Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
glob, globfree - パターンにマッチするパス名を見付ける。glob() によっ て確保されたメモリー領域を解放する。
書式
#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
一つもマッチしなかった
属性
この節で使用されている用語の説明については、 attributes(7) を参照。
┌─────────────────┬───────────────┬──────────────────────────┐
│インターフェース │ 属性 │ 値 │
├─────────────────┼───────────────┼──────────────────────────┤
│glob() │ Thread safety │ MT-Unsafe race:utent env │
│ │ │ sig:ALRM timer locale │
├─────────────────┼───────────────┼──────────────────────────┤
│globfree() │ Thread safety │ MT-Safe │
└─────────────────┴───────────────┴──────────────────────────┘
In the above table, utent in race:utent signifies that if any of the functions setutent(3), getutent(3),
or endutent(3) are used in parallel in different threads of a program, then data races could occur.
glob() calls those functions, so we use race:utent to remind users.
準拠
POSIX.1-2001, POSIX.1-2008, POSIX.2.
注意
glibc 2.1 では、 gl_pathc と gl_offs は POSIX.2 で指定されているように size_t として宣言されている。
glibc 2.0 では、 int として宣言されている。
バグ
glob() 関数はその中で呼び出している malloc(3) や opendir(3) などの関数の呼び出しで失敗が起こると失敗す
る。 これにより errno にそのエラーコードが入る。
例
使用法の一例を以下に示す。以下はシェルで
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]);
関連項目
ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告
に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。