Libc-1439.100.3.tar.gz

[apple/libc.git] / gen / FreeBSD / glob.3

diff --git a/gen/FreeBSD/glob.3 b/gen/FreeBSD/glob.3
index ce07fddf17a01c07d912b7acb11f96207f95029e..75bebc477f2e56b6370258cbf48f74438da4db52 100644 (file)
--- a/gen/FreeBSD/glob.3
+++ b/gen/FreeBSD/glob.3
@@ -11,11 +11,7 @@
 .\" 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.
 .\" 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
+.\" 3. 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.
 .\"
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"


@@ -32,21 +28,22 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)glob.3     8.3 (Berkeley) 4/16/94
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)glob.3     8.3 (Berkeley) 4/16/94

-.\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.23 2003/02/04 16:28:04 mikeh Exp $
+.\" $FreeBSD$

 .\"
 .\"

-.Dd April 16, 1994
+.Dd June 11, 2017

 .Dt GLOB 3
 .Os
 .Sh NAME
 .Nm glob ,
 .Dt GLOB 3
 .Os
 .Sh NAME
 .Nm glob ,

+.Nm glob_b ,

 .Nm globfree
 .Nd generate pathnames matching a pattern
 .Nm globfree
 .Nd generate pathnames matching a pattern

-.Sh LIBRARY
-.Lb libc

 .Sh SYNOPSIS
 .In glob.h
 .Ft int
 .Sh SYNOPSIS
 .In glob.h
 .Ft int

-.Fn glob "const char *pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t *pglob"
+.Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *epath, int errno)" "glob_t * restrict pglob"
+.Ft int
+.Fn glob_b "const char * restrict pattern" "int flags" "int (^errblk)(const char *epath, int errno)" "glob_t * restrict pglob"

 .Ft void
 .Fn globfree "glob_t *pglob"
 .Sh DESCRIPTION
 .Ft void
 .Fn globfree "glob_t *pglob"
 .Sh DESCRIPTION


@@ -57,15 +54,15 @@ is a pathname generator that implements the rules for file name pattern
 matching used by the shell.
 .Pp
 The include file
 matching used by the shell.
 .Pp
 The include file

-.Pa glob.h
+.In glob.h

 defines the structure type
 .Fa glob_t ,
 which contains at least the following fields:
 .Bd -literal
 typedef struct {
 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 */
+       size_t gl_pathc;        /* count of total paths so far */

        int gl_matchc;          /* count of paths matching pattern */
        int gl_matchc;          /* count of paths matching pattern */

-       int gl_offs;            /* reserved at beginning of gl_pathv */
+       size_t gl_offs;         /* reserved at beginning of gl_pathv */

        int gl_flags;           /* returned flags */
        char **gl_pathv;        /* list of paths matching pattern */
 } glob_t;
        int gl_flags;           /* returned flags */
        char **gl_pathv;        /* list of paths matching pattern */
 } glob_t;


@@ -121,7 +118,7 @@ is the bitwise inclusive
 .Tn OR
 of any of the following
 values defined in
 .Tn OR
 of any of the following
 values defined in

-.Pa glob.h :
+.In glob.h :

 .Bl -tag -width GLOB_ALTDIRFUNC
 .It Dv GLOB_APPEND
 Append pathnames generated to the ones from a previous call (or calls)
 .Bl -tag -width GLOB_ALTDIRFUNC
 .It Dv GLOB_APPEND
 Append pathnames generated to the ones from a previous call (or calls)


@@ -198,7 +195,7 @@ If
 is set, backslash escaping is disabled.
 .It Dv GLOB_NOSORT
 By default, the pathnames are sorted in ascending
 is set, backslash escaping is disabled.
 .It Dv GLOB_NOSORT
 By default, the pathnames are sorted in ascending

-.Tn ASCII
+collation

 order;
 this flag prevents that sorting (speeding up
 .Fn glob ) .
 order;
 this flag prevents that sorting (speeding up
 .Fn glob ) .


@@ -328,16 +325,27 @@ or
 returns zero, the error is ignored.
 .Pp
 The
 returns zero, the error is ignored.
 .Pp
 The

+.Fn glob_b
+function is like
+.Fn glob
+except that the error callback is a block pointer instead of a function
+pointer.
+.Pp
+The

 .Fn globfree
 function frees any space associated with
 .Fa pglob
 from a previous call(s) to
 .Fn globfree
 function frees any space associated with
 .Fa pglob
 from a previous call(s) to

-.Fn glob .
+.Fn glob
+or
+.Fn glob_b .

 .Sh RETURN VALUES
 On successful completion,
 .Fn glob
 .Sh RETURN VALUES
 On successful completion,
 .Fn glob

-returns zero.
-In addition the fields of
+and
+.Fn glob_b
+return zero.
+In addition, the fields of

 .Fa pglob
 contain the values described below:
 .Bl -tag -width GLOB_NOCHECK
 .Fa pglob
 contain the values described below:
 .Bl -tag -width GLOB_NOCHECK


@@ -345,12 +353,16 @@ contain the values described below:
 contains the total number of matched pathnames so far.
 This includes other matches from previous invocations of
 .Fn glob
 contains the total number of matched pathnames so far.
 This includes other matches from previous invocations of
 .Fn glob

+or
+.Fn glob_b

 if
 .Dv GLOB_APPEND
 was specified.
 .It Fa gl_matchc
 contains the number of matched pathnames in the current invocation of
 if
 .Dv GLOB_APPEND
 was specified.
 .It Fa gl_matchc
 contains the number of matched pathnames in the current invocation of

-.Fn glob .
+.Fn glob
+or
+.Fn glob_b .

 .It Fa gl_flags
 contains a copy of the
 .Fa flags
 .It Fa gl_flags
 contains a copy of the
 .Fa flags


@@ -373,15 +385,17 @@ are undefined.
 .Pp
 If
 .Fn glob
 .Pp
 If
 .Fn glob

+or
+.Fn glob_b

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

 .Bl -tag -width GLOB_NOCHECK
 .It Dv GLOB_NOSPACE
 An attempt to allocate memory failed, or if
 .Fa errno
 .Bl -tag -width GLOB_NOCHECK
 .It Dv GLOB_NOSPACE
 An attempt to allocate memory failed, or if
 .Fa errno

-was 0
+was E2BIG,

 .Dv GLOB_LIMIT
 was specified in the flags and
 .Fa pglob\->gl_matchc
 .Dv GLOB_LIMIT
 was specified in the flags and
 .Fa pglob\->gl_matchc


@@ -418,17 +432,29 @@ g.gl_pathv[0] = "ls";
 g.gl_pathv[1] = "-l";
 execvp("ls", g.gl_pathv);
 .Ed
 g.gl_pathv[1] = "-l";
 execvp("ls", g.gl_pathv);
 .Ed

+.Sh CAVEATS
+The
+.Fn glob
+and
+.Fn glob_b
+functions
+will not match filenames that begin with a period
+unless this is specifically requested (e.g., by ".*").

 .Sh SEE ALSO
 .Xr sh 1 ,
 .Xr fnmatch 3 ,
 .Xr regexp 3
 .Sh STANDARDS
 .Sh SEE ALSO
 .Xr sh 1 ,
 .Xr fnmatch 3 ,
 .Xr regexp 3
 .Sh STANDARDS

-The
+The current implementation of the

 .Fn glob
 .Fn glob

-function is expected to be
-.St -p1003.2
-compatible with the exception
-that the flags
+function
+.Em does not
+conform to
+.St -p1003.2 .
+Collating symbol expressions, equivalence class expressions and
+character class expressions are not supported.
+.Pp
+The flags

 .Dv GLOB_ALTDIRFUNC ,
 .Dv GLOB_BRACE ,
 .Dv GLOB_LIMIT ,
 .Dv GLOB_ALTDIRFUNC ,
 .Dv GLOB_BRACE ,
 .Dv GLOB_LIMIT ,


@@ -440,8 +466,10 @@ and the fields
 .Fa gl_matchc
 and
 .Fa gl_flags
 .Fa gl_matchc
 and
 .Fa gl_flags

-should not be used by applications striving for strict
+are extensions to the

 .Tn POSIX
 .Tn POSIX

+standard and
+should not be used by applications striving for strict

 conformance.
 .Sh HISTORY
 The
 conformance.
 .Sh HISTORY
 The


@@ -450,6 +478,9 @@ and
 .Fn globfree
 functions first appeared in
 .Bx 4.4 .
 .Fn globfree
 functions first appeared in
 .Bx 4.4 .

+The
+.Fn glob_b
+function first appeared in Mac OS X 10.6.

 .Sh BUGS
 Patterns longer than
 .Dv MAXPATHLEN
 .Sh BUGS
 Patterns longer than
 .Dv MAXPATHLEN


@@ -457,7 +488,9 @@ may cause unchecked errors.
 .Pp
 The
 .Fn glob
 .Pp
 The
 .Fn glob

-argument
+and
+.Fn glob_b
+functions

 may fail and set errno for any of the errors specified for the
 library routines
 .Xr stat 2 ,
 may fail and set errno for any of the errors specified for the
 library routines
 .Xr stat 2 ,