BSD 4_3_Net_2 release

[unix-history] / usr / src / lib / libc / gen / glob.3

diff --git a/usr/src/lib/libc/gen/glob.3 b/usr/src/lib/libc/gen/glob.3
index fb10f66..5b2a140 100644 (file)
--- a/usr/src/lib/libc/gen/glob.3
+++ b/usr/src/lib/libc/gen/glob.3
@@ -1,269 +1,364 @@
-.\" Copyright (c) 1989 The Regents of the University of California.
+.\" Copyright (c) 1989, 1991 The Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to Berkeley by
 .\" Guido van Rossum.
 .\" 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.

 .\"
 .\"

-.\" Redistribution and use in source and binary forms are permitted provided
-.\" that: (1) source distributions retain this entire copyright notice and
-.\" comment, and (2) distributions including binaries display the following
-.\" acknowledgement:  ``This product includes software developed by the
-.\" University of California, Berkeley and its contributors'' in the
-.\" documentation or other materials provided with the distribution and in
-.\" all advertising materials mentioning features or use of this software.
-.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
-.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" 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      5.2 (Berkeley) 6/23/90
+.\"     @(#)glob.3     5.6 (Berkeley) 7/31/91

 .\"
 .\"

-.TH GLOB 3 "June 23, 1990"
-.UC 7
-.SH NAME
-glob, globfree \- generate pathnames matching a pattern
-.SH SYNOPSIS
-.nf
-#include <glob.h>
-
-glob(const char *pattern, int flags,
-       const int (*errfunc)(char *, int), glob_t *pglob);
-
-void globfree(glob_t *pglob);
-.fi
-.SH DESCRIPTION
-.I Glob
+.Dd July 31, 1991
+.Dt GLOB 3
+.Os
+.Sh NAME
+.Nm glob ,
+.Nm globfree
+.Nd generate pathnames matching a pattern
+.Sh SYNOPSIS
+.Fd #include <glob.h>
+.Ft int
+.Fn glob "const char *pattern" "int flags" "const int (*errfunc)(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.
 is a pathname generator that implements the rules for file name pattern
 matching used by the shell.

-.PP
+.Pp

 The include file
 The include file

-.I glob.h
+.Pa glob.h

 defines the structure type
 defines the structure type

-.IR glob_t ,
+.Fa glob_t ,

 which contains at least the following fields:
 which contains at least the following fields:

-.sp
-.RS
-.nf
-.ta .5i +\w'char **gl_pathv;\0\0\0'u
+.Bd -literal

 typedef struct {
 typedef struct {

-       int gl_pathc;           /* count of paths matching pattern */
+       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_offs;            /* reserved at beginning of gl_pathv */

+       int gl_flags;           /* returned flags */

        char **gl_pathv;        /* list of paths matching pattern */
 } glob_t;
        char **gl_pathv;        /* list of paths matching pattern */
 } glob_t;

-.fi
-.RE
-.PP
+.Ed
+.Pp

 The argument
 The argument

-.I pattern
+.Fa pattern

 is a pointer to a pathname pattern to be expanded.
 is a pointer to a pathname pattern to be expanded.

-.I Glob
+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,
 matches all accessible pathnames against the pattern and creates
 a list of the pathnames that match.
 In order to have access to a pathname,

-.I glob
+.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
 requires search permission on every component of a path except the last
 and read permission on each directory of any filename component of

-.I pattern
-that contains any of the special characters ``*'', ``?'' or ``[''.
-.PP
-.I Glob
+.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
 stores the number of matched pathnames into the

-.I gl_pathc
+.Fa gl_pathc

 field, and a pointer to a list of pointers to pathnames into the
 field, and a pointer to a list of pointers to pathnames into the

-.I gl_pathv
+.Fa gl_pathv

 field.
 field.

-The first pointer after the last pathname is NULL.
+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.
 If the pattern does not match any pathnames, the returned number of
 matched paths is set to zero.

-.PP
+.Pp

 It is the caller's responsibility to create the structure pointed to by
 It is the caller's responsibility to create the structure pointed to by

-.IR pglob .
+.Fa pglob .

 The
 The

-.I glob
+.Fn glob

 function allocates other space as needed, including the memory pointed
 to by
 function allocates other space as needed, including the memory pointed
 to by

-.IR gl_pathv .
-.PP
+.Fa gl_pathv .
+.Pp

 The argument
 The argument

-.I flags
+.Fa flags

 is used to modify the behavior of
 is used to modify the behavior of

-.IR glob .
+.Fn glob .

 The value of
 The value of

-.I flags
-is the bitwise inclusive OR of any of the following
+.Fa flags
+is the bitwise inclusive
+.Tn OR
+of any of the following

 values defined in
 values defined in

-.IR glob.h :
-.TP
-GLOB_APPEND
+.Pa glob.h :
+.Bl -tag -width GLOB_NOCHECK
+.It Dv GLOB_APPEND

 Append pathnames generated to the ones from a previous call (or calls)
 to
 Append pathnames generated to the ones from a previous call (or calls)
 to

-.IR glob .
+.Fn glob .

 The value of
 The value of

-.I gl_pathc
+.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
 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

-GLOB_DOOFFS flag, nor change the value of
-.I gl_offs
+.Dv GLOB_DOOFFS
+flag, nor change the value of
+.Fa gl_offs

 when
 when

-GLOB_DOOFFS is set, nor (obviously) call
-.I globfree
+.Dv GLOB_DOOFFS
+is set, nor (obviously) call
+.Fn globfree

 for
 for

-.I pglob.
-.TP
-GLOB_DOOFFS
+.Fa pglob .
+.It Dv GLOB_DOOFFS

 Make use of the
 Make use of the

-.I gl_offs
+.Fa gl_offs

 field.
 If this flag is set,
 field.
 If this flag is set,

-.I gl_offs
-is used to specify how many NULL pointers to prepend to the beginning
+.Fa gl_offs
+is used to specify how many
+.Dv NULL
+pointers to prepend to the beginning

 of the
 of the

-.I gl_pathv
+.Fa gl_pathv

 field.
 In other words,
 field.
 In other words,

-.I gl_pathv
+.Fa gl_pathv

 will point to
 will point to

-.I gl_offs
-NULL pointers,
+.Fa gl_offs
+.Dv NULL
+pointers,

 followed by
 followed by

-.I gl_pathc
-pathname pointers, followed by a NULL pointer.
-.TP
-GLOB_ERR
+.Fa gl_pathc
+pathname pointers, followed by a
+.Dv NULL
+pointer.
+.It Dv GLOB_ERR

 Causes
 Causes

-.I glob
+.Fn glob

 to return when it encounters a directory that it cannot open or read.
 Ordinarily,
 to return when it encounters a directory that it cannot open or read.
 Ordinarily,

-.I glob
+.Fn glob

 continues to find matches.
 continues to find matches.

-.TP
-GLOB_MARK
+.It Dv GLOB_MARK

 Each pathname that is a directory that matches
 Each pathname that is a directory that matches

-.I pattern
+.Fa pattern

 has a slash
 appended.
 has a slash
 appended.

-.TP
-GLOB_NOSORT
-By default, the pathnames are sorted in ascending ASCII order;
-this flag prevents that sorting (speeding up
-.IR glob ).
-.TP
-GLOB_NOCHECK
+.It Dv GLOB_NOCHECK

 If
 If

-.I pattern
+.Fa pattern

 does not match any pathname, then
 does not match any pathname, then

-.I glob
+.Fn glob

 returns a list
 consisting of only
 returns a list
 consisting of only

-.IR pattern ,
-and the number of matched pathnames is set to 1.
+.Fa pattern ,
+with the number of total pathnames is set to 1, and the number of matched
+pathnames set to 0.

 If
 If

-.I GLOB_QUOTE
+.Dv GLOB_QUOTE

 is set, its effect is present in the pattern returned.
 is set, its effect is present in the pattern returned.

-.TP
-GLOB_QUOTE
-Use the backslash (``\e'') character for quoting: every occurrence of
+.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_NOSORT
+By default, the pathnames are sorted in ascending
+.Tn ASCII
+order;
+this flag prevents that sorting (speeding up
+.Fn glob ) .
+.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.
 a backslash followed by a character in the pattern is replaced by that
 character, avoiding any special interpretation of the character.

-.PP
+.El
+.Pp

 If, during the search, a directory is encountered that cannot be opened
 or read and
 If, during the search, a directory is encountered that cannot be opened
 or read and

-.I errfunc
-is non-NULL,
-.I glob
-calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP).
-This may be unintuitive: a pattern like ``*/Makefile'' will try to
-.IR stat (2)
-``foo/Makefile'' even if ``foo'' is not a directory, resulting in a
+.Fa errfunc
+is
+.Pf non- Dv NULL , 
+.Fn glob
+calls
+.Fa (*errfunc)(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
 call to

-.IR errfunc .
-The error routine can suppress this action by testing for ENOENT and
-ENOTDIR; however, the GLOB_ERR flag will still cause an immediate
+.Fa errfunc .
+The error routine can suppress this action by testing for
+.Dv ENOENT
+and
+.Dv ENOTDIR ; 
+however, the
+.Dv GLOB_ERR
+flag will still cause an immediate

 return when this happens.
 return when this happens.

-.PP
+.Pp

 If
 If

-.I errfunc
+.Fa errfunc

 returns non-zero,
 returns non-zero,

-.I glob
+.Fn glob

 stops the scan and returns
 stops the scan and returns

-.I GLOB_ABEND
+.Dv GLOB_ABEND

 after setting
 after setting

-.I gl_pathc
+.Fa gl_pathc

 and
 and

-.I gl_pathv
+.Fa gl_pathv

 to reflect any paths already matched.
 This also happens if an error is encountered and
 to reflect any paths already matched.
 This also happens if an error is encountered and

-.I GLOB_ERR
+.Dv GLOB_ERR

 is set in
 is set in

-.IR flags ,
+.Fa flags ,

 regardless of the return value of
 regardless of the return value of

-.IR errfunc ,
+.Fa errfunc ,

 if called.
 If
 if called.
 If

-.I GLOB_ERR
+.Dv GLOB_ERR

 is not set and either
 is not set and either

-.I errfunc
-is NULL or
-.I errfunc
+.Fa errfunc
+is
+.Dv NULL
+or
+.Fa errfunc

 returns zero, the error is ignored.
 returns zero, the error is ignored.

-.PP
+.Pp

 The
 The

-.I globfree
+.Fn globfree

 function frees any space associated with
 function frees any space associated with

-.I pglob
+.Fa pglob

 from a previous call(s) to
 from a previous call(s) to

-.IR glob .
-.SH RETURNS
+.Fn glob .
+.Sh RETURN VALUES

 On successful completion,
 On successful completion,

-.I glob
+.Fn glob

 returns zero.
 returns zero.

-The field
-.I gl_pathc
-returns the number of matched pathnames and
-the field
-.I gl_pathv
-contains a pointer to a NULL-terminated list of matched pathnames.
+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
 However, if

-.I pglob->gl_pathc
+.Fa gl_pathc

 is zero, the contents of
 is zero, the contents of

-.I pglob->gl_pathv
-is undefined.
-.PP
+.Fa gl_pathv
+are undefined.
+.El
+.Pp

 If
 If

-.I glob
+.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
 terminates due to an error, it sets errno and returns one of the
 following non-zero constants, which are defined in the include

-file <glob.h>:
-.TP
-GLOB_NOSPACE
+file
+.Aq Pa glob.h :
+.Bl -tag -width GLOB_NOCHECK
+.It Dv GLOB_NOSPACE

 An attempt to allocate memory failed.
 An attempt to allocate memory failed.

-.TP
-GLOB_ABEND
+.It Dv GLOB_ABEND

 The scan was stopped because an error was encountered and either
 The scan was stopped because an error was encountered and either

-GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero.
-.PP
+.Dv GLOB_ERR
+was set or
+.Fa (*errfunc)()
+returned non-zero.
+.El
+.Pp

 The arguments
 The arguments

-.I pglob->gl_pathc
+.Fa pglob\->gl_pathc

 and
 and

-.I pglob->gl_pathv
+.Fa pglob\->gl_pathv

 are still set as specified above.
 are still set as specified above.

-.SH STANDARDS
+.Sh SEE ALSO
+.Xr sh 1 ,
+.Xr fnmatch 3 ,
+.Xr wordexp 3 ,
+.Xr regexp 3
+.Sh STANDARDS

 The
 The

-.I glob
-function is expected to be POSIX 1003.2 compatible with the exception
-that the flag GLOB_QUOTE should not be used by applications striving
-for strict POSIX conformance.
-.SH EXAMPLE
-A rough equivalent of ``ls -l *.c *.h'' can be obtained with the
+.Fn glob
+function is expected to be
+.St -p1003.2
+compatible with the exception
+that the flag 
+.Dv GLOB_QUOTE
+and the fields 
+.Fa gl_matchc
+and 
+.Fa gl_flags
+should not be used by applications striving for strict
+.Tn POSIX
+conformance.
+.Sh EXAMPLE
+A rough equivalent of
+.Ql "ls -l *.c *.h"
+can be obtained with the

 following code:
 following code:

-.sp
-.nf
-.RS
-glob_t g;
+.Bd -literal -offset indent
+GLOB_t g;

 
 g.gl_offs = 2;
 glob("*.c", GLOB_DOOFFS, NULL, &g);
 
 g.gl_offs = 2;
 glob("*.c", GLOB_DOOFFS, NULL, &g);


@@ -271,21 +366,28 @@ glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
 g.gl_pathv[0] = "ls";
 g.gl_pathv[1] = "-l";
 execvp("ls", g.gl_pathv);
 g.gl_pathv[0] = "ls";
 g.gl_pathv[1] = "-l";
 execvp("ls", g.gl_pathv);

-.RE
-.fi
-.SH SEE ALSO
-sh(1), fnmatch(3), wordexp(3), regexp(3)
-.SH BUGS
-Patterns longer than MAXPATHLEN may cause unchecked errors.
-.PP
-.I Glob
+.Ed
+.Sh HISTORY
+The
+.Fn glob
+and
+.Fn globfree
+functions are
+.Ud .
+.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
 may fail and set errno for any of the errors specified for the
 library routines

-.I stat (2),
-.I closedir (3),
-.I opendir (3),
-.I readdir (3),
-.I malloc (3),
+.Xr stat 2 ,
+.Xr closedir 3 ,
+.Xr opendir 3 ,
+.Xr readdir 3 ,
+.Xr malloc 3 ,

 and
 and

-.I free (3).
-
+.Xr free 3 .