GLOB

Section: C Library Functions (3)
索引 jman

BSD mandoc

索引

名称

glob globfree

索引

ライブラリ

Lb libc - パターンに適合するパス名を生成

索引

書式

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

索引

解説

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

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

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

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

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

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

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

GLOB_APPEND: 生成されたパス名を、 Fn glob に対する前の呼び出し (単数または複数) で生成されたパス名に追加します。 Fa gl_pathc の値は、今回の呼び出しおよび前の呼び出し (単数または複数) での、適合パス名の合計になります。前の呼び出し (単数または複数) によって返されたパス名に、今回生成されたパス名が追加されますが、マージ (併合) はされません。前の呼び出しと今回の呼び出しのあいだに、呼び出し元は GLOB_DOOFFS フラグを変えてはいけません。同様に、 GLOB_DOOFFS 設定時の Fa gl_offs の値も変えてはいけません。 (もちろん) Fa pglob に影響する Fn globfree の呼び出しも行ってはなりません。
GLOB_DOOFFS: Fa gl_offs フィールドを有効にします。このフラグを設定すると、 Fa gl_pathv フィールドの前に付加する NULL ポインタの数が、 Fa gl_offs によって指定できます。言い換えれば Fa gl_pathv が Fa gl_offs の NULL ポインタを示し、その後に Fa gl_pathc パス名ポインタが続き、さらにその後に NULL ポインタが続きます。
GLOB_ERR: オープンまたは読み込みできないディレクトリに出会った場合、 Fn glob をリターンさせます。通常は、 Fn glob が適合パス名検索を続行します。
GLOB_MARK: Fa pattern に適合するディレクトリの各パス名に、スラッシュを付加します。
GLOB_NOCHECK: Fa pattern に適合するパス名が皆無だった場合、 Fn glob は Fa pattern だけで構成されるリストを返します。パス名の合計数は 1 に、適合パス名の数は 0 に設定されます。 GLOB_QUOTE が設定されていれば、返されるパターンにその効果が反映されます。
GLOB_NOSORT: デフォルトでパス名は ASCII 昇順にソートされます。このフラグはそうしたソート、すなわち高速化 Fn glob 機能を妨げます。

次に示す値も Fa flags に含まれることはありますが、これらは St -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

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

GLOB_NOMAGIC

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

GLOB_QUOTE

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

GLOB_TILDE

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

GLOB_LIMIT

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

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

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

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

索引

戻り値

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

Fa gl_pathc: これまでの適合パス名の合計数が含まれます。 GLOB_APPEND が指定されている場合は、前の Fn glob 起動で得られたほかの適合パス名の数も、この合計には含れます。
Fa gl_matchc: 現在の Fn glob 起動によって得られた適合パス名の数が含まれます。
Fa gl_flags: Fa pattern に特殊キャラクタ ``*'', ``?'', または ``['' のどれかが含まれている場合は、 GLOB_MAGCHAR が設定したビットを持つ Fa flags パラメータのコピーが含まれます。特殊キャラクタが含まれていない場合、このフィールドの内容はクリアされます。
Fa gl_pathv: 適合パス名の NULL で終わるリストのポインタが含まれます。ただし、もし Fa gl_pathc が 0 ならば、 Fa gl_pathv の内容は定義されません。

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

GLOB_NOSPACE: メモリ割り当ての試みが失敗しました。もしくは Fa errno が 0 の場合、 GLOB_LIMIT が flags に指定され、 Fa pglob->gl_matchc 個またはそれ以上のパターンがマッチしました。
GLOB_ABEND: エラーが発生した上に GLOB_ERR が設定されていたか、または Fa *errfunc が非 0 を返したので、 Fn glob はパス名の走査を停止しました。

引数 Fa pglob->gl_pathc および Fa 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);

索引

規格

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

索引