mirror of https://github.com/mkerrisk/man-pages
364 lines
8.8 KiB
Groff
364 lines
8.8 KiB
Groff
.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" 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_END
|
|
.\"
|
|
.\" 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 2015-04-19 "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 argument
|
|
.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 filesystem access instead of the normal library
|
|
functions.
|
|
.TP
|
|
.B GLOB_BRACE
|
|
Expand
|
|
.BR csh (1)
|
|
style brace expressions of the form
|
|
.BR {a,b} .
|
|
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 nondirectory 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 nonzero, 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,
|
|
.BR or ed
|
|
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 ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lb lb lbw24
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR glob ()
|
|
T} Thread safety T{
|
|
MT-Unsafe race:utent env
|
|
.br
|
|
sig:ALRM timer locale
|
|
T}
|
|
T{
|
|
.BR globfree ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
|
|
In the above table,
|
|
.I utent
|
|
in
|
|
.I race:utent
|
|
signifies that if any of the functions
|
|
.BR setutent (3),
|
|
.BR getutent (3),
|
|
or
|
|
.BR endutent (3)
|
|
are used in parallel in different threads of a program,
|
|
then data races could occur.
|
|
.BR glob (3)
|
|
calls those functions,
|
|
so we use race:utent to remind users.
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, POSIX.2.
|
|
.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 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)
|