書式

#include <glob.h>

---

int glob(const char *pattern, int flags,
int (*errfunc) (const char *epath, int eerrno),
glob_t *pglob);
void globfree(glob_t *pglob);

説明

glob() 関数はシェルが用いているルール (glob(7) 参照) に基づいてパターン pattern にマッチするすべてのパス名を検索する。 チルダ (~) の展開やパラメータ置換は行われない。それらを行いたい場合は wordexp(3) を使うとよい。

globfree() 関数は前に呼ばれた glob() により動的に確保された記憶領域を解放する。

glob() の結果は pglob がポイントする構造体に返される。 pglob は glob_t 型の構造体である。 glob_t 型は <glob.h> 内で宣言されており、以下の要素を含んでいる。これらの要素は POSIX.2 で定義 されている (さらに多くの要素が拡張として入っているかもしれない)。

typedef struct {
    size_t   gl_pathc;    /* 今までにマッチしたパスの数 */
    char   **gl_pathv;    /* マッチしたパス名のリスト */
    size_t   gl_offs;     /* gl_pathv 内に確保するスロット数 */
} glob_t;

結果は動的に確保された記憶領域に入れられる。

パラメータ flags には以下の示す定数のうち、指定したいものをビットごとの OR で与える (一つも 指定しなくてもよい)。これによって glob() の動作を変更できる。

GLOB_ERR

(例えば、ディレクトリに読み取り許可属性が無い場合などで) 読み取りエラーが発生した際に関数から戻る。 デフォルトでは、エラーに関わらず 読み取り可能なディレクトリを全てについて読み取りを実行しようとする。

GLOB_MARK

ディレクトリに対応する各々のパスにスラッシュを付加する。

GLOB_NOSORT

返されるパス名のソートを行わない。 ソートを行わない理由は、処理時間を節約するためだけである。 デフォルトでは、返されるパス名はソートされる。

GLOB_DOOFFS

pglob->pathv の文字列リストの先頭に pglob->gl_offs スロット分の領域を予約する。 予約されたスロットにはヌルポインタが入る。

GLOB_NOCHECK

マッチするパターンがなければ、元のパターンを返す。 デフォルトでは、 glob() はマッチするパターンがなければ GLOB_NOMATCH を返す。

GLOB_APPEND

この呼び出しでの結果を直前の glob() の呼び出しで返された結果のベクトルに追加する。最初の glob() の呼び出しの際にはこのフラグを設定してはいけない。

GLOB_NOESCAPE

バックスラッシュ ('\') をエスケープ用文字として使用できない。 通常は、バックスラッシュを使って、次に続く文字をクォートすることで、 特別な意味を持つメタキャラクタを無効することができる。

flags には以下に示すものも指定できる。 これらは GNU で拡張されたもので、POSIX.2 では定義されていない。

GLOB_PERIOD

先頭のピリオドがメタキャラクタにマッチできるようにする。 デフォルトでは、メタキャラクタは先頭のピリオドにはマッチできない。

GLOB_ALTDIRFUNC

ファイルシステムにアクセスする際に、通常のライブラリ関数の代わりに 代替関数 pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat, pglob->gl_stat が用いられる。

GLOB_BRACE

{a,b} という形式の csh(1) スタイルの括弧表現を展開する。 括弧表現は入れ子にすることができる。 したがって、例えば、"{foo/{,cat,dog},bar}" というパターンを 指定した場合に得られる結果は、 4つの文字列 "foo/", "foo/cat", "foo/dog", "bar" のそれぞれについて glob() を呼び出した場合と同じになる。

GLOB_NOMAGIC

パターンにメタキャラクタが含まれていない場合、 マッチ結果として指定されたパターンだけを返す。 パターンで指定された名前のファイルが存在しない場合であっても、 そのパターンが返される。

GLOB_TILDE

チルダの展開を行う。 チルダ ('~') がパターン内の唯一の文字の場合か、先頭のチルダの直後の文字が スラッシュ ('/') の場合、チルダを呼び出し者のホームディレクトリで置換する。 先頭のチルダにユーザ名が続く場合 (例えば "~andrea/bin")、 チルダとユーザ名をそのユーザのホームディレクトリで置換する。 ユーザ名が無効な場合やホームディレクトリが決定できない場合は、 置換は実行されない。

GLOB_TILDE_CHECK

このフラグを指定すると GLOB_TILDE と同様の振舞いをする。 GLOB_TILDE との違いは、ユーザ名が無効だった場合や ホームディレクトリが決定できなかった場合に、 パターン自身を使用するのではなく、 glob() がエラーを示す GLOB_NOMATCH を返すことである。

GLOB_ONLYDIR

このフラグは、 glob() に対する「ヒント」であり、 呼び出し側がパターンにマッチするディレクトリにしか興味がないことを知らせる。 実装においてファイルの種別情報を簡単に決定できる場合は、ディレクトリでない ファイルは呼び出し側に返されない。しかしながら、呼び出し側では、返された ファイルリストがディレクトリかどうかを確認しなければならない。 (このフラグが存在するのは、呼び出し側がディレクトリにしか興味がない際に 性能を最適化する目的のためだけである。)

errfunc が NULL でなければ、 エラーが起こった場合には関数 errfunc が呼び出される。関数の引数には、失敗したパス名 epath と errno (opendir(3), readdir(3), stat(2). のいずれかによってセットされた値) が与えられる。 errfunc が 0 以外の値を返すかもしくは GLOB_ERR がセットされた場合 glob() は errfunc の呼び出し後に終了する。

呼び出しが成功して戻った場合 pglob->gl_pathc にはマッチしたパス名が含まれ、 pglob->gl_pathv はマッチしたパス名へのポインタのリストへのポインタとなる。 ポインタのリストはヌルポインタで終端される。

glob() を何度か続けて呼び出すことができる。その際2回目以降の呼び出しでは GLOB_APPEND フラグが flags に設定されていなければならない。

GNU の拡張として、 pglob->gl_flags には指定したフラグがセットされる。もし一つでもメタキャラクタが見付かれば このフラグと GLOB_MAGCHAR との OR を取った結果がセットされる。

返り値

呼び出しが成功して完了すると glob() は 0 を返す。 それ以外の返り値は以下の通り:

GLOB_NOSPACE

メモリを使い果たした

GLOB_ABORTED

読み取りエラー

GLOB_NOMATCH

一つもマッチしなかった

準拠

POSIX.2, POSIX.1-2001.

注意

glibc 2.1 では、 gl_pathc と gl_offs は POSIX.2 で指定されているように size_t として宣言されている。 libc4, libc5, glibc 2.0 では、 int として宣言されている。

例

使用法の一例を以下に示す。以下はシェルで

ls -l *.c ../*.c

をタイプした場合をシミュレートしている。

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

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。