diff options
Diffstat (limited to 'man3/glob.3')
| -rw-r--r-- | man3/glob.3 | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/man3/glob.3 b/man3/glob.3 deleted file mode 100644 index 9457de6..0000000 --- a/man3/glob.3 +++ /dev/null @@ -1,353 +0,0 @@ -'\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |