diff options
Diffstat (limited to 'man3/glob.3')
| -rw-r--r-- | man3/glob.3 | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/man3/glob.3 b/man3/glob.3 new file mode 100644 index 000000000..e64277bd7 --- /dev/null +++ b/man3/glob.3 @@ -0,0 +1,252 @@ +.\" (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 expresions \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 malloc (3), +.BR opendir (3), +.BR readdir (3), +.BR wordexp (3), +.BR glob (7) |