Libc-594.9.4.tar.gz

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

--- glob.3.orig	2009-05-12 11:21:55.000000000 -0700
+++ glob.3	2009-05-20 15:39:07.000000000 -0700
@@ -34,21 +34,38 @@
 .\"     @(#)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 $
 .\"
-.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
@@ -326,18 +343,39 @@
 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
@@ -345,12 +383,22 @@
 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
@@ -373,6 +421,10 @@
 .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
@@ -418,6 +470,18 @@
 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 ,
@@ -456,6 +520,11 @@
 .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
@@ -463,7 +532,13 @@
 .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 ,