glob() - パターンと一致するパス名の生成

標準

標準/拡張機能 C/C++ 依存項目

XPG4
XPG4.2
Single UNIX Specification、バージョン 3

 両方  

形式

#define _XOPEN_SOURCE
#include <glob.h>

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

機能説明

glob() 関数は、「 X/Open CAE Specification, Commands and Utilities, Issue 4, Version 2 」のパターン・マッチング表記に関するトピックで定義されている規則を実装するパス名生成関数であり、ファイル名拡張に使用されるパターンに関するトピックの規則 3 をオプションでサポートします。

構造体 glob_t はヘッダー <glob.h> で定義されます。次のメンバーは必ず設定されます。
gl_pathc
pattern と一致するパスの数。
gl_pathv
一致したファイル名のリストへのポインター。
gl_offs
gl_pathv の先頭で予約するスロット。
引数 pattern は、拡張されたパス名パターンへのポインターです。glob() 関数は、すべてのアクセス可能なパス名を、このパターンと 突き合わせ、一致したすべてのパス名のリストを作成します。パス名にアクセスするには、最後のコンポーネントを除くパスの すべてのコンポーネントでの検索許可と、以下の特殊文字を含む pattern の ファイル名コンポーネントの各ディレクトリーでの読み取り許可が glob() から要求されます。
        *        ?        [

glob() 関数は、一致したパス名の数を pglob->gl_pathc に保管し、パス名へのポインターのリストへのポインターを pglob->gl_pathv に保管します。パス名は、LC_COLLATE カテゴリーの現行の設定によって定義されているソート順になっ ています。「 X/Open CAE Specification, System Interface Definitions, Issue 4, Version 2 」の トピック『LC_COLLATE』を参照してください。 最後のパス名の後の最初のポインターは NULL ポインターになります。パターンがいずれのパス名とも一致しない場合は、一致したパス数の戻り値 は 0 に設定されます。pglob->gl_pathv の内容は、設定によって異なります。

pglob によって指定される構造体を作成するのは、呼び出し側 の責任です。glob() 関数は、gl_pathv で指定される メモリーを含む別のスペースを必要なだけ割り振ります。

flags 引数は、glob() の動作を制御する場合に使用します。flags の値は、以下の定数 (0 または複数個) のビット単位包含 OR (包含論理和) です。これらの定数はヘッダー <glob.h> で 定義されます。
GLOB_APPEND
生成されたパス名を glob() の以前の呼び出しからのパス名に 追加する。
GLOB_DOOFFS
pglob->gl_offs を使用する。このフラグが設定されている場合は、pglob->gl_offs を使用して、pglob->gl_pathv の先頭に追加する NULL ポインターの数を指定することができる。つまり、pglob->gl_pathv は、pglob->gl_offs NULL ポインターを指し、次に pglob->gl_pathc パス名ポインター、そのあとに NULL ポインターというように指す。
GLOB_ERR
glob() でオープンも読み取りもできないディレクトリーを検出した場合、glob() に戻りを実行させる。通常、glob() により突き合わせの検索が継続される。
GLOB_MARK
ディレクトリーが pattern と一致する各パス名は、後ろにスラッシュが付け加えられる。
GLOB_NOCHECK
「XCU 仕様」の トピックのファイル名拡張に使用されるパターンの規則 3 をサポートする。pattern がいずれのパス名とも一致しない場合は、glob() により pattern だけで構成されるリストが戻される。一致したパス名の数は 1 になる。
GLOB_NOESCAPE
バックスラッシュのエスケープを使用不可にする。
GLOB_NOSORT
通常、glob() は、LC_COLLATE カテゴリーの現行の設定に従って、一致したパス名をソートする。「XBD 仕様」の トピック『LC_COLLATE』を参照。このフラグが使用されると、戻されたパス名の順は未指定である。
GLOB_APPEND フラグを使用すると、glob() の以前の呼び出しで検出されたパス名に新規のパス名のセットを追加することができます。以下の規則が適用されるのは、2 つ以上の glob() 呼び出しが、pglob の同じ値で、globfree() 呼び出し介入なしに行われる場合です。
  1. 最初のそのような呼び出しは、GLOB_APPEND を設定すべきではない。2 回目以降のすべての呼び出しでは、これを設定しなければ なりません。
  2. すべての呼び出しは GLOB_DOOFFS を設定するか、または設定すべきでは ない。
  3. 2 番目の呼び出しのあと、pglob->gl_pathv は、以下を含むリストを指す。
    1. ゼロまたは複数個の NULL ポインター。GLOB_DOOFFS および pglob->gl_offs の指定による。
    2. 以前と同じ順で、呼び出し前に pglob->gl_pathv リスト内 にあるパス名へのポインター。
    3. 指定された順で、2 番目の呼び出しによって生成された新規のパス名へのポ インター。
  4. pglob->gl_pathc で戻された数は、2 つの呼び出しからの パス名の総数である。
  5. アプリケーションは、glob() の呼び出し後、任意のフィールドを変更できる。その場合、後続の呼び出しの前に、同じ pglob 値を globfree() に、または GLOB_APPEND フラグが設定されている glob() へ使用して、それらを元の値にリセットしておく必要がある。
検索中に、オープンも読み取りもできないディレクトリーが検出され、さらに errfunc が NULL ポインターでない場合は、glob() は以下の 2 つ の引数を指定した (*errfunc()) を呼び出します。
  1. epath 引数は失敗したパスへのポインターである。
  2. eerrno 引数は、opendir()、readdir()、または stat() で設定 されたように、失敗した場合の errno の値である(この関数では明示的に述べられていない別のエラーを報告するために、別の値が 使用されることもある)。

戻り値

正常に実行された場合、glob() は 0 を戻します。引数 pglob->gl_pathc は、一致したパス名の数を戻し、引数 pglob->gl_pathv には一致してソートされたパス名の NULL 終了リストへのポインターが含まれます。しかし、pglob->gl_pathc が 0 の場合、pglob->gl_pathv の内容は、未定義です。

glob() がエラーのために終了する場合は、glob() のエラー戻り値 として、<glob.h> で定義されている以下のゼロ以外の定数のいずれかが戻されます。
GLOB_ABORTED
GLOB_ERR が設定されたか、または (*errfunc()) がゼロ以外の値を戻したため、走査は停止されました。
GLOB_NOMATCH
パターンがどの既存のパス名とも一致せず、GLOB_NOCHECK が flags に設定されました。
GLOB_NOSPACE
メモリーの割り振りに失敗しました。

(*errfunc()) が呼び出され、ゼロ以外の値を戻す場合、または GLOB_ERR フラグが flags に設定される場合は、glob() は走査を停止し、既に走査したパスを反映させるために、gl_pathc および gl_pathv を pglob に設定してから、GLOB_ABORTED を戻します。GLOB_ERR が設定されず、errfunc が NULL ポインターであるか、または (*errfunc()) が 0 を戻す場合は、エラーは無視されます。

関連情報

親トピック: ライブラリー関数