Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)