.\" 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.
.\"
.\" 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 ,
+.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
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 {
- 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;
.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)
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 ) .
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
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
.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
-.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
-was 0
+was E2BIG,
.Dv GLOB_LIMIT
was specified in the flags and
.Fa pglob\->gl_matchc
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
-The
+The current implementation of the
.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 ,
.Fa gl_matchc
and
.Fa gl_flags
-should not be used by applications striving for strict
+are extensions to the
.Tn POSIX
+standard and
+should not be used by applications striving for strict
conformance.
.Sh HISTORY
The
.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
.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 ,
projects / apple / libc.git / blobdiff