diff options
Diffstat (limited to 'man/man3/glob.3')
| -rw-r--r-- | man/man3/glob.3 | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/man/man3/glob.3 b/man/man3/glob.3 new file mode 100644 index 0000000..98ea94f --- /dev/null +++ b/man/man3/glob.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +glob, globfree \- find pathnames matching a pattern, free memory from glob() +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <glob.h> +.P +.BI "int glob(const char *restrict " pattern ", int " flags , +.BI " int (*" errfunc ")(const char *" epath ", int " eerrno ), +.BI " glob_t *restrict " pglob ); +.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). +.P +The +.BR globfree () +function frees the dynamically allocated storage from an earlier call +to +.BR glob (). +.P +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): +.P +.in +4n +.EX +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; +.EE +.in +.P +Results are stored in dynamically allocated storage. +.P +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]\e\[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. +.P +.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]\[ti]\[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., "\[ti]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 +.B 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.) +.P +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 . +.P +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. +.P +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. +.P +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 lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR glob () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent env +sig:ALRM timer locale +T} +T{ +.na +.nh +.BR globfree () +T} Thread safety MT-Safe +.TE +.P +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 () +calls those functions, +so we use race:utent to remind users. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 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 EXAMPLES +One example of use is the following code, which simulates typing +.P +.in +4n +.EX +ls \-l *.c ../*.c +.EE +.in +.P +in the shell: +.P +.in +4n +.EX +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]); +.EE +.in +.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) |