名称

glob, globfree — パターンマッチング (照合) パス名を生成する

ライブラリ

Standard C Library (libc, -lc)

書式

#include < glob.h>

int
glob( const char * restrict pattern, int flags, int (*errfunc)(const char *, int), glob_t * restrict pglob);

void
globfree( glob_t *pglob);

解説

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

インクルードファイル < glob.h> は、少なくとも次のフィールドをんでいる構造体タイプ glob_t を定義します。

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

引数 pattern は、展開するパス名パターンへのポインタです。 glob() 引数は、パターンとアクセス可能なパス名をすべてマッチ (照合) して、一致するパス名のリストを作成します。パス名にアクセスするために glob() は、最後を除いてパスのすべての構成要素について検索許可と特別の文字‘ *’, ‘ ?’または‘ [’のどれでも含んでいる pattern の任意のファイル名の構成要素の各ディレクトリについて読み込み許可を要求します。

glob() 引数は、一致したパス名の数を gl_pathc フィールドに、パス名へのポインタのリストへのポインタを gl_pathv フィールドに格納します。最終パス名の後の最初のポインタは、 NULL です。パターンがパス名と一致しない場合、一致したパスの返された数は、0 に設定されます。

pglob によって指される構造体を作るのは呼び出し側の責任です。 glob() 関数は、 gl_pathv によって指されるメモリを含んで必要に応じて他の空間を割り付けます。

引数 flags は、 glob() の振る舞いを修正るために使用されます。 flags の値は、 < glob.h> で定義された次の値のうちのビットごとの包含的 OR です。

GLOB_APPEND

glob() への前の呼び出し (単数または複数) からのものに生成されたパス名を追加します。 gl_pathc の値は、この呼び出しおよび前の呼び出し (単数または複数) によって見つかった一致の合計になります。パス名は、前の呼び出し (単数または複数) によって返されたパス名にマージ (併合) されるのではなく、追加されます。呼び出しの間に、呼び出し側は、 GLOB_DOOFFS フラグの設定を変更してはいけませんし、 GLOB_DOOFFS が設定される時 gl_offs の値を変更してはいけません。そしてまた pglob のための globfree() の (明白な) 呼び出しを行ってはいけません。

GLOB_DOOFFS

gl_offs フィールドを使用します。このフラグを設定される場合、 gl_offs は、 gl_pathv フィールドの始めにいくつの NULL ポインタを付加するかを指定するために使われます。言いかえれば gl_pathv は、 gl_offs NULL ポインタを指し、後に gl_pathc パス名ポインタが続き、さらに後に NULL ポインタが続きます。

GLOB_ERR

オープンまたは読み込みできないディレクトリに出会った時、 glob() を返らせます。通常は、 glob() は、一致を見つけるために継続します。

GLOB_MARK

pattern に一致するディレクトリであるパス名ごとにスラッシュを追加します。

GLOB_NOCHECK

pattern がパス名と一致しない場合、 glob() は、パス名の合計数は、1 に設定され、一致したパス名の数は、0 に設定される、 pattern のみで構成されるリストを返します。バックスラッシュを回避する効果は、返されたパターンの中にあります。

GLOB_NOESCAPE

デフォルトでは、バックスラッシュ (‘ \’) 文字は、文字のどんな特別の解釈も回避して、パターン中の続く文字を回避するために使用されます。 GLOB_NOESCAPE が設定される場合、バックスラッシュ回避は、無効になります。

GLOB_NOSORT

デフォルトでは、パス名は、 ASCII 昇順でソートされます。このフラグは、そのようなソートを防ぎます ( glob() の高速化)。

次の値もまた flags に含まれているかもしれません。しかしながら、それらは、 IEEE Std 1003.2 (“POSIX.2”) の非標準の拡張です。

GLOB_ALTDIRFUNC

pglob 構造体の次の追加フィールドは、ディレクトリをオープン、読み込み、クローズおよび、それらディレクトリで見つかった名前の stat (ステータス) 情報を取得するために使用する 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) のようなプログラムがテープに格納されたディレクトリから (globbing) グロッビング (ファイル名置換) を提供することを可能にするために提供されます。

GLOB_BRACE

csh(1) のような‘ {pat,pat,...}’文字列を展開するためにパターン文字列を前処理します。パターン‘ {}’は、歴史的理由 (そして csh(1) は、 find(1) パターンのタイプを容易にするために、同じことを行ないます) のため未展開のまま残されます。

GLOB_MAGCHAR

パターンにグロッビング (ファイル名置換) 文字が含まれている場合、 glob() 関数によって設定されます。より詳細については、 gl_matchc 構造体メンバの使用法ついての説明を参照してください。

GLOB_NOMAGIC

GLOB_NOCHECK と同じですが、特別の文字 ``*'', ``?'' または ``['' のうちのどれも含んでいない場合、 pattern を追加するのみです。 GLOB_NOMAGIC は、歴史的な csh(1) のグロッビング (ファイル名置換) の振る舞いの実装を単純化するために提供されます。また、他のいかなる場所でも使用されてはなりません。

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 フラグは、ただちに返ることになります。

errfunc が非 0 で返る場合、 glob() は、スキャンを停止して、すでに一致したすべてのパスを反映するために、 gl_pathc および gl_pathv を設定した後に GLOB_ABORTED を返します。エラーに遭遇し GLOB_ERR が flags に設定されている場合、もし呼び出されたなら、 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_ABORTED

エラーに遭遇し GLOB_ERR が設定されたか、あるいは (*errfunc)() が 0 でなくて返ったかのどちらかだったので、スキャンは、停止されました。

GLOB_NOMATCH

パターンは、パス名と一致しませんでした。また、 GLOB_NOCHECK は、設定されませんでした。

引数 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), regex(3)

規格

glob() 関数の現在の実装は、 IEEE Std 1003.2 (“POSIX.2”) に適合して いません。 シンボル式の照合、同値類式、文字クラス式は、サポートされていません。

フラグ GLOB_ALTDIRFUNC, GLOB_BRACE, GLOB_LIMIT, GLOB_MAGCHAR, GLOB_NOMAGIC, 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 に設定されます。