globfree(3)

glob, globfree

標準 C ライブラリ (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() に対する前の呼び出し (単数ま たは複数) で生成されたパス名に追加します。 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 に含まれることはありますが、これらは 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) のような プログラムによってグロッビング (ファイル名展開) できるよ うに、この拡張が用意されています。

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 の各フィールド には次に示す値が含まれます。

これまでの適合パス名の合計数が含まれます。 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() 関数は、 4.4BSD ではじめて登場しました。

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

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

FreeBSD 10.0 April 16, 1994 FreeBSD 10.0