GLOB(3)

名称
glob, globfree

ライブラリ
libc - パターンに適合するパス名を生成

書式
#include <glob.h> int glob(const char *pattern, int flags, int (*errfunc)(const char *, int), glob_t *pglob) void globfree(glob_t *pglob)

解説
glob() 関数は、シェルによって使用されるファイル名パターンの、適合規則を 実装するパス名ジェネレータです。

インクルードファイル glob.h は、少なくとも次に示すフィールドが含まれる 構造体タイプ glob_t を定義します。

    typedef struct {
            int gl_pathc;           /* これまでの合計パスカウント */
            int gl_matchc;          /* パターンに適合するパスカウント */
            int gl_offs;            /* gl_pathvの最初に予約されるフィールド */
            int gl_flags;           /* 返されるフラグ */
            char **gl_pathv;        /* パターンに適合するパスのリスト */
    } glob_t;

引数 pattern は展開するパス名パターンのポインタです。 glob() 引数はその パターンに対して、アクセス可能なすべてのパス名を突き合わせ (マッチング)、 適合するパス名リストを作成します。パス名にアクセスするため glob() は、パス の各構成要素 (最終要素を除く) での検索許可と、特殊キャラクタ ‘*’, ‘’? または ‘[’ などを含む pattern の、すべてのファイル名構成要素ディレクトリの読み 込み許可を要求します。

glob() 引数は、適合パス名の数を gl_pathc フィールドに、パス名ポインタリスト のポインタを gl_pathv フィールドにそれぞれ保存します。最終パス名の後の 最初のポインタは NULL です。パターンに適合するパス名が皆無だった場合、 返される適合パスの数は 0 に設定されます。

pglob で示される構造体は呼び出し元が作成します。 gl_pathv で示されるメモリ などほかの空間は、 glob() 関数が必要に応じて割り振ります。

引数 flags は、 glob() の挙動を変更するために使用します。 flags の値は、 glob.h で定義されている次に示す値のそれぞれビットごとの包括的 OR です。

GLOB_APPEND
    生成されたパス名を、 glob() に対する前の呼び出し (単数または複数) で生成されたパス名に追加します。 gl_pathc の値は、今回の呼び出しおよび前の呼び出し (単数または複数) での、 適合パス名の合計になります。前の呼び出し (単数または複数) によって 返されたパス名に、今回生成されたパス名が追加されますが、 マージ (併合) はされません。前の呼び出しと今回の呼び出しのあいだに、 呼び出し元は GLOB_DOOFFS フラグを変えてはいけません。同様に、 GLOB_DOOFFS 設定時の gl_offs の値も変えてはいけません。 (もちろん) pglob に影響する globfree() の呼び出しも行ってはなりません。

GLOB_DOOFFS
    gl_offs フィールドを有効にします。このフラグを設定すると、 gl_pathv フィールドの前に付加する NULL ポインタの数が、 gl_offs によって指定できます。言い換えれば gl_pathv が gl_offs の NULL ポインタを示し、その後に gl_pathc パス名ポインタが続き、さらにその後に NULL ポインタが続きます。

GLOB_ERR
    オープンまたは読み込みできないディレクトリに出会った場合、 glob() をリターンさせます。通常は、 glob() が適合パス名検索を続行します。

GLOB_MARK
    pattern に適合するディレクトリの各パス名に、スラッシュを 付加します。

GLOB_NOCHECK
    pattern に適合するパス名が皆無だった場合、 glob() は pattern だけで構成されるリストを返します。パス名の合計数は 1 に、適合 パス名の数は 0 に設定されます。 GLOB_QUOTE が設定されていれば、返されるパターンにその効果が反映されます。

GLOB_NOSORT
    デフォルトでパス名は ASCII 昇順にソートされます。このフラグはそうしたソート、すなわち高速化 glob() 機能を妨げます。

次に示す値も flags に含まれることはありますが、これらは p1003.2 の非標準拡張です。

GLOB_ALTDIRFUNC
    pglob 構造体の次に示す追加フィールドを、ディレクトリのオープン、読み込み、 クローズおよび、それらディレクトリで見付かったパス名のステータス情報取得に 使用する、代替 glob 関数で初期化します。

        void *(*gl_opendir)(const char * name);
        struct dirent *(*gl_readdir)(void *);
        void (*gl_closedir)(void *);
        int (*gl_lstat)(const char *name, struct stat *st);
        int (*gl_stat)(const char *name, struct stat *st);

    テープに保存されたディレクトリから、 restore(8) のようなプログラムによって グロッビング (ファイル名展開) できるように、 この拡張が用意されています。

GLOB_BRACE
    csh(1) のような ‘{pat,pat,...}’ ストリングを展開するために、 パターンストリングを前処理します。パターン ‘{}’ は歴史的理由 (および find(1) パターンの入力を容易にするために、 csh(1) が同じことをするという理由) から、未展開のまま残されます。

GLOB_MAGCHAR
    パターンに glob() 用キャラクタが含まれていると、 glob() 関数によってこのフラグが設定されます。詳細は gl_matchc 構造体メンバの、用法についての説明を参照してください。

GLOB_NOMAGIC
    GLOB_NOCHECK と同じですが、特殊キャラクタ ``*'', ``?'' または ``['' がなにも含まれていない場合に、このフラグはただ pattern を後に付加するだけです。 GLOB_NOMAGIC は、歴史的な csh(1) によるグロッビング (ファイル名展開) 挙動の実装を単純化するために 用意されています。その他の目的ではたぶん、 どんな場合も使用すべきではありません。

GLOB_QUOTE
    バックスラッシュ (‘\’) キャラクタを引用符として 有効にします。パターンにバックスラッシュとそれに続くキャラクタがある場合、 そのキャラクタを特別に解釈することなくそのままのキャラクタとして 置換します。

GLOB_TILDE
    ‘~’ で始まるパターンを、ユーザ名のホームディレクトリに 展開します。

GLOB_LIMIT
    返されるパス名の合計数を、 gl_matchc で指定される数に制限します (デフォルトは ARG_MAX) です。 非常に大きな数のマッチに展開される ‘*/../*/..’ のような長いストリングのパターンによって、 サービス拒否攻撃に無理矢理されてしまい得るプログラムに対し、 本オプションを設定すべきです。

検索においてオープンまたは読み込みできないディレクトリに出会った場合、 errfunc が NULL でなければ、 glob() は (*errfunc)(path, errno) を呼び出します。 これは非直観的な場合があります。 ‘*/Makefile’ のようなパターンでは、 ‘foo’ が ディレクトリでなくても ‘foo/Makefile’ の stat(2) が試みられて、 errfunc を 呼び出す結果になるからです。 ENOENT および ENOTDIR のテストによって、 エラールーチンはこの動作を抑制することができますが、 それでもなおこうした場合には GLOB_ERR フラグがただちに glob() をリターンさせます。

errfunc から非 0 が返ると glob() は操作を停止して、すでに適合したすべての パスを反映するために、 gl_pathc および gl_pathv を設定した後で GLOB_ABEND を返します。 エラーが起こり flags に GLOB_ERR が設定されていれば、 errfunc を呼び出した場合その戻り値に関係なく、同じことが起こります。 GLOB_ERR を未設定で、 errfunc が NULL かまたは errfunc が 0 を返した場合、エラーは無視されます。

globfree() 関数は、前の glob() 呼び出しによって pglob と 関連した、すべての空間を解放します。

戻り値
無事に完了した場合 glob() は 0 を返します。さらに、 pglob の各フィールド には次に示す値が含まれます。

gl_pathc
    これまでの適合パス名の合計数が含まれます。 GLOB_APPEND が指定されている場合は、前の glob() 起動で得られたほかの適合パス名の数も、 この合計には含れます。

gl_matchc
    現在の glob() 起動によって得られた適合パス名の数が 含まれます。

gl_flags
    pattern に特殊キャラクタ ``*'', ``?'', または ``['' のどれかが含まれている場合は、 GLOB_MAGCHAR が設定したビットを持つ flags パラメータの コピーが含まれます。特殊キャラクタが含まれていない場合、このフィールドの 内容はクリアされます。

gl_pathv
    適合パス名の NULL で終わるリストのポインタが含まれます。 ただし、もし gl_pathc が 0 ならば、 gl_pathv の内容は定義されません。

エラーのため終了すると glob() は errno を設定して、次に示す非 0 定数の 1 つを返します。これらの定数は、インクルードファイル <glob.h> で定義されます。

GLOB_NOSPACE
    メモリ割り当ての試みが失敗しました。 もしくは errno が 0 の場合、 GLOB_LIMIT が flags に指定され、 pglob->gl_matchc 個またはそれ以上のパターンがマッチしました。

GLOB_ABEND
    エラーが発生した上に GLOB_ERR が設定されていたか、または *errfunc が非 0 を返したので、 glob() はパス名の走査を停止しました。

引数 pglob->gl_pathc および pglob->gl_pathv は依然として、上で 指定のとおりに設定されたままです。

例
‘ls -l *.c *.h’ の大体の等価は、次に示すコードで取得することができます。

    glob_t g;
    g.gl_offs = 2;
    glob("*.c", GLOB_DOOFFS, NULL, &g);
    glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
    g.gl_pathv[0] = "ls";
    g.gl_pathv[1] = "-l";
    execvp("ls", g.gl_pathv);

関連項目
sh(1), fnmatch(3), regexp(3)

規格
glob() 関数には次に示す例外を除いて、 p1003.2 との互換性が期待されています。例外はフラグ GLOB_ALTDIRFUNC, GLOB_BRACE, GLOB_LIMIT, GLOB_MAGCHAR, GLOB_NOMAGIC, GLOB_QUOTE, GLOB_TILDE それにフィールド gl_matchc および gl_flags などを、厳正な POSIX 適合を争うアプリケーションでは使用すべきではないということです。

歴史
glob() および globfree() 関数は、 4.4BSD ではじめて登場しました。

バグ
MAXPATHLEN よりも長いパターンは、無検査エラーの原因となる可能性があります。

glob() 引数は失敗して、ライブラリルーチン stat(2), closedir(3), opendir(3), readdir(3), malloc(3), および free(3) 用に指定したエラーのどれかに、errno を設定することがあります。