Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/gen/glob.3
Show All 24 Lines | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" @(#)glob.3 8.3 (Berkeley) 4/16/94 | .\" @(#)glob.3 8.3 (Berkeley) 4/16/94 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd December 20, 2011 | .Dd May 5, 2014 | ||||
.Dt GLOB 3 | .Dt GLOB 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm glob , | .Nm glob , | ||||
.Nm glob_b , | |||||
.Nm globfree | .Nm globfree | ||||
.Nd generate pathnames matching a pattern | .Nd generate pathnames matching a pattern | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In glob.h | .In glob.h | ||||
.Ft int | .Ft int | ||||
.Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t * restrict pglob" | .Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t * restrict pglob" | ||||
.Ft int | |||||
.Fn glob_b "const char * restrict pattern" "int flags" "int (^errblock)(const char *, int)" "glob_t * restrict pglob" | |||||
.Ft void | .Ft void | ||||
.Fn globfree "glob_t *pglob" | .Fn globfree "glob_t *pglob" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn glob | .Fn glob | ||||
function | function | ||||
is a pathname generator that implements the rules for file name pattern | is a pathname generator that implements the rules for file name pattern | ||||
matching used by the shell. | matching used by the shell. | ||||
Show All 13 Lines | |||||
} glob_t; | } glob_t; | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
The argument | The argument | ||||
.Fa pattern | .Fa pattern | ||||
is a pointer to a pathname pattern to be expanded. | is a pointer to a pathname pattern to be expanded. | ||||
The | The | ||||
.Fn glob | .Fn glob | ||||
argument | function | ||||
matches all accessible pathnames against the pattern and creates | matches all accessible pathnames against the pattern and creates | ||||
a list of the pathnames that match. | a list of the pathnames that match. | ||||
In order to have access to a pathname, | In order to have access to a pathname, | ||||
.Fn glob | .Fn glob | ||||
requires search permission on every component of a path except the last | requires search permission on every component of a path except the last | ||||
and read permission on each directory of any filename component of | and read permission on each directory of any filename component of | ||||
.Fa pattern | .Fa pattern | ||||
that contains any of the special characters | that contains any of the special characters | ||||
.Ql * , | .Ql * , | ||||
.Ql ?\& | .Ql ?\& | ||||
or | or | ||||
.Ql \&[ . | .Ql \&[ . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn glob | .Fn glob | ||||
argument | function | ||||
stores the number of matched pathnames into the | stores the number of matched pathnames into the | ||||
.Fa gl_pathc | .Fa gl_pathc | ||||
field, and a pointer to a list of pointers to pathnames into the | field, and a pointer to a list of pointers to pathnames into the | ||||
.Fa gl_pathv | .Fa gl_pathv | ||||
field. | field. | ||||
The first pointer after the last pathname is | The first pointer after the last pathname is | ||||
.Dv NULL . | .Dv NULL . | ||||
If the pattern does not match any pathnames, the returned number of | If the pattern does not match any pathnames, the returned number of | ||||
▲ Show 20 Lines • Show All 218 Lines • ▼ Show 20 Lines | |||||
is not set and either | is not set and either | ||||
.Fa errfunc | .Fa errfunc | ||||
is | is | ||||
.Dv NULL | .Dv NULL | ||||
or | or | ||||
.Fa errfunc | .Fa errfunc | ||||
returns zero, the error is ignored. | returns zero, the error is ignored. | ||||
.Pp | .Pp | ||||
.Fn glob_b | |||||
is a block-based version of | |||||
.Fn glob . | |||||
where the error callback is the block pointer, | |||||
.Fa errblock . | |||||
.Pp | |||||
The | The | ||||
.Fn globfree | .Fn globfree | ||||
function frees any space associated with | function frees any space associated with | ||||
.Fa pglob | .Fa pglob | ||||
from a previous call(s) to | from a previous call(s) to | ||||
.Fn glob . | .Fn glob . | ||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
wblock: As above, it might be better to just state the difference and not what the other function does. | |||||
On successful completion, | On successful completion, | ||||
.Fn glob | .Fn glob | ||||
returns zero. | and | ||||
.Fn glob_b | |||||
return zero. | |||||
In addition the fields of | In addition the fields of | ||||
.Fa pglob | .Fa pglob | ||||
contain the values described below: | contain the values described below: | ||||
.Bl -tag -width GLOB_NOCHECK | .Bl -tag -width GLOB_NOCHECK | ||||
.It Fa gl_pathc | .It Fa gl_pathc | ||||
contains the total number of matched pathnames so far. | contains the total number of matched pathnames so far. | ||||
This includes other matches from previous invocations of | This includes other matches from previous invocations of | ||||
.Fn glob | .Fn glob | ||||
or | |||||
.Fn glob_b | |||||
if | if | ||||
.Dv GLOB_APPEND | .Dv GLOB_APPEND | ||||
was specified. | was specified. | ||||
.It Fa gl_matchc | .It Fa gl_matchc | ||||
contains the number of matched pathnames in the current invocation of | contains the number of matched pathnames in the current invocation of | ||||
.Fn glob . | .Fn glob | ||||
or | |||||
.Fn glob_b . | |||||
.It Fa gl_flags | .It Fa gl_flags | ||||
contains a copy of the | contains a copy of the | ||||
.Fa flags | .Fa flags | ||||
argument with the bit | argument with the bit | ||||
.Dv GLOB_MAGCHAR | .Dv GLOB_MAGCHAR | ||||
set if | set if | ||||
.Fa pattern | .Fa pattern | ||||
contained any of the special characters ``*'', ``?'' or ``['', cleared | contained any of the special characters ``*'', ``?'' or ``['', cleared | ||||
if not. | if not. | ||||
.It Fa gl_pathv | .It Fa gl_pathv | ||||
contains a pointer to a | contains a pointer to a | ||||
.Dv NULL Ns -terminated | .Dv NULL Ns -terminated | ||||
list of matched pathnames. | list of matched pathnames. | ||||
However, if | However, if | ||||
.Fa gl_pathc | .Fa gl_pathc | ||||
is zero, the contents of | is zero, the contents of | ||||
.Fa gl_pathv | .Fa gl_pathv | ||||
are undefined. | are undefined. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
If | If | ||||
.Fn glob | .Fn glob | ||||
or | |||||
.Fn glob_b | |||||
terminates due to an error, it sets errno and returns one of the | terminates due to an error, it sets errno and returns one of the | ||||
following non-zero constants, which are defined in the include | following non-zero constants, which are defined in the include | ||||
file | file | ||||
.In glob.h : | .In glob.h : | ||||
.Bl -tag -width GLOB_NOCHECK | .Bl -tag -width GLOB_NOCHECK | ||||
.It Dv GLOB_NOSPACE | .It Dv GLOB_NOSPACE | ||||
An attempt to allocate memory failed, or if | An attempt to allocate memory failed, or if | ||||
.Fa errno | .Fa errno | ||||
▲ Show 20 Lines • Show All 67 Lines • ▼ Show 20 Lines | |||||
conformance. | conformance. | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Fn glob | .Fn glob | ||||
and | and | ||||
.Fn globfree | .Fn globfree | ||||
functions first appeared in | functions first appeared in | ||||
.Bx 4.4 . | .Bx 4.4 . | ||||
The | |||||
.Fn glob_b | |||||
function first appeared in Mac OS X. | |||||
This implementation was created by Stacey Son for | |||||
.Fx 11.0 . | |||||
.Sh BUGS | .Sh BUGS | ||||
Patterns longer than | Patterns longer than | ||||
.Dv MAXPATHLEN | .Dv MAXPATHLEN | ||||
may cause unchecked errors. | may cause unchecked errors. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn glob | .Fn glob | ||||
argument | or | ||||
.Fn glob_b | |||||
function | |||||
may fail and set errno for any of the errors specified for the | may fail and set errno for any of the errors specified for the | ||||
library routines | library routines | ||||
.Xr stat 2 , | .Xr stat 2 , | ||||
.Xr closedir 3 , | .Xr closedir 3 , | ||||
.Xr opendir 3 , | .Xr opendir 3 , | ||||
.Xr readdir 3 , | .Xr readdir 3 , | ||||
.Xr malloc 3 , | .Xr malloc 3 , | ||||
and | and | ||||
.Xr free 3 . | .Xr free 3 . |
As above, it might be better to just state the difference and not what the other function does. It might also be better as two sentences, or at least with a comma. In other words:
.Fn glob_b
is a block-based version of
.Fn glob .
The error callback is the block pointer
.Fa errblock .
(No starting "The". Wording might need work. "block-oriented"?)