Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       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 がポイントする構造体に返される。 pglobglob_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 が呼び出される。関数の引
       数には、失敗したパス名  epatherrno (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_pathcgl_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/ に書かれている。