gen/FreeBSD/glob.3.patch

   1 --- glob.3.orig 2011-01-26 13:57:29.000000000 -0800
   2 +++ glob.3      2011-01-26 14:02:29.000000000 -0800
   3 @@ -30,21 +30,38 @@
   4  .\"     @(#)glob.3     8.3 (Berkeley) 4/16/94
   5  .\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.32 2007/01/09 00:27:54 imp Exp $
   6  .\"
   7 -.Dd September 1, 2004
   8 +.Dd May 20, 2008
   9  .Dt GLOB 3
  10  .Os
  11  .Sh NAME
  12  .Nm glob ,
  13 +#ifdef UNIFDEF_BLOCKS
  14 +.Nm glob_b ,
  15 +#endif
  16  .Nm globfree
  17  .Nd generate pathnames matching a pattern
  18 -.Sh LIBRARY
  19 -.Lb libc
  20  .Sh SYNOPSIS
  21  .In glob.h
  22  .Ft int
  23 -.Fn glob "const char *pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t *pglob"
  24 +.Fo glob
  25 +.Fa "const char *restrict pattern"
  26 +.Fa "int flags"
  27 +.Fa "int (*errfunc)(const char *epath, int errno)"
  28 +.Fa "glob_t *restrict pglob"
  29 +.Fc
  30 +#ifdef UNIFDEF_BLOCKS
  31 +.Ft int
  32 +.Fo glob_b
  33 +.Fa "const char *restrict pattern"
  34 +.Fa "int flags"
  35 +.Fa "int (^errblk)(const char *epath, int errno)"
  36 +.Fa "glob_t *restrict pglob"
  37 +.Fc
  38 +#endif
  39  .Ft void
  40 -.Fn globfree "glob_t *pglob"
  41 +.Fo globfree
  42 +.Fa "glob_t *pglob"
  43 +.Fc
  44  .Sh DESCRIPTION
  45  The
  46  .Fn glob
  47 @@ -60,7 +77,7 @@
  48  .Bd -literal
  49  typedef struct {
  50         size_t gl_pathc;        /* count of total paths so far */
  51 -       size_t gl_matchc;       /* count of paths matching pattern */
  52 +       int gl_matchc;          /* count of paths matching pattern */
  53         size_t gl_offs;         /* reserved at beginning of gl_pathv */
  54         int gl_flags;           /* returned flags */
  55         char **gl_pathv;        /* list of paths matching pattern */
  56 @@ -322,18 +339,39 @@
  57  or
  58  .Fa errfunc
  59  returns zero, the error is ignored.
  60 +#ifdef UNIFDEF_BLOCKS
  61 +.Pp
  62 +The
  63 +.Fn glob_b
  64 +function is like
  65 +.Fn glob
  66 +except that the error callback is a block pointer instead of a function
  67 +pointer.
  68 +#endif
  69  .Pp
  70  The
  71  .Fn globfree
  72  function frees any space associated with
  73  .Fa pglob
  74  from a previous call(s) to
  75 +#ifdef UNIFDEF_BLOCKS
  76 +.Fn glob
  77 +or
  78 +.Fn glob_b .
  79 +#else
  80  .Fn glob .
  81 +#endif
  82  .Sh RETURN VALUES
  83  On successful completion,
  84  .Fn glob
  85 +#ifdef UNIFDEF_BLOCKS
  86 +and
  87 +.Fn glob_b
  88 +return zero.
  89 +#else
  90  returns zero.
  91 -In addition the fields of
  92 +#endif
  93 +In addition, the fields of
  94  .Fa pglob
  95  contain the values described below:
  96  .Bl -tag -width GLOB_NOCHECK
  97 @@ -341,12 +379,22 @@
  98  contains the total number of matched pathnames so far.
  99  This includes other matches from previous invocations of
 100  .Fn glob
 101 +#ifdef UNIFDEF_BLOCKS
 102 +or
 103 +.Fn glob_b
 104 +#endif
 105  if
 106  .Dv GLOB_APPEND
 107  was specified.
 108  .It Fa gl_matchc
 109  contains the number of matched pathnames in the current invocation of
 110 +#ifdef UNIFDEF_BLOCKS
 111 +.Fn glob
 112 +or
 113 +.Fn glob_b .
 114 +#else
 115  .Fn glob .
 116 +#endif
 117  .It Fa gl_flags
 118  contains a copy of the
 119  .Fa flags
 120 @@ -369,6 +417,10 @@
 121  .Pp
 122  If
 123  .Fn glob
 124 +#ifdef UNIFDEF_BLOCKS
 125 +or
 126 +.Fn glob_b
 127 +#endif
 128  terminates due to an error, it sets errno and returns one of the
 129  following non-zero constants, which are defined in the include
 130  file
 131 @@ -414,6 +466,18 @@
 132  g.gl_pathv[1] = "-l";
 133  execvp("ls", g.gl_pathv);
 134  .Ed
 135 +.Sh CAVEATS
 136 +The
 137 +.Fn glob
 138 +#ifdef UNIFDEF_BLOCKS
 139 +and
 140 +.Fn glob_b
 141 +functions
 142 +#else
 143 +function
 144 +#endif
 145 +will not match filenames that begin with a period
 146 +unless this is specifically requested (e.g., by ".*").
 147  .Sh SEE ALSO
 148  .Xr sh 1 ,
 149  .Xr fnmatch 3 ,
 150 @@ -452,6 +516,11 @@
 151  .Fn globfree
 152  functions first appeared in
 153  .Bx 4.4 .
 154 +#ifdef UNIFDEF_BLOCKS
 155 +The
 156 +.Fn glob_b
 157 +function first appeared in Mac OS X 10.6.
 158 +#endif
 159  .Sh BUGS
 160  Patterns longer than
 161  .Dv MAXPATHLEN
 162 @@ -459,7 +528,13 @@
 163  .Pp
 164  The
 165  .Fn glob
 166 -argument
 167 +#ifdef UNIFDEF_BLOCKS
 168 +and
 169 +.Fn glob_b
 170 +functions
 171 +#else
 172 +function
 173 +#endif
 174  may fail and set errno for any of the errors specified for the
 175  library routines
 176  .Xr stat 2 ,