manual/LDP_man-pages/draft/man3/glob.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu)
  26 .\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de)
  27 .\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  28 .\" Modified 990912 by aeb
  29 .\" 2007-10-10 mtk
  30 .\"     Added description of GLOB_TILDE_NOMATCH
  31 .\"     Expanded the description of various flags
  32 .\"     Various wording fixes.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" This file was generated with po4a. Translate the source file.
  37 .\"
  38 .\"*******************************************************************
  39 .\"
  40 .\" Japanese Version Copyright (c) 1998 Ken Wakasa all rights reserved.
  41 .\" Translated 1998-06-24, Ken Wakasa <wakasa@iname.com>
  42 .\" Updated 1999-01-04, Kentaro Shirakata <argrath@yo.rim.or.jp>
  43 .\" Updated 2008-02-12, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
  44 .\"
  45 .TH GLOB 3 2020\-06\-09 GNU "Linux Programmer's Manual"
  46 .SH 名前
  47 glob, globfree \- パターンにマッチするパス名を見付ける。glob() によっ て確保されたメモリー領域を解放する。
  48 .SH 書式
  49 .nf
  50 \fB#include <glob.h>\fP
  51 .PP
  52 \fBint glob(const char *\fP\fIpattern\fP\fB, int \fP\fIflags\fP\fB,\fP
  53 \fB         int (*\fP\fIerrfunc\fP\fB) (const char *\fP\fIepath\fP\fB, int \fP\fIeerrno\fP\fB),\fP
  54 \fB         glob_t *\fP\fIpglob\fP\fB);\fP
  55 \fBvoid globfree(glob_t *\fP\fIpglob\fP\fB);\fP
  56 .fi
  57 .SH 説明
  58 \fBglob\fP()  関数はシェルが用いているルール (\fBglob\fP(7)  参照) に基づいてパターン \fIpattern\fP
  59 にマッチするすべてのパス名を検索する。 チルダ (~) の展開やパラメーター置換は行われない。それらを行いたい場合は \fBwordexp\fP(3)
  60 を使うとよい。
  61 .PP
  62 \fBglobfree\fP()  関数は前に呼ばれた \fBglob\fP()  により動的に確保された記憶領域を解放する。
  63 .PP
  64 \fBglob\fP()  の結果は \fIpglob\fP がポイントする構造体に返される。 \fIpglob\fP は \fIglob_t\fP 型の構造体である。
  65 \fIglob_t\fP 型は \fI<glob.h>\fP 内で宣言されており、以下の要素を含んでいる。これらの要素は POSIX.2 で定義
  66 されている (さらに多くの要素が拡張として入っているかもしれない)。
  67 .PP
  68 .in +4n
  69 .EX
  70 typedef struct {
  71     size_t   gl_pathc;    /* 今までにマッチしたパスの数 */
  72     char   **gl_pathv;    /* マッチしたパス名のリスト */
  73     size_t   gl_offs;     /* \fIgl_pathv\fP 内に確保するスロット数 */
  74 } glob_t;
  75 .EE
  76 .in
  77 .PP
  78 結果は動的に確保された記憶領域に入れられる。
  79 .PP
  80 パラメーター \fIflags\fP には以下の示す定数のうち、指定したいものをビットごとの OR で与える (一つも 指定しなくてもよい)。これによって
  81 \fBglob\fP()  の動作を変更できる。
  82 .TP
  83 \fBGLOB_ERR\fP
  84 (例えば、ディレクトリに読み取り許可属性が無い場合などで)  読み取りエラーが発生した際に関数から戻る。 デフォルトでは、エラーに関わらず
  85 読み取り可能なディレクトリを全てについて読み取りを実行しようとする。
  86 .TP
  87 \fBGLOB_MARK\fP
  88 ディレクトリに対応する各々のパスにスラッシュを付加する。
  89 .TP
  90 \fBGLOB_NOSORT\fP
  91 返されるパス名のソートを行わない。 ソートを行わない理由は、処理時間を節約するためだけである。 デフォルトでは、返されるパス名はソートされる。
  92 .TP
  93 \fBGLOB_DOOFFS\fP
  94 \fIpglob\->pathv\fP の文字列リストの先頭に \fIpglob\->gl_offs\fP スロット分の領域を予約する。
  95 予約されたスロットにはヌルポインターが入る。
  96 .TP
  97 \fBGLOB_NOCHECK\fP
  98 マッチするパターンがなければ、元のパターンを返す。 デフォルトでは、 \fBglob\fP()  はマッチするパターンがなければ
  99 \fBGLOB_NOMATCH\fP を返す。
 100 .TP
 101 \fBGLOB_APPEND\fP
 102 この呼び出しでの結果を直前の \fBglob\fP()  の呼び出しで返された結果のベクトルに追加する。最初の \fBglob\fP()
 103 の呼び出しの際にはこのフラグを設定してはいけない。
 104 .TP
 105 \fBGLOB_NOESCAPE\fP
 106 バックスラッシュ (\(aq\e\(aq) をエスケープ用文字として使用できない。 通常は、バックスラッシュを使って、次に続く文字をクォートすることで、
 107 特別な意味を持つメタキャラクターを無効することができる。
 108 .PP
 109 \fIflags\fP には以下に示すものも指定できる。 これらは GNU で拡張されたもので、POSIX.2 では定義されていない。
 110 .TP
 111 \fBGLOB_PERIOD\fP
 112 先頭のピリオドがメタキャラクターにマッチできるようにする。 デフォルトでは、メタキャラクターは先頭のピリオドにはマッチできない。
 113 .TP
 114 \fBGLOB_ALTDIRFUNC\fP
 115 ファイルシステムにアクセスする際に、通常のライブラリ関数の代わりに 代替関数 \fIpglob\->gl_closedir\fP,
 116 \fIpglob\->gl_readdir\fP, \fIpglob\->gl_opendir\fP, \fIpglob\->gl_lstat\fP,
 117 \fIpglob\->gl_stat\fP が用いられる。
 118 .TP
 119 \fBGLOB_BRACE\fP
 120 \fB{a,b}\fP という形式の \fBcsh\fP(1)  スタイルの括弧表現を展開する。 括弧表現は入れ子にすることができる。
 121 したがって、例えば、"{foo/{,cat,dog},bar}" というパターンを 指定した場合に得られる結果は、 4つの文字列 "foo/",
 122 "foo/cat", "foo/dog", "bar" のそれぞれについて \fBglob\fP()  を呼び出した場合と同じになる。
 123 .TP
 124 \fBGLOB_NOMAGIC\fP
 125 パターンにメタキャラクターが含まれていない場合、 マッチ結果として指定されたパターンだけを返す。
 126 パターンで指定された名前のファイルが存在しない場合であっても、 そのパターンが返される。
 127 .TP
 128 \fBGLOB_TILDE\fP
 129 Carry out tilde expansion.  If a tilde (\(aq\(ti\(aq) is the only character
 130 in the pattern, or an initial tilde is followed immediately by a slash
 131 (\(aq/\(aq), then the home directory of the caller is substituted for the
 132 tilde.  If an initial tilde is followed by a username (e.g.,
 133 "\(tiandrea/bin"), then the tilde and username are substituted by the home
 134 directory of that user.  If the username is invalid, or the home directory
 135 cannot be determined, then no substitution is performed.
 136 .TP
 137 \fBGLOB_TILDE_CHECK\fP
 138 このフラグを指定すると \fBGLOB_TILDE\fP と同様の振舞いをする。 \fBGLOB_TILDE\fP との違いは、ユーザー名が無効だった場合や
 139 ホームディレクトリが決定できなかった場合に、 パターン自身を使用するのではなく、 \fBglob\fP()  がエラーを示す \fBGLOB_NOMATCH\fP
 140 を返すことである。
 141 .TP
 142 \fBGLOB_ONLYDIR\fP
 143 このフラグは、 \fBglob\fP()  に対する「ヒント」であり、 呼び出し側がパターンにマッチするディレクトリにしか興味がないことを知らせる。
 144 実装においてファイルの種別情報を簡単に決定できる場合は、ディレクトリでない ファイルは呼び出し側に返されない。しかしながら、呼び出し側では、返された
 145 ファイルリストがディレクトリかどうかを確認しなければならない。 (このフラグが存在するのは、呼び出し側がディレクトリにしか興味がない際に
 146 性能を最適化する目的のためだけである。)
 147 .PP
 148 \fIerrfunc\fP が NULL でなければ、 エラーが起こった場合には関数 \fIerrfunc\fP が呼び出される。関数の引数には、失敗したパス名
 149 \fIepath\fP と \fIerrno\fP (\fBopendir\fP(3), \fBreaddir\fP(3), \fBstat\fP(2).
 150 のいずれかによってセットされた値) が与えられる。 \fIerrfunc\fP が 0 以外の値を返すかもしくは \fBGLOB_ERR\fP がセットされた場合
 151 \fBglob\fP()  は \fIerrfunc\fP の呼び出し後に終了する。
 152 .PP
 153 呼び出しが成功して戻った場合 \fIpglob\->gl_pathc\fP にはマッチしたパス名が含まれ、 \fIpglob\->gl_pathv\fP
 154 はマッチしたパス名へのポインターのリストへのポインターとなる。 ポインターのリストはヌルポインターで終端される。
 155 .PP
 156 \fBglob\fP()  を何度か続けて呼び出すことができる。その際2回目以降の呼び出しでは \fBGLOB_APPEND\fP フラグが \fIflags\fP
 157 に設定されていなければならない。
 158 .PP
 159 GNU の拡張として、 \fIpglob\->gl_flags\fP には指定したフラグがセットされる。もし一つでもメタキャラクターが見付かれば
 160 このフラグと \fBGLOB_MAGCHAR\fP との \fBOR\fP を取った結果がセットされる。
 161 .SH 返り値
 162 呼び出しが成功して完了すると \fBglob\fP()  は 0 を返す。 それ以外の返り値は以下の通り:
 163 .TP
 164 \fBGLOB_NOSPACE\fP
 165 メモリーを使い果たした
 166 .TP
 167 \fBGLOB_ABORTED\fP
 168 読み取りエラー
 169 .TP
 170 \fBGLOB_NOMATCH\fP
 171 一つもマッチしなかった
 172 .SH 属性
 173 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。
 174 .TS
 175 allbox;
 176 lb lb lbw24
 177 l l l.
 178 インターフェース        属性  値
 179 T{
 180 \fBglob\fP()
 181 T}      Thread safety   T{
 182 MT\-Unsafe race:utent env
 183 .br
 184 sig:ALRM timer locale
 185 T}
 186 T{
 187 \fBglobfree\fP()
 188 T}      Thread safety   MT\-Safe
 189 .TE
 190 .sp 1
 191 In the above table, \fIutent\fP in \fIrace:utent\fP signifies that if any of the
 192 functions \fBsetutent\fP(3), \fBgetutent\fP(3), or \fBendutent\fP(3)  are used in
 193 parallel in different threads of a program, then data races could occur.
 194 \fBglob\fP()  calls those functions, so we use race:utent to remind users.
 195 .SH 準拠
 196 POSIX.1\-2001, POSIX.1\-2008, POSIX.2.
 197 .SH 注意
 198 glibc 2.1 では、 \fIgl_pathc\fP と \fIgl_offs\fP は POSIX.2 で指定されているように \fIsize_t\fP
 199 として宣言されている。 glibc 2.0 では、 \fIint\fP として宣言されている。
 200 .SH バグ
 201 \fBglob\fP()  関数はその中で呼び出している \fBmalloc\fP(3)  や \fBopendir\fP(3)
 202 などの関数の呼び出しで失敗が起こると失敗する。 これにより \fIerrno\fP にそのエラーコードが入る。
 203 .SH EXAMPLES
 204 使用法の一例を以下に示す。以下はシェルで
 205 .PP
 206 .in +4n
 207 .EX
 208 ls \-l *.c ../*.c
 209 .EE
 210 .in
 211 .PP
 212 をタイプした場合をシミュレートしている。
 213 .PP
 214 .in +4n
 215 .EX
 216 glob_t globbuf;
 217
 218 globbuf.gl_offs = 2;
 219 glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
 220 glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
 221 globbuf.gl_pathv[0] = "ls";
 222 globbuf.gl_pathv[1] = "\-l";
 223 execvp("ls", &globbuf.gl_pathv[0]);
 224 .EE
 225 .in
 226 .SH 関連項目
 227 \fBls\fP(1), \fBsh\fP(1), \fBstat\fP(2), \fBexec\fP(3), \fBfnmatch\fP(3), \fBmalloc\fP(3),
 228 \fBopendir\fP(3), \fBreaddir\fP(3), \fBwordexp\fP(3), \fBglob\fP(7)
 229 .SH この文書について
 230 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
 231 \%https://www.kernel.org/doc/man\-pages/ に書かれている。