[linuxjm/LDP_man-pages.git] / draft / man3 / glob.3

.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" License.
.\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de)
.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
.\" Modified 990912 by aeb
.\" 2007-10-10 mtk
.\"     Added description of GLOB_TILDE_NOMATCH
.\"     Expanded the description of various flags
.\"     Various wording fixes.
.\"
.\" Japanese Version Copyright (c) 1998 Ken Wakasa all rights reserved.
.\" Translated 1998-06-24, Ken Wakasa <wakasa@iname.com>
.\" Updated 1999-01-04, Kentaro Shirakata <argrath@yo.rim.or.jp>
.\" Updated 2008-02-12, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
.\"
.TH GLOB 3  2007-10-10 "GNU" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O glob, globfree \- find pathnames matching a pattern, free memory from glob()
glob, globfree \- パターンにマッチするパス名を見付ける。glob() によっ
て確保されたメモリ領域を解放する。
.\"O .SH SYNOPSIS
.SH 書式
.nf
.B #include <glob.h>
.sp
.BI "int glob(const char *" pattern ", int " flags ,
.br
.BI "         int (*" errfunc ") (const char *" epath ", int " eerrno ),
.br
.BI "         glob_t *" pglob );
.br
.BI "void globfree(glob_t *" pglob );
.fi
.\"O .SH DESCRIPTION
.SH 説明
.\"O The
.\"O .BR glob ()
.\"O function searches for all the pathnames matching
.\"O .I pattern
.\"O according to the rules used by the shell (see
.\"O .BR glob (7)).
.BR glob ()
関数はシェルが用いているルール
.RB ( glob (7)
参照) に基づいてパターン
.I pattern
にマッチするすべてのパス名を検索する。
.\"O No tilde expansion or parameter substitution is done; if you want
.\"O these, use
.\"O .BR wordexp (3).
チルダ (~) の展開やパラメータ置換は行われない。それらを行いたい場合は
.BR wordexp (3)
を使うとよい。
.PP
.\"O The
.\"O .BR globfree ()
.\"O function frees the dynamically allocated storage from an earlier call
.\"O to
.\"O .BR glob ().
.BR globfree ()
関数は前に呼ばれた
.BR glob ()
により動的に確保された記憶領域を解放する。
.PP
.\"O The results of a
.\"O .BR glob ()
.\"O call are stored in the structure pointed to by
.\"O .IR pglob .
.\"O This structure is of type
.\"O .I glob_t
.\"O (declared in
.\"O .IR <glob.h> )
.\"O and includes the following elements defined by POSIX.2 (more may be
.\"O present as an extension):
.BR glob ()
の結果は
.I pglob
がポイントする構造体に返される。
.I pglob
は
.I glob_t
型の構造体である。
.I glob_t
型は
.I <glob.h>
内で宣言されており、以下の要素を含んでいる。これらの要素は POSIX.2 で定義
されている (さらに多くの要素が拡張として入っているかもしれない)。
.PP
.br
.in +4n
.nf
typedef struct {
.\"O     size_t   gl_pathc;    /* Count of paths matched so far  */
.\"O     char   **gl_pathv;    /* List of matched pathnames.  */
.\"O     size_t   gl_offs;     /* Slots to reserve in \fIgl_pathv\fP.  */
    size_t   gl_pathc;    /* 今までにマッチしたパスの数 */
    char   **gl_pathv;    /* マッチしたパス名のリスト */
    size_t   gl_offs;     /* \fIgl_pathv\fP 内に確保するスロット数 */
} glob_t;
.fi
.in
.PP
.\"O Results are stored in dynamically allocated storage.
結果は動的に確保された記憶領域に入れられる。
.PP
.\"O The argument
.\"O .I flags
.\"O is made up of the bitwise OR of zero or more the following symbolic
.\"O constants, which modify the behavior of
.\"O .BR glob ():
パラメータ
.I flags
には以下の示す定数のうち、指定したいものをビットごとの OR で与える
(一つも
指定しなくてもよい)。これによって
.BR glob ()
の動作を変更できる。
.TP
.B GLOB_ERR
.\"O Return upon a read error (because a directory does not
.\"O have read permission, for example).
.\"O By default,
.\"O .BR glob ()
.\"O attempts carry on despite errors,
.\"O reading all of the directories that it can.
(例えば、ディレクトリに読み取り許可属性が無い場合などで)
読み取りエラーが発生した際に関数から戻る。
デフォルトでは、エラーに関わらず
読み取り可能なディレクトリを全てについて読み取りを実行しようとする。
.TP
.B GLOB_MARK
.\"O Append a slash to each path which corresponds to a directory.
ディレクトリに対応する各々のパスにスラッシュを付加する。
.TP
.B GLOB_NOSORT
.\"O Don't sort the returned pathnames.
.\"O The only reason to do this is to save processing time.
.\"O By default, the returned pathnames are sorted.
返されるパス名のソートを行わない。
ソートを行わない理由は、処理時間を節約するためだけである。
デフォルトでは、返されるパス名はソートされる。
.TP
.B GLOB_DOOFFS
.\"O Reserve
.\"O .I pglob\->gl_offs
.\"O slots at the beginning of the list of strings in
.\"O .IR pglob\->pathv .
.\"O The reserved slots contain NULL pointers.
.I pglob->pathv
の文字列リストの先頭に
.I pglob->gl_offs
スロット分の領域を予約する。
予約されたスロットには NULL ポインタが入る。
.TP
.B GLOB_NOCHECK
.\"O If no pattern matches, return the original pattern.
.\"O By default,
.\"O .BR glob ()
.\"O returns
.\"O .B GLOB_NOMATCH
.\"O if there are no matches.
マッチするパターンがなければ、元のパターンを返す。
デフォルトでは、
.BR glob ()
はマッチするパターンがなければ
.B GLOB_NOMATCH
を返す。
.TP
.B GLOB_APPEND
.\"O Append the results of this call to the vector of results
.\"O returned by a previous call to
.\"O .BR glob ().
.\"O Do not set this flag on the first invocation of
.\"O .BR glob ().
この呼び出しでの結果を直前の
.BR glob ()
の呼び出しで返された結果のベクトルに追加する。最初の
.BR glob ()
の呼び出しの際にはこのフラグを設定してはいけない。
.TP
.B GLOB_NOESCAPE
.\"O Don't allow backslash (\(aq\\\(aq) to be used as an escape
.\"O character.
.\"O Normally, a backslash can be used to quote the following character,
.\"O providing a mechanism to turn off the special meaning
.\"O metacharacters.
バックスラッシュ (\(aq\\\(aq) をエスケープ用文字として使用できない。
通常は、バックスラッシュを使って、次に続く文字をクォートすることで、
特別な意味を持つメタキャラクタを無効することができる。
.PP
.\"O .I flags
.\"O may also include any of the following, which are GNU
.\"O extensions and not defined by POSIX.2:
.I flags
には以下に示すものも指定できる。
これらは GNU で拡張されたもので、POSIX.2 では定義されていない。
.TP
.B GLOB_PERIOD
.\"O Allow a leading period to be matched by metacharacters.
.\"O By default, metacharacters can't match a leading period.
先頭のピリオドがメタキャラクタにマッチできるようにする。
デフォルトでは、メタキャラクタは先頭のピリオドにはマッチできない。
.TP
.B GLOB_ALTDIRFUNC
.\"O Use alternative functions
.\"O .IR pglob\->gl_closedir ,
.\"O .IR pglob\->gl_readdir ,
.\"O .IR pglob\->gl_opendir ,
.\"O .IR pglob\->gl_lstat ", and"
.\"O .I pglob\->gl_stat
.\"O for file system access instead of the normal library
.\"O functions.
ファイルシステムにアクセスする際に、通常のライブラリ関数の代わりに
代替関数
.IR pglob\->gl_closedir ,
.IR pglob\->gl_readdir ,
.IR pglob\->gl_opendir ,
.IR pglob\->gl_lstat ,
.I pglob\->gl_stat
が用いられる。
.TP
.B GLOB_BRACE
.\"O Expand
.\"O .BR csh (1)
.\"O style brace expressions of the form \fB{a,b}\fR.
.\"O Brace expressions can be nested.
.\"O Thus, for example, specifying the pattern
.\"O "{foo/{,cat,dog},bar}" would return the same results as four separate
.\"O .BR glob ()
.\"O calls using the strings:
.\"O "foo/",
.\"O "foo/cat",
.\"O "foo/dog",
.\"O and
.\"O "bar".
\fB{a,b}\fR
という形式の
.BR csh (1)
スタイルの括弧表現を展開する。
括弧表現は入れ子にすることができる。
したがって、例えば、"{foo/{,cat,dog},bar}" というパターンを
指定した場合に得られる結果は、
4つの文字列 "foo/", "foo/cat", "foo/dog", "bar" のそれぞれについて
.BR glob ()
を呼び出した場合と同じになる。
.TP
.B GLOB_NOMAGIC
.\"O If the pattern contains no metacharacters
.\"O then it should be returned as the sole matching word,
.\"O even if there is no file with that name.
パターンにメタキャラクタが含まれていない場合、
マッチ結果として指定されたパターンだけを返す。
パターンで指定された名前のファイルが存在しない場合であっても、
そのパターンが返される。
.TP
.B GLOB_TILDE
.\"O Carry out tilde expansion.
.\"O If a tilde (\(aq~\(aq) is the only character in the pattern,
.\"O or an initial tilde is followed immediately by a slash (\(aq/\(aq),
.\"O then the home directory of the caller is substituted for
.\"O the tilde.
.\"O If an initial tilde is followed by a username (e.g., "~andrea/bin"),
.\"O then the tilde and username are substituted by the home directory
.\"O of that user.
.\"O If the username is invalid, or the home directory cannot be
.\"O determined, then no substitution is performed.
チルダの展開を行う。
チルダ (\(aq~\(aq) がパターン内の唯一の文字の場合か、先頭のチルダの直後の文字が
スラッシュ (\(aq/\(aq) の場合、チルダを呼び出し者のホームディレクトリで置換する。
先頭のチルダにユーザ名が続く場合 (例えば "~andrea/bin")、
チルダとユーザ名をそのユーザのホームディレクトリで置換する。
ユーザ名が無効な場合やホームディレクトリが決定できない場合は、
置換は実行されない。
.TP
.B GLOB_TILDE_CHECK
.\"O This provides behavior similar to that of
.\"O .BR GLOB_TILDE .
.\"O The difference is that if the username is invalid, or the
.\"O home directory cannot be determined, then
.\"O instead of using the pattern itself as the name,
.\"O .BR glob ()
.\"O returns
.\"O .BR GLOB_NOMATCH
.\"O to indicate an error.
このフラグを指定すると
.B GLOB_TILDE
と同様の振舞いをする。
.B GLOB_TILDE
との違いは、ユーザ名が無効だった場合や
ホームディレクトリが決定できなかった場合に、
パターン自身を使用するのではなく、
.BR glob ()
がエラーを示す
.B GLOB_NOMATCH
を返すことである。
.TP
.B GLOB_ONLYDIR
.\"O This is a
.\"O .I hint
.\"O to
.\"O .BR glob ()
.\"O that the caller is interested only in directories that match the pattern.
.\"O If the implementation can easily determine file-type information,
.\"O then nondirectory files are not returned to the caller.
.\"O However, the caller must still check that returned files
.\"O are directories.
.\"O (The purpose of this flag is merely to optimize performance when
.\"O the caller is interested only in directories.)
このフラグは、
.BR glob ()
に対する「ヒント」であり、
呼び出し側がパターンにマッチするディレクトリにしか興味がないことを知らせる。
実装においてファイルの種別情報を簡単に決定できる場合は、ディレクトリでない
ファイルは呼び出し側に返されない。しかしながら、呼び出し側では、返された
ファイルリストがディレクトリかどうかを確認しなければならない。
(このフラグが存在するのは、呼び出し側がディレクトリにしか興味がない際に
性能を最適化する目的のためだけである。)
.PP
.\"O If
.\"O .I errfunc
.\"O is not NULL,
.\"O it will be called in case of an error with the arguments
.\"O .IR epath ,
.\"O a pointer to the path which failed, and
.\"O .IR eerrno ,
.\"O the value of
.\"O .I errno
.\"O as returned from one of the calls to
.\"O .BR opendir (3),
.\"O .BR readdir (3),
.\"O or
.\"O .BR stat (2).
.I errfunc
が NULL でなければ、
エラーが起こった場合には関数
.I errfunc
が呼び出される。関数の引数には、失敗したパス名
.I epath
と
.I errno
.RB ( opendir (3),
.BR readdir (3),
.BR stat (2).
のいずれかによってセットされた値) が与えられる。
.\"O If
.\"O .I errfunc
.\"O returns nonzero, or if
.\"O .B GLOB_ERR
.\"O is set,
.\"O .BR glob ()
.\"O will terminate after the call to
.\"O .IR errfunc .
.I errfunc
が 0 以外の値を返すかもしくは
.B GLOB_ERR
がセットされた場合
.BR glob ()
は
.I errfunc
の呼び出し後に終了する。
.PP
.\"O Upon successful return,
.\"O .I pglob\->gl_pathc
.\"O contains the number of matched pathnames and
.\"O .I pglob\->gl_pathv
.\"O contains a pointer to the list of pointers to matched pathnames.
.\"O The list of pointers is terminated by a NULL pointer.
呼び出しが成功して戻った場合
.I pglob\->gl_pathc
にはマッチしたパス名が含まれ、
.I pglob\->gl_pathv
はマッチしたパス名へのポインタのリストへのポインタとなる。
ポインタのリストは NULL ポインタで終端される。
.PP
.\"O It is possible to call
.\"O .BR glob ()
.\"O several times.
.\"O In that case, the
.\"O .B GLOB_APPEND
.\"O flag has to be set in
.\"O .I flags
.\"O on the second and later invocations.
.BR glob ()
を何度か続けて呼び出すことができる。その際2回目以降の呼び出しでは
.B GLOB_APPEND
フラグが
.I flags
に設定されていなければならない。
.PP
.\"O As a GNU extension,
.\"O .I pglob\->gl_flags
.\"O is set to the flags specified, \fBor\fRed with
.\"O .B GLOB_MAGCHAR
.\"O if any metacharacters were found.
GNU の拡張として、
.I pglob\->gl_flags
には指定したフラグがセットされる。もし一つでもメタキャラクタが見付かれば
このフラグと
.B GLOB_MAGCHAR
との \fBOR\fR を取った結果がセットされる。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O On successful completion,
.\"O .BR glob ()
.\"O returns zero.
.\"O Other possible returns are:
呼び出しが成功して完了すると
.BR glob ()
は 0 を返す。
それ以外の返り値は以下の通り:
.TP
.B GLOB_NOSPACE
.\"O for running out of memory,
メモリを使い果たした
.TP
.B GLOB_ABORTED
.\"O for a read error, and
読み取りエラー
.TP
.B GLOB_NOMATCH
.\"O for no found matches.
一つもマッチしなかった
.\"O .SH "CONFORMING TO"
.SH 準拠
POSIX.2, POSIX.1-2001.
.\"O .SH BUGS
.\"O .SH NOTES
.SH 注意
.\"O The structure elements
.\"O .I gl_pathc
.\"O and
.\"O .I gl_offs
.\"O are declared as
.\"O .I size_t
.\"O in glibc 2.1, as they should be according to POSIX.2,
.\"O but are declared as
.\"O .I int
.\"O in libc4, libc5 and glibc 2.0.
glibc 2.1 では、
.I gl_pathc
と
.I gl_offs
は POSIX.2 で指定されているように
.I size_t
として宣言されている。
libc4, libc5, glibc 2.0 では、
.I int
として宣言されている。
.SH バグ
.\"O .BR glob ()
.\"O function may fail due to failure of underlying function calls, such as
.\"O .BR malloc (3)
.\"O or
.\"O .BR opendir (3).
.\"O These will store their error code in
.\"O .IR errno .
.BR glob ()
関数はその中で呼び出している
.BR malloc (3)
や
.BR opendir (3)
などの関数の呼び出しで失敗が起こると失敗する。
これにより
.I errno
にそのエラーコードが入る。
.\"O .SH EXAMPLE
.SH 例
.\"O One example of use is the following code, which simulates typing
.\"O .sp
.\"O .in +4n
.\"O ls \-l *.c ../*.c
.\"O .in
.\"O .sp
.\"O in the shell:
使用法の一例を以下に示す。以下はシェルで
.sp
.in +4n
ls \-l *.c ../*.c
.in
.sp
をタイプした場合をシミュレートしている。
.nf
.in +4n

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]);
.in
.fi
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR ls (1),
.BR sh (1),
.BR stat (2),
.BR exec (3),
.BR fnmatch (3),
.BR malloc (3),
.BR opendir (3),
.BR readdir (3),
.BR wordexp (3),
.BR glob (7)