diff options
Diffstat (limited to 'newlib/libc/sys/linux/stdlib/glob.3')
| -rw-r--r-- | newlib/libc/sys/linux/stdlib/glob.3 | 466 |
1 files changed, 0 insertions, 466 deletions
diff --git a/newlib/libc/sys/linux/stdlib/glob.3 b/newlib/libc/sys/linux/stdlib/glob.3 deleted file mode 100644 index aa509a363..000000000 --- a/newlib/libc/sys/linux/stdlib/glob.3 +++ /dev/null @@ -1,466 +0,0 @@ -.\" Copyright (c) 1989, 1991, 1993, 1994 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" Guido van Rossum. -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)glob.3 8.3 (Berkeley) 4/16/94 -.\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.20 2001/10/01 16:08:51 ru Exp $ -.\" -.Dd April 16, 1994 -.Dt GLOB 3 -.Os -.Sh NAME -.Nm glob , -.Nm globfree -.Nd generate pathnames matching a pattern -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In glob.h -.Ft int -.Fn glob "const char *pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t *pglob" -.Ft void -.Fn globfree "glob_t *pglob" -.Sh DESCRIPTION -The -.Fn glob -function -is a pathname generator that implements the rules for file name pattern -matching used by the shell. -.Pp -The include file -.Pa glob.h -defines the structure type -.Fa glob_t , -which contains at least the following fields: -.Bd -literal -typedef struct { - int gl_pathc; /* count of total paths so far */ - int gl_matchc; /* count of paths matching pattern */ - int gl_offs; /* reserved at beginning of gl_pathv */ - int gl_flags; /* returned flags */ - char **gl_pathv; /* list of paths matching pattern */ -} glob_t; -.Ed -.Pp -The argument -.Fa pattern -is a pointer to a pathname pattern to be expanded. -The -.Fn glob -argument -matches all accessible pathnames against the pattern and creates -a list of the pathnames that match. -In order to have access to a pathname, -.Fn glob -requires search permission on every component of a path except the last -and read permission on each directory of any filename component of -.Fa pattern -that contains any of the special characters -.Ql * , -.Ql ?\& -or -.Ql \&[ . -.Pp -The -.Fn glob -argument -stores the number of matched pathnames into the -.Fa gl_pathc -field, and a pointer to a list of pointers to pathnames into the -.Fa gl_pathv -field. -The first pointer after the last pathname is -.Dv NULL . -If the pattern does not match any pathnames, the returned number of -matched paths is set to zero. -.Pp -It is the caller's responsibility to create the structure pointed to by -.Fa pglob . -The -.Fn glob -function allocates other space as needed, including the memory pointed -to by -.Fa gl_pathv . -.Pp -The argument -.Fa flags -is used to modify the behavior of -.Fn glob . -The value of -.Fa flags -is the bitwise inclusive -.Tn OR -of any of the following -values defined in -.Pa glob.h : -.Bl -tag -width GLOB_ALTDIRFUNC -.It Dv GLOB_APPEND -Append pathnames generated to the ones from a previous call (or calls) -to -.Fn glob . -The value of -.Fa gl_pathc -will be the total matches found by this call and the previous call(s). -The pathnames are appended to, not merged with the pathnames returned by -the previous call(s). -Between calls, the caller must not change the setting of the -.Dv GLOB_DOOFFS -flag, nor change the value of -.Fa gl_offs -when -.Dv GLOB_DOOFFS -is set, nor (obviously) call -.Fn globfree -for -.Fa pglob . -.It Dv GLOB_DOOFFS -Make use of the -.Fa gl_offs -field. -If this flag is set, -.Fa gl_offs -is used to specify how many -.Dv NULL -pointers to prepend to the beginning -of the -.Fa gl_pathv -field. -In other words, -.Fa gl_pathv -will point to -.Fa gl_offs -.Dv NULL -pointers, -followed by -.Fa gl_pathc -pathname pointers, followed by a -.Dv NULL -pointer. -.It Dv GLOB_ERR -Causes -.Fn glob -to return when it encounters a directory that it cannot open or read. -Ordinarily, -.Fn glob -continues to find matches. -.It Dv GLOB_MARK -Each pathname that is a directory that matches -.Fa pattern -has a slash -appended. -.It Dv GLOB_NOCHECK -If -.Fa pattern -does not match any pathname, then -.Fn glob -returns a list -consisting of only -.Fa pattern , -with the number of total pathnames is set to 1, and the number of matched -pathnames set to 0. -If -.Dv GLOB_QUOTE -is set, its effect is present in the pattern returned. -.It Dv GLOB_NOSORT -By default, the pathnames are sorted in ascending -.Tn ASCII -order; -this flag prevents that sorting (speeding up -.Fn glob ) . -.El -.Pp -The following values may also be included in -.Fa flags , -however, they are non-standard extensions to -.St -p1003.2 . -.Bl -tag -width GLOB_ALTDIRFUNC -.It Dv GLOB_ALTDIRFUNC -The following additional fields in the pglob structure have been -initialized with alternate functions for glob to use to open, read, -and close directories and to get stat information on names found -in those directories. -.Bd -literal -void *(*gl_opendir)(const char * name); -struct dirent *(*gl_readdir)(void *); -void (*gl_closedir)(void *); -int (*gl_lstat)(const char *name, struct stat *st); -int (*gl_stat)(const char *name, struct stat *st); -.Ed -.Pp -This extension is provided to allow programs such as -.Xr restore 8 -to provide globbing from directories stored on tape. -.It Dv GLOB_BRACE -Pre-process the pattern string to expand -.Ql {pat,pat,...} -strings like -.Xr csh 1 . -The pattern -.Ql {} -is left unexpanded for historical reasons (and -.Xr csh 1 -does the same thing to -ease typing -of -.Xr find 1 -patterns). -.It Dv GLOB_MAGCHAR -Set by the -.Fn glob -function if the pattern included globbing characters. -See the description of the usage of the -.Fa gl_matchc -structure member for more details. -.It Dv GLOB_NOMAGIC -Is the same as -.Dv GLOB_NOCHECK -but it only appends the -.Fa pattern -if it does not contain any of the special characters ``*'', ``?'' or ``[''. -.Dv GLOB_NOMAGIC -is provided to simplify implementing the historic -.Xr csh 1 -globbing behavior and should probably not be used anywhere else. -.It Dv GLOB_QUOTE -Use the backslash -.Pq Ql \e -character for quoting: every occurrence of -a backslash followed by a character in the pattern is replaced by that -character, avoiding any special interpretation of the character. -.It Dv GLOB_TILDE -Expand patterns that start with -.Ql ~ -to user name home directories. -.It Dv GLOB_LIMIT -Limit the total number of returned pathnames to the value provided in -.Fa gl_matchc -(default -.Dv ARG_MAX ) . -This option should be set for programs -that can be coerced into a denial of service attack -via patterns that expand to a very large number of matches, -such as a long string of -.Ql */../*/.. . -.El -.Pp -If, during the search, a directory is encountered that cannot be opened -or read and -.Fa errfunc -is -.Pf non- Dv NULL , -.Fn glob -calls -.Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) . -This may be unintuitive: a pattern like -.Ql */Makefile -will try to -.Xr stat 2 -.Ql foo/Makefile -even if -.Ql foo -is not a directory, resulting in a -call to -.Fa errfunc . -The error routine can suppress this action by testing for -.Er ENOENT -and -.Er ENOTDIR ; -however, the -.Dv GLOB_ERR -flag will still cause an immediate -return when this happens. -.Pp -If -.Fa errfunc -returns non-zero, -.Fn glob -stops the scan and returns -.Dv GLOB_ABEND -after setting -.Fa gl_pathc -and -.Fa gl_pathv -to reflect any paths already matched. -This also happens if an error is encountered and -.Dv GLOB_ERR -is set in -.Fa flags , -regardless of the return value of -.Fa errfunc , -if called. -If -.Dv GLOB_ERR -is not set and either -.Fa errfunc -is -.Dv NULL -or -.Fa errfunc -returns zero, the error is ignored. -.Pp -The -.Fn globfree -function frees any space associated with -.Fa pglob -from a previous call(s) to -.Fn glob . -.Sh RETURN VALUES -On successful completion, -.Fn glob -returns zero. -In addition the fields of -.Fa pglob -contain the values described below: -.Bl -tag -width GLOB_NOCHECK -.It Fa gl_pathc -contains the total number of matched pathnames so far. -This includes other matches from previous invocations of -.Fn glob -if -.Dv GLOB_APPEND -was specified. -.It Fa gl_matchc -contains the number of matched pathnames in the current invocation of -.Fn glob . -.It Fa gl_flags -contains a copy of the -.Fa flags -parameter with the bit -.Dv GLOB_MAGCHAR -set if -.Fa pattern -contained any of the special characters ``*'', ``?'' or ``['', cleared -if not. -.It Fa gl_pathv -contains a pointer to a -.Dv NULL Ns -terminated -list of matched pathnames. -However, if -.Fa gl_pathc -is zero, the contents of -.Fa gl_pathv -are undefined. -.El -.Pp -If -.Fn glob -terminates due to an error, it sets errno and returns one of the -following non-zero constants, which are defined in the include -file -.Aq Pa glob.h : -.Bl -tag -width GLOB_NOCHECK -.It Dv GLOB_NOSPACE -An attempt to allocate memory failed, or if -.Fa errno -was 0 -.Dv GLOB_LIMIT -was specified in the flags and -.Fa pglob\->gl_matchc -or more patterns were matched. -.It Dv GLOB_ABEND -The scan was stopped because an error was encountered and either -.Dv GLOB_ERR -was set or -.Fa \*(lp*errfunc\*(rp\*(lp\*(rp -returned non-zero. -.El -.Pp -The arguments -.Fa pglob\->gl_pathc -and -.Fa pglob\->gl_pathv -are still set as specified above. -.Sh EXAMPLES -A rough equivalent of -.Ql "ls -l *.c *.h" -can be obtained with the -following code: -.Bd -literal -offset indent -glob_t g; - -g.gl_offs = 2; -glob("*.c", GLOB_DOOFFS, NULL, &g); -glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); -g.gl_pathv[0] = "ls"; -g.gl_pathv[1] = "-l"; -execvp("ls", g.gl_pathv); -.Ed -.Sh SEE ALSO -.Xr sh 1 , -.Xr fnmatch 3 , -.Xr regexp 3 -.Sh STANDARDS -The -.Fn glob -function is expected to be -.St -p1003.2 -compatible with the exception -that the flags -.Dv GLOB_ALTDIRFUNC , -.Dv GLOB_BRACE , -.Dv GLOB_LIMIT , -.Dv GLOB_MAGCHAR , -.Dv GLOB_NOMAGIC , -.Dv GLOB_QUOTE , -and -.Dv GLOB_TILDE , -and the fields -.Fa gl_matchc -and -.Fa gl_flags -should not be used by applications striving for strict -.Tn POSIX -conformance. -.Sh HISTORY -The -.Fn glob -and -.Fn globfree -functions first appeared in -.Bx 4.4 . -.Sh BUGS -Patterns longer than -.Dv MAXPATHLEN -may cause unchecked errors. -.Pp -The -.Fn glob -argument -may fail and set errno for any of the errors specified for the -library routines -.Xr stat 2 , -.Xr closedir 3 , -.Xr opendir 3 , -.Xr readdir 3 , -.Xr malloc 3 , -and -.Xr free 3 . |