mirror of https://github.com/mkerrisk/man-pages
254 lines
6.2 KiB
Groff
254 lines
6.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
|
|
.\"
|
|
.TH GLOB 3 1999-09-12 "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 ,
|
|
.nl
|
|
.BI " int " errfunc "(const char *" epath ", int " eerrno ),
|
|
.nl
|
|
.BI " glob_t *" pglob );
|
|
.nl
|
|
.BI "void globfree(glob_t *" pglob );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.B 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
|
|
.B globfree()
|
|
function frees the dynamically allocated storage from an earlier call
|
|
to
|
|
.BR glob() .
|
|
.PP
|
|
The results of a
|
|
.B glob()
|
|
call are stored in the structure pointed to by
|
|
.IR pglob ,
|
|
which is a
|
|
.B glob_t
|
|
which is declared in
|
|
.B <glob.h>
|
|
and includes the following elements defined by POSIX.2 (more may be
|
|
present as an extension):
|
|
.PP
|
|
.br
|
|
.nf
|
|
.in 10
|
|
typedef struct
|
|
{
|
|
.in 14
|
|
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 `gl_pathv'. */
|
|
.in 10
|
|
} glob_t;
|
|
.fi
|
|
.PP
|
|
Results are stored in dynamically allocated storage.
|
|
.PP
|
|
The parameter
|
|
.I flags
|
|
is made up of bitwise OR of zero or more the following symbolic
|
|
constants, which modify the of behaviour of
|
|
.BR glob() :
|
|
.TP
|
|
.B GLOB_ERR
|
|
which means to return upon read error (because a directory does not
|
|
have read permission, for example),
|
|
.TP
|
|
.B GLOB_MARK
|
|
which means to append a slash to each path which corresponds to a directory,
|
|
.TP
|
|
.B GLOB_NOSORT
|
|
which means don't sort the returned pathnames (they are by default),
|
|
.TP
|
|
.B GLOB_DOOFFS
|
|
which means that
|
|
.I pglob->gl_offs
|
|
slots will be reserved at the beginning of the list of strings in
|
|
.IR pglob->pathv ,
|
|
.TP
|
|
.B GLOB_NOCHECK
|
|
which means that, if no pattern matches, to return the original pattern,
|
|
.TP
|
|
.B GLOB_APPEND
|
|
which means to append to the results of a previous call. Do not set
|
|
this flag on the first invocation of
|
|
.BR glob() .
|
|
.TP
|
|
.B GLOB_NOESCAPE
|
|
which means that meta characters cannot be quoted by backslashes.
|
|
.PP
|
|
The flags may also include some of the following, which are GNU
|
|
extensions and not defined by POSIX.2:
|
|
.TP
|
|
.B GLOB_PERIOD
|
|
which means that a leading period can be matched by meta characters,
|
|
.TP
|
|
.B GLOB_ALTDIRFUNC
|
|
which means that alternative functions
|
|
.IR pglob->gl_closedir ,
|
|
.IR pglob->gl_readdir ,
|
|
.IR pglob->gl_opendir ,
|
|
.IR pglob->gl_lstat ", and"
|
|
.I pglob->gl_stat
|
|
are used for file system access instead of the normal library
|
|
functions,
|
|
.TP
|
|
.B GLOB_BRACE
|
|
which means that
|
|
.BR csh (1)
|
|
style brace expressions \fB{a,b}\fR are expanded,
|
|
.TP
|
|
.B GLOB_NOMAGIC
|
|
which means that the pattern is returned if it contains no metacharacters,
|
|
.TP
|
|
.B GLOB_TILDE
|
|
which means that tilde expansion is carried out, and
|
|
.TP
|
|
.B GLOB_ONLYDIR
|
|
which means that only directories are matched.
|
|
.PP
|
|
If
|
|
.I errfunc
|
|
is not
|
|
.BR 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() ", " readdir() ", or " stat() .
|
|
If
|
|
.I errfunc
|
|
returns non-zero, or if
|
|
.B GLOB_ERR
|
|
is set,
|
|
.B 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
|
|
a pointer to the list of matched pathnames. The first pointer after
|
|
the last pathname is
|
|
.BR NULL .
|
|
.PP
|
|
It is possible to call
|
|
.B 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,
|
|
.B 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 EXAMPLES
|
|
One example of use is the following code, which simulates typing
|
|
.nl
|
|
.B ls \-l *.c ../*.c
|
|
.nl
|
|
in the shell.
|
|
.nf
|
|
.in 10
|
|
|
|
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]);
|
|
.fi
|
|
.SH "CONFORMING TO"
|
|
POSIX.2
|
|
.SH BUGS
|
|
The
|
|
.B glob()
|
|
function may fail due to failure of underlying function calls, such as
|
|
.BR malloc() " or " opendir() .
|
|
These will store their error code in
|
|
.IR errno .
|
|
.SH NOTES
|
|
The structure elements
|
|
.I gl_pathc
|
|
and
|
|
.I gl_offs
|
|
are declared as
|
|
.BR size_t
|
|
in glibc 2.1, as they should according to POSIX.2,
|
|
but are declared as
|
|
.B int
|
|
in libc4, libc5 and glibc 2.0.
|
|
.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)
|