release/man3/glob.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\" License.
  23 .\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu)
  24 .\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de)
  25 .\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  26 .\" Modified 990912 by aeb
  27 .\" 2007-10-10 mtk
  28 .\"     Added description of GLOB_TILDE_NOMATCH
  29 .\"     Expanded the description of various flags
  30 .\"     Various wording fixes.
  31 .\"
  32 .\" Japanese Version Copyright (c) 1998 Ken Wakasa all rights reserved.
  33 .\" Translated 1998-06-24, Ken Wakasa <wakasa@iname.com>
  34 .\" Updated 1999-01-04, Kentaro Shirakata <argrath@yo.rim.or.jp>
  35 .\" Updated 2008-02-12, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
  36 .\"
  37 .TH GLOB 3  2007-10-10 "GNU" "Linux Programmer's Manual"
  38 .SH 名前
  39 glob, globfree \- パターンにマッチするパス名を見付ける。glob() によっ
  40 て確保されたメモリ領域を解放する。
  41 .SH 書式
  42 .nf
  43 .B #include <glob.h>
  44 .sp
  45 .BI "int glob(const char *" pattern ", int " flags ,
  46 .br
  47 .BI "         int (*" errfunc ") (const char *" epath ", int " eerrno ),
  48 .br
  49 .BI "         glob_t *" pglob );
  50 .br
  51 .BI "void globfree(glob_t *" pglob );
  52 .fi
  53 .SH 説明
  54 .BR glob ()
  55 関数はシェルが用いているルール
  56 .RB ( glob (7)
  57 参照) に基づいてパターン
  58 .I pattern
  59 にマッチするすべてのパス名を検索する。
  60 チルダ (~) の展開やパラメータ置換は行われない。それらを行いたい場合は
  61 .BR wordexp (3)
  62 を使うとよい。
  63 .PP
  64 .BR globfree ()
  65 関数は前に呼ばれた
  66 .BR glob ()
  67 により動的に確保された記憶領域を解放する。
  68 .PP
  69 .BR glob ()
  70 の結果は
  71 .I pglob
  72 がポイントする構造体に返される。
  73 .I pglob
  74 は
  75 .I glob_t
  76 型の構造体である。
  77 .I glob_t
  78 型は
  79 .I <glob.h>
  80 内で宣言されており、以下の要素を含んでいる。これらの要素は POSIX.2 で定義
  81 されている (さらに多くの要素が拡張として入っているかもしれない)。
  82 .PP
  83 .br
  84 .in +4n
  85 .nf
  86 typedef struct {
  87     size_t   gl_pathc;    /* 今までにマッチしたパスの数 */
  88     char   **gl_pathv;    /* マッチしたパス名のリスト */
  89     size_t   gl_offs;     /* \fIgl_pathv\fP 内に確保するスロット数 */
  90 } glob_t;
  91 .fi
  92 .in
  93 .PP
  94 結果は動的に確保された記憶領域に入れられる。
  95 .PP
  96 パラメータ
  97 .I flags
  98 には以下の示す定数のうち、指定したいものをビットごとの OR で与える
  99 (一つも
 100 指定しなくてもよい)。これによって
 101 .BR glob ()
 102 の動作を変更できる。
 103 .TP
 104 .B GLOB_ERR
 105 (例えば、ディレクトリに読み取り許可属性が無い場合などで)
 106 読み取りエラーが発生した際に関数から戻る。
 107 デフォルトでは、エラーに関わらず
 108 読み取り可能なディレクトリを全てについて読み取りを実行しようとする。
 109 .TP
 110 .B GLOB_MARK
 111 ディレクトリに対応する各々のパスにスラッシュを付加する。
 112 .TP
 113 .B GLOB_NOSORT
 114 返されるパス名のソートを行わない。
 115 ソートを行わない理由は、処理時間を節約するためだけである。
 116 デフォルトでは、返されるパス名はソートされる。
 117 .TP
 118 .B GLOB_DOOFFS
 119 .I pglob->pathv
 120 の文字列リストの先頭に
 121 .I pglob->gl_offs
 122 スロット分の領域を予約する。
 123 予約されたスロットには NULL ポインタが入る。
 124 .TP
 125 .B GLOB_NOCHECK
 126 マッチするパターンがなければ、元のパターンを返す。
 127 デフォルトでは、
 128 .BR glob ()
 129 はマッチするパターンがなければ
 130 .B GLOB_NOMATCH
 131 を返す。
 132 .TP
 133 .B GLOB_APPEND
 134 この呼び出しでの結果を直前の
 135 .BR glob ()
 136 の呼び出しで返された結果のベクトルに追加する。最初の
 137 .BR glob ()
 138 の呼び出しの際にはこのフラグを設定してはいけない。
 139 .TP
 140 .B GLOB_NOESCAPE
 141 バックスラッシュ (\(aq\\\(aq) をエスケープ用文字として使用できない。
 142 通常は、バックスラッシュを使って、次に続く文字をクォートすることで、
 143 特別な意味を持つメタキャラクタを無効することができる。
 144 .PP
 145 .I flags
 146 には以下に示すものも指定できる。
 147 これらは GNU で拡張されたもので、POSIX.2 では定義されていない。
 148 .TP
 149 .B GLOB_PERIOD
 150 先頭のピリオドがメタキャラクタにマッチできるようにする。
 151 デフォルトでは、メタキャラクタは先頭のピリオドにはマッチできない。
 152 .TP
 153 .B GLOB_ALTDIRFUNC
 154 ファイルシステムにアクセスする際に、通常のライブラリ関数の代わりに
 155 代替関数
 156 .IR pglob\->gl_closedir ,
 157 .IR pglob\->gl_readdir ,
 158 .IR pglob\->gl_opendir ,
 159 .IR pglob\->gl_lstat ,
 160 .I pglob\->gl_stat
 161 が用いられる。
 162 .TP
 163 .B GLOB_BRACE
 164 \fB{a,b}\fR
 165 という形式の
 166 .BR csh (1)
 167 スタイルの括弧表現を展開する。
 168 括弧表現は入れ子にすることができる。
 169 したがって、例えば、"{foo/{,cat,dog},bar}" というパターンを
 170 指定した場合に得られる結果は、
 171 4つの文字列 "foo/", "foo/cat", "foo/dog", "bar" のそれぞれについて
 172 .BR glob ()
 173 を呼び出した場合と同じになる。
 174 .TP
 175 .B GLOB_NOMAGIC
 176 パターンにメタキャラクタが含まれていない場合、
 177 マッチ結果として指定されたパターンだけを返す。
 178 パターンで指定された名前のファイルが存在しない場合であっても、
 179 そのパターンが返される。
 180 .TP
 181 .B GLOB_TILDE
 182 チルダの展開を行う。
 183 チルダ (\(aq~\(aq) がパターン内の唯一の文字の場合か、先頭のチルダの直後の文字が
 184 スラッシュ (\(aq/\(aq) の場合、チルダを呼び出し者のホームディレクトリで置換する。
 185 先頭のチルダにユーザ名が続く場合 (例えば "~andrea/bin")、
 186 チルダとユーザ名をそのユーザのホームディレクトリで置換する。
 187 ユーザ名が無効な場合やホームディレクトリが決定できない場合は、
 188 置換は実行されない。
 189 .TP
 190 .B GLOB_TILDE_CHECK
 191 このフラグを指定すると
 192 .B GLOB_TILDE
 193 と同様の振舞いをする。
 194 .B GLOB_TILDE
 195 との違いは、ユーザ名が無効だった場合や
 196 ホームディレクトリが決定できなかった場合に、
 197 パターン自身を使用するのではなく、
 198 .BR glob ()
 199 がエラーを示す
 200 .B GLOB_NOMATCH
 201 を返すことである。
 202 .TP
 203 .B GLOB_ONLYDIR
 204 このフラグは、
 205 .BR glob ()
 206 に対する「ヒント」であり、
 207 呼び出し側がパターンにマッチするディレクトリにしか興味がないことを知らせる。
 208 実装においてファイルの種別情報を簡単に決定できる場合は、ディレクトリでない
 209 ファイルは呼び出し側に返されない。しかしながら、呼び出し側では、返された
 210 ファイルリストがディレクトリかどうかを確認しなければならない。
 211 (このフラグが存在するのは、呼び出し側がディレクトリにしか興味がない際に
 212 性能を最適化する目的のためだけである。)
 213 .PP
 214 .I errfunc
 215 が NULL でなければ、
 216 エラーが起こった場合には関数
 217 .I errfunc
 218 が呼び出される。関数の引数には、失敗したパス名
 219 .I epath
 220 と
 221 .I errno
 222 .RB ( opendir (3),
 223 .BR readdir (3),
 224 .BR stat (2).
 225 のいずれかによってセットされた値) が与えられる。
 226 .I errfunc
 227 が 0 以外の値を返すかもしくは
 228 .B GLOB_ERR
 229 がセットされた場合
 230 .BR glob ()
 231 は
 232 .I errfunc
 233 の呼び出し後に終了する。
 234 .PP
 235 呼び出しが成功して戻った場合
 236 .I pglob\->gl_pathc
 237 にはマッチしたパス名が含まれ、
 238 .I pglob\->gl_pathv
 239 はマッチしたパス名へのポインタのリストへのポインタとなる。
 240 ポインタのリストは NULL ポインタで終端される。
 241 .PP
 242 .BR glob ()
 243 を何度か続けて呼び出すことができる。その際2回目以降の呼び出しでは
 244 .B GLOB_APPEND
 245 フラグが
 246 .I flags
 247 に設定されていなければならない。
 248 .PP
 249 GNU の拡張として、
 250 .I pglob\->gl_flags
 251 には指定したフラグがセットされる。もし一つでもメタキャラクタが見付かれば
 252 このフラグと
 253 .B GLOB_MAGCHAR
 254 との \fBOR\fR を取った結果がセットされる。
 255 .SH 返り値
 256 呼び出しが成功して完了すると
 257 .BR glob ()
 258 は 0 を返す。
 259 それ以外の返り値は以下の通り:
 260 .TP
 261 .B GLOB_NOSPACE
 262 メモリを使い果たした
 263 .TP
 264 .B GLOB_ABORTED
 265 読み取りエラー
 266 .TP
 267 .B GLOB_NOMATCH
 268 一つもマッチしなかった
 269 .SH 準拠
 270 POSIX.2, POSIX.1-2001.
 271 .SH 注意
 272 glibc 2.1 では、
 273 .I gl_pathc
 274 と
 275 .I gl_offs
 276 は POSIX.2 で指定されているように
 277 .I size_t
 278 として宣言されている。
 279 libc4, libc5, glibc 2.0 では、
 280 .I int
 281 として宣言されている。
 282 .SH バグ
 283 .BR glob ()
 284 関数はその中で呼び出している
 285 .BR malloc (3)
 286 や
 287 .BR opendir (3)
 288 などの関数の呼び出しで失敗が起こると失敗する。
 289 これにより
 290 .I errno
 291 にそのエラーコードが入る。
 292 .SH 例
 293 使用法の一例を以下に示す。以下はシェルで
 294 .sp
 295 .in +4n
 296 ls \-l *.c ../*.c
 297 .in
 298 .sp
 299 をタイプした場合をシミュレートしている。
 300 .nf
 301 .in +4n
 302
 303 glob_t globbuf;
 304
 305 globbuf.gl_offs = 2;
 306 glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
 307 glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
 308 globbuf.gl_pathv[0] = "ls";
 309 globbuf.gl_pathv[1] = "\-l";
 310 execvp("ls", &globbuf.gl_pathv[0]);
 311 .in
 312 .fi
 313 .SH 関連項目
 314 .BR ls (1),
 315 .BR sh (1),
 316 .BR stat (2),
 317 .BR exec (3),
 318 .BR fnmatch (3),
 319 .BR malloc (3),
 320 .BR opendir (3),
 321 .BR readdir (3),
 322 .BR wordexp (3),
 323 .BR glob (7)