mirror of https://github.com/mkerrisk/man-pages
325 lines
8.2 KiB
Groff
325 lines
8.2 KiB
Groff
.\" (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.
|
|
.\"
|
|
.TH GLOB 3 2007-10-10 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
glob, globfree \- find pathnames matching a pattern, free memory from glob()
|
|
.SH SYNOPSIS
|
|
.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
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR glob ()
|
|
function searches for all the pathnames matching
|
|
.I pattern
|
|
according to the rules used by the shell (see
|
|
.BR glob (7)).
|
|
No tilde expansion or parameter substitution is done; if you want
|
|
these, use
|
|
.BR wordexp (3).
|
|
.PP
|
|
The
|
|
.BR globfree ()
|
|
function frees the dynamically allocated storage from an earlier call
|
|
to
|
|
.BR glob ().
|
|
.PP
|
|
The results of a
|
|
.BR glob ()
|
|
call are stored in the structure pointed to by
|
|
.IR pglob .
|
|
This structure is of type
|
|
.I glob_t
|
|
(declared in
|
|
.IR <glob.h> )
|
|
and includes the following elements defined by POSIX.2 (more may be
|
|
present as an extension):
|
|
.PP
|
|
.br
|
|
.in +4n
|
|
.nf
|
|
typedef struct {
|
|
size_t gl_pathc; /* Count of paths matched so far */
|
|
char **gl_pathv; /* List of matched pathnames. */
|
|
size_t gl_offs; /* Slots to reserve in \fIgl_pathv\fP. */
|
|
} glob_t;
|
|
.fi
|
|
.in
|
|
.PP
|
|
Results are stored in dynamically allocated storage.
|
|
.PP
|
|
The parameter
|
|
.I flags
|
|
is made up of the bitwise OR of zero or more the following symbolic
|
|
constants, which modify the behavior of
|
|
.BR glob ():
|
|
.TP
|
|
.B GLOB_ERR
|
|
Return upon a read error (because a directory does not
|
|
have read permission, for example).
|
|
By default,
|
|
.BR glob ()
|
|
attempts carry on despite errors,
|
|
reading all of the directories that it can.
|
|
.TP
|
|
.B GLOB_MARK
|
|
Append a slash to each path which corresponds to a directory.
|
|
.TP
|
|
.B GLOB_NOSORT
|
|
Don't sort the returned pathnames.
|
|
The only reason to do this is to save processing time.
|
|
By default, the returned pathnames are sorted.
|
|
.TP
|
|
.B GLOB_DOOFFS
|
|
Reserve
|
|
.I pglob\->gl_offs
|
|
slots at the beginning of the list of strings in
|
|
.IR pglob\->pathv .
|
|
The reserved slots contain NULL pointers.
|
|
.TP
|
|
.B GLOB_NOCHECK
|
|
If no pattern matches, return the original pattern.
|
|
By default,
|
|
.BR glob ()
|
|
returns
|
|
.B GLOB_NOMATCH
|
|
if there are no matches.
|
|
.TP
|
|
.B GLOB_APPEND
|
|
Append the results of this call to the vector of results
|
|
returned by a previous call to
|
|
.BR glob ().
|
|
Do not set this flag on the first invocation of
|
|
.BR glob ().
|
|
.TP
|
|
.B GLOB_NOESCAPE
|
|
Don't allow backslash (\(aq\\\(aq) to be used as an escape
|
|
character.
|
|
Normally, a backslash can be used to quote the following character,
|
|
providing a mechanism to turn off the special meaning
|
|
metacharacters.
|
|
.PP
|
|
.I flags
|
|
may also include any of the following, which are GNU
|
|
extensions and not defined by POSIX.2:
|
|
.TP
|
|
.B GLOB_PERIOD
|
|
Allow a leading period to be matched by metacharacters.
|
|
By default, metacharacters can't match a leading period.
|
|
.TP
|
|
.B GLOB_ALTDIRFUNC
|
|
Use alternative functions
|
|
.IR pglob\->gl_closedir ,
|
|
.IR pglob\->gl_readdir ,
|
|
.IR pglob\->gl_opendir ,
|
|
.IR pglob\->gl_lstat ", and"
|
|
.I pglob\->gl_stat
|
|
for file system access instead of the normal library
|
|
functions.
|
|
.TP
|
|
.B GLOB_BRACE
|
|
Expand
|
|
.BR csh (1)
|
|
style brace expressions of the form \fB{a,b}\fR.
|
|
Brace expressions can be nested.
|
|
Thus, for example, specifying the pattern
|
|
"{foo/{,cat,dog},bar}" would return the same results as four separate
|
|
.BR glob ()
|
|
calls using the strings:
|
|
"foo/",
|
|
"foo/cat",
|
|
"foo/dog",
|
|
and
|
|
"bar".
|
|
.TP
|
|
.B GLOB_NOMAGIC
|
|
If the pattern contains no metacharacters
|
|
then it should be returned as the sole matching word,
|
|
even if there is no file with that name.
|
|
.TP
|
|
.B GLOB_TILDE
|
|
Carry out tilde expansion.
|
|
If a tilde (\(aq~\(aq) is the only character in the pattern,
|
|
or an initial tilde is followed immediately by a slash (\(aq/\(aq),
|
|
then the home directory of the caller is substituted for
|
|
the tilde.
|
|
If an initial tilde is followed by a username (e.g., "~andrea/bin"),
|
|
then the tilde and username are substituted by the home directory
|
|
of that user.
|
|
If the username is invalid, or the home directory cannot be
|
|
determined, then no substitution is performed.
|
|
.TP
|
|
.B GLOB_TILDE_CHECK
|
|
This provides behavior similar to that of
|
|
.BR GLOB_TILDE .
|
|
The difference is that if the username is invalid, or the
|
|
home directory cannot be determined, then
|
|
instead of using the pattern itself as the name,
|
|
.BR glob ()
|
|
returns
|
|
.BR GLOB_NOMATCH
|
|
to indicate an error.
|
|
.TP
|
|
.B GLOB_ONLYDIR
|
|
This is a
|
|
.I hint
|
|
to
|
|
.BR glob ()
|
|
that the caller is interested only in directories that match the pattern.
|
|
If the implementation can easily determine file-type information,
|
|
then non-directory files are not returned to the caller.
|
|
However, the caller must still check that returned files
|
|
are directories.
|
|
(The purpose of this flag is merely to optimize performance when
|
|
the caller is interested only in directories.)
|
|
.PP
|
|
If
|
|
.I errfunc
|
|
is not NULL,
|
|
it will be called in case of an error with the arguments
|
|
.IR epath ,
|
|
a pointer to the path which failed, and
|
|
.IR eerrno ,
|
|
the value of
|
|
.I errno
|
|
as returned from one of the calls to
|
|
.BR opendir (3),
|
|
.BR readdir (3),
|
|
or
|
|
.BR stat (2).
|
|
If
|
|
.I errfunc
|
|
returns non-zero, or if
|
|
.B GLOB_ERR
|
|
is set,
|
|
.BR glob ()
|
|
will terminate after the call to
|
|
.IR errfunc .
|
|
.PP
|
|
Upon successful return,
|
|
.I pglob\->gl_pathc
|
|
contains the number of matched pathnames and
|
|
.I pglob\->gl_pathv
|
|
contains a pointer to the list of pointers to matched pathnames.
|
|
The list of pointers is terminated by a NULL pointer.
|
|
.PP
|
|
It is possible to call
|
|
.BR glob ()
|
|
several times.
|
|
In that case, the
|
|
.B GLOB_APPEND
|
|
flag has to be set in
|
|
.I flags
|
|
on the second and later invocations.
|
|
.PP
|
|
As a GNU extension,
|
|
.I pglob\->gl_flags
|
|
is set to the flags specified, \fBor\fRed with
|
|
.B GLOB_MAGCHAR
|
|
if any metacharacters were found.
|
|
.SH "RETURN VALUE"
|
|
On successful completion,
|
|
.BR glob ()
|
|
returns zero.
|
|
Other possible returns are:
|
|
.TP
|
|
.B GLOB_NOSPACE
|
|
for running out of memory,
|
|
.TP
|
|
.B GLOB_ABORTED
|
|
for a read error, and
|
|
.TP
|
|
.B GLOB_NOMATCH
|
|
for no found matches.
|
|
.SH "CONFORMING TO"
|
|
POSIX.2, POSIX.1-2001.
|
|
.SH NOTES
|
|
The structure elements
|
|
.I gl_pathc
|
|
and
|
|
.I gl_offs
|
|
are declared as
|
|
.I size_t
|
|
in glibc 2.1, as they should be according to POSIX.2,
|
|
but are declared as
|
|
.I int
|
|
in libc4, libc5 and glibc 2.0.
|
|
.SH BUGS
|
|
The
|
|
.BR glob ()
|
|
function may fail due to failure of underlying function calls, such as
|
|
.BR malloc (3)
|
|
or
|
|
.BR opendir (3).
|
|
These will store their error code in
|
|
.IR errno .
|
|
.SH EXAMPLE
|
|
One example of use is the following code, which simulates typing
|
|
.sp
|
|
.in +4n
|
|
ls \-l *.c ../*.c
|
|
.in
|
|
.sp
|
|
in the shell:
|
|
.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
|
|
.SH "SEE ALSO"
|
|
.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)
|