Libc-825.24.tar.gz

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

diff --git a/gen/FreeBSD/glob.3 b/gen/FreeBSD/glob.3
index 4473427b55a053bcfe3121b29f5ffaf935648e5f..a71c96b4e79bb31e14bc3eee31f397f0f231495d 100644 (file)
--- a/gen/FreeBSD/glob.3
+++ b/gen/FreeBSD/glob.3
@@ -30,21 +30,38 @@
 .\"     @(#)glob.3     8.3 (Berkeley) 4/16/94
 .\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.32 2007/01/09 00:27:54 imp Exp $
 .\"
-.Dd September 1, 2004
+.Dd May 20, 2008
 .Dt GLOB 3
 .Os
 .Sh NAME
 .Nm glob ,
+#ifdef UNIFDEF_BLOCKS
+.Nm glob_b ,
+#endif
 .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"
+.Fo glob
+.Fa "const char *restrict pattern"
+.Fa "int flags"
+.Fa "int (*errfunc)(const char *epath, int errno)"
+.Fa "glob_t *restrict pglob"
+.Fc
+#ifdef UNIFDEF_BLOCKS
+.Ft int
+.Fo glob_b
+.Fa "const char *restrict pattern"
+.Fa "int flags"
+.Fa "int (^errblk)(const char *epath, int errno)"
+.Fa "glob_t *restrict pglob"
+.Fc
+#endif
 .Ft void
-.Fn globfree "glob_t *pglob"
+.Fo globfree
+.Fa "glob_t *pglob"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn glob
@@ -60,7 +77,7 @@ which contains at least the following fields:
 .Bd -literal
 typedef struct {
        size_t gl_pathc;        /* count of total paths so far */
-       size_t gl_matchc;       /* count of paths matching pattern */
+       int gl_matchc;          /* count of paths matching pattern */
        size_t gl_offs;         /* reserved at beginning of gl_pathv */
        int gl_flags;           /* returned flags */
        char **gl_pathv;        /* list of paths matching pattern */
@@ -322,18 +339,39 @@ is
 or
 .Fa errfunc
 returns zero, the error is ignored.
+#ifdef UNIFDEF_BLOCKS
+.Pp
+The
+.Fn glob_b
+function is like
+.Fn glob
+except that the error callback is a block pointer instead of a function
+pointer.
+#endif
 .Pp
 The
 .Fn globfree
 function frees any space associated with
 .Fa pglob
 from a previous call(s) to
+#ifdef UNIFDEF_BLOCKS
+.Fn glob
+or
+.Fn glob_b .
+#else
 .Fn glob .
+#endif
 .Sh RETURN VALUES
 On successful completion,
 .Fn glob
+#ifdef UNIFDEF_BLOCKS
+and
+.Fn glob_b
+return zero.
+#else
 returns zero.
-In addition the fields of
+#endif
+In addition, the fields of
 .Fa pglob
 contain the values described below:
 .Bl -tag -width GLOB_NOCHECK
@@ -341,12 +379,22 @@ contain the values described below:
 contains the total number of matched pathnames so far.
 This includes other matches from previous invocations of
 .Fn glob
+#ifdef UNIFDEF_BLOCKS
+or
+.Fn glob_b
+#endif
 if
 .Dv GLOB_APPEND
 was specified.
 .It Fa gl_matchc
 contains the number of matched pathnames in the current invocation of
+#ifdef UNIFDEF_BLOCKS
+.Fn glob
+or
+.Fn glob_b .
+#else
 .Fn glob .
+#endif
 .It Fa gl_flags
 contains a copy of the
 .Fa flags
@@ -369,6 +417,10 @@ are undefined.
 .Pp
 If
 .Fn glob
+#ifdef UNIFDEF_BLOCKS
+or
+.Fn glob_b
+#endif
 terminates due to an error, it sets errno and returns one of the
 following non-zero constants, which are defined in the include
 file
@@ -414,6 +466,18 @@ g.gl_pathv[0] = "ls";
 g.gl_pathv[1] = "-l";
 execvp("ls", g.gl_pathv);
 .Ed
+.Sh CAVEATS
+The
+.Fn glob
+#ifdef UNIFDEF_BLOCKS
+and
+.Fn glob_b
+functions
+#else
+function
+#endif
+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 ,
@@ -452,6 +516,11 @@ and
 .Fn globfree
 functions first appeared in
 .Bx 4.4 .
+#ifdef UNIFDEF_BLOCKS
+The
+.Fn glob_b
+function first appeared in Mac OS X 10.6.
+#endif
 .Sh BUGS
 Patterns longer than
 .Dv MAXPATHLEN
@@ -459,7 +528,13 @@ may cause unchecked errors.
 .Pp
 The
 .Fn glob
-argument
+#ifdef UNIFDEF_BLOCKS
+and
+.Fn glob_b
+functions
+#else
+function
+#endif
 may fail and set errno for any of the errors specified for the
 library routines
 .Xr stat 2 ,