tail head cat sleep
QR code linking to this page

manページ  — GLOB

名称

glob, globfree

内容

ライブラリ

Standard C Library (libc, -lc)– パターンに適合するパス名を生成

書式


#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_pathvgl_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 に含まれることはありますが、これらは IEEE Std 1003.2 ("POSIX.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() 関数には次に示す例外を除いて、 IEEE Std 1003.2 ("POSIX.2") との互換性が期待されています。例外はフラグ GLOB_ALTDIRFUNC, GLOB_BRACE, GLOB_LIMIT, GLOB_MAGCHAR, GLOB_NOMAGIC, GLOB_QUOTE, GLOB_TILDE それにフィールド gl_matchc および gl_flags などを、厳正な POSIX 適合を争うアプリケーションでは使用すべきではないということです。

歴史

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

バグ

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

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


GLOB (3) April 16, 1994

tail head cat sleep
QR code linking to this page


このマニュアルページサービスについてのご意見は Ben Bullock にお知らせください。

Using Unix is the computing equivalent of listening only to music by David Cassidy
— Rob Pike