Standard C Library Functions glob(3C)
NAME
glob, globfree - generate path names matching a pattern
SYNOPSIS
#include
int glob(const char *restrict pattern, int flags,
int(*errfunc)(const char *epath, int eerrno),
globt *restrict pglob);
void globfree(globt *pglob);
DESCRIPTION
The glob() function is a path name generator.
The globfree() function frees any memory allocated by glob()
associated with pglob.
pattern Argument
The argument pattern is a pointer to a path name pattern to
be expanded. The glob() function matches all accessible path
names against this pattern and develops a list of all path
names that match. In order to have access to a path name,
glob() requires search permission on every component of a
path except the last, and read permission on each directory
of any filename component of pattern that contains any of
the following special characters:
* ? [
pglob Argument
The structure type globt is defined in the header
and includes at least the following members:
sizet glpathc; /* count of paths matched by */
/* pattern */
char **glpathv; /* pointer to list of matched */
/* path names */
sizet gloffs; /* slots to reserve at beginning */
/* of glpathv */
The glob() function stores the number of matched path names
into pglob->glpathc and a pointer to a list of pointers to
path names into pglob->glpathv. The path names are in sort
order as defined by the current setting of the LCOLATE
category. The first pointer after the last path name is a
SunOS 5.11 Last change: 1 Nov 2003 1
Standard C Library Functions glob(3C)
NUL pointer. If the pattern does not match any path names,
the returned number of matched paths is set to 0, and the
contents of pglob->glpathv are implementation-dependent.
It is the caller's responsibility to create the structure
pointed to by pglob. The glob() function allocates other
space as needed, including the memory pointed to by
glpathv. The globfree() function frees any space associated
with pglob from a previous call to glob().
flags Argument
The flags argument is used to control the behavior of
glob(). The value of flags is a bitwise inclusive OR of zero
or more of the following constants, which are defined in the
header :
GLOBAPEND Append path names generated to the ones
from a previous call to glob().
GLOBDOFS Make use of pglob->gloffs. If this flag is
set, pglob->gloffs is used to specify how
many NUL pointers to add to the beginning
of pglob->glpathv. In other words,
pglob->glpathv will point to
pglob->gloffs NUL pointers, followed by
pglob->glpathc path name pointers, fol-
lowed by a NUL pointer.
GLOBER Causes glob() to return when it encounters
a directory that it cannot open or read.
Ordinarily, glob() continues to find
matches.
GLOBMARK Each path name that is a directory that
matches pattern has a slash appended.
GLOBNOCHECK If pattern does not match any path name,
then glob() returns a list consisting of
only pattern, and the number of matched
path names is 1.
GLOBNOESCAPE Disable backslash escaping.
GLOBNOSORT Ordinarily, glob() sorts the matching path
names according to the current setting of
SunOS 5.11 Last change: 1 Nov 2003 2
Standard C Library Functions glob(3C)
the LCOLATE category. When this flag is
used the order of path names returned is
unspecified.
The GLOBAPEND flag can be used to append a new set of path
names to those found in a previous call to glob(). The fol-
lowing rules apply when two or more calls to glob() are made
with the same value of pglob and without intervening calls
to globfree():
1. The first such call must not set GLOBAPEND. All
subsequent calls must set it.
2. All the calls must set GLOBDOFS, or all must not
set it.
3. After the second call, pglob->glpathv points to a
list containing the following:
a. Zero or more NUL pointers, as specified by
GLOBDOFS and pglob->gloffs.
b. Pointers to the path names that were in the
pglob->glpathv list before the call, in the
same order as before.
c. Pointers to the new path names generated by the
second call, in the specified order.
4. The count returned in pglob->glpathc will be the
total number of path names from the two calls.
5. The application can change any of the fields after
a call to glob(). If it does, it must reset them to
the original value before a subsequent call, using
the same pglob value, to globfree() or glob() with
the GLOBAPEND flag.
errfunc and epath Arguments
If, during the search, a directory is encountered that can-
not be opened or read and errfunc is not a NUL pointer,
glob() calls (*errfunc) with two arguments:
1. The epath argument is a pointer to the path that
failed.
2. The eerrno argument is the value of errno from the
failure, as set by the opendir(3C), readdir(3C) or
stat(2) functions. (Other values may be used to
report other errors not explicitly documented for
SunOS 5.11 Last change: 1 Nov 2003 3
Standard C Library Functions glob(3C)
those functions.)
The following constants are defined as error return values
for glob():
GLOBABORTED The scan was stopped because GLOBER was
set or (*errfunc) returned non-zero.
GLOBNOMATCH The pattern does not match any existing path
name, and GLOBNOCHECK was not set in flags.
GLOGNOSPACE An attempt to allocate memory failed.
If (*errfunc) is called and returns non-zero, or if the
GLOBER flag is set in flags, glob() stops the scan and
returns GLOBABORTED after setting glpathc and glpathv in
pglob to reflect the paths already scanned. If GLOBER is
not set and either errfunc is a NUL pointer or (*errfunc)
returns 0, the error is ignored.
RETURN VALUES
The following values are returned by glob():
0 Successful completion. The argument
pglob->glpathc returns the number of matched
path names and the argument pglob->glpathv con-
tains a pointer to a null-terminated list of
matched and sorted path names. However, if
pglob->glpathc is 0, the content of
pglob->glpathv is undefined.
non-zero An error has occurred. Non-zero constants are
defined in . The arguments
pglob->glpathc and pglob->glpathv are still
set as defined above.
The globfree() function returns no value.
USAGE
This function is not provided for the purpose of enabling
utilities to perform path name expansion on their arguments,
as this operation is performed by the shell, and utilities
are explicitly not expected to redo this. Instead, it is
provided for applications that need to do path name
SunOS 5.11 Last change: 1 Nov 2003 4
Standard C Library Functions glob(3C)
expansion on strings obtained from other sources, such as a
pattern typed by a user or read from a file.
If a utility needs to see if a path name matches a given
pattern, it can use fnmatch(3C).
Note that glpathc and glpathv have meaning even if glob()
fails. This allows glob() to report partial results in the
event of an error. However, if glpathc is 0, glpathv is
unspecified even if glob() did not return an error.
The GLOBNOCHECK option could be used when an application
wants to expand a path name if wildcards are specified, but
wants to treat the pattern as just a string otherwise.
The new path names generated by a subsequent call with
GLOBAPEND are not sorted together with the previous path
names. This mirrors the way that the shell handles path name
expansion when multiple expansions are done on a command
line.
Applications that need tilde and parameter expansion should
use the wordexp(3C) function.
EXAMPLES
Example 1 Example of globdoofs function.
One use of the GLOBDOFS flag is by applications that
build an argument list for use with the execv(), execve(),
or execvp() functions (see exec(2)). Suppose, for example,
that an application wants to do the equivalent of:
ls -l *.c
but for some reason:
system("ls -l *.c")
is not acceptable. The application could obtain approxi-
mately the same result using the sequence:
SunOS 5.11 Last change: 1 Nov 2003 5
Standard C Library Functions glob(3C)
globbuf.gloffs = 2;
glob ("*.c", GLOBDOFS, NUL, &globbuf);
globbuf.glpathv[0] = "ls";
globbuf.glpathv[1] = "-l";
execvp ("ls", &globbuf.glpathv[0]);
Using the same example:
ls -l *.c *.h
could be approximately simulated using GLOBAPEND as fol-
lows:
globbuf.gloffs = 2;
glob ("*.c", GLOBDOFS, NUL, &globbuf);
glob ("*.h", GLOBDOFSGLOBAPEND, NUL, &globbuf);
...
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
execv(2), stat(2), fnmatch(3C), opendir(3C), readdir(3C),
wordexp(3C), attributes(5), standards(5)
SunOS 5.11 Last change: 1 Nov 2003 6
|
