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 6baa5683a7b437ec869bb166e666a4388009ab70..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.
-.\" 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.
 .\"
@@ -32,21 +28,22 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)glob.3     8.3 (Berkeley) 4/16/94
-.\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.30 2004/09/01 23:28:27 tjr Exp $
+.\" $FreeBSD$
 .\"
-.Dd September 1, 2004
+.Dd June 11, 2017
 .Dt GLOB 3
 .Os
 .Sh NAME
 .Nm glob ,
+.Nm glob_b ,
 .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"
+.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
@@ -63,9 +60,9 @@ defines the structure type
 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_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;
@@ -198,7 +195,7 @@ If
 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 ) .
@@ -328,16 +325,27 @@ or
 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 glob .
+.Fn glob
+or
+.Fn glob_b .
 .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
@@ -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
+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
-.Fn glob .
+.Fn glob
+or
+.Fn glob_b .
 .It Fa gl_flags
 contains a copy of the
 .Fa flags
@@ -373,6 +385,8 @@ are undefined.
 .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
@@ -381,7 +395,7 @@ file
 .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
@@ -418,6 +432,14 @@ g.gl_pathv[0] = "ls";
 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 ,
@@ -456,6 +478,9 @@ and
 .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
@@ -463,7 +488,9 @@ may cause unchecked errors.
 .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 ,