glob(3C) glob(3C)
NAME
glob, globfree - generate pathnames matching a pattern
SYNOPSIS
#include <glob.h>
int glob(const char *pattern, int flags, int (*errfunc)
(const char *epath, int eerrno), globt *pglob);
void globfree(globt *pglob);
DESCRIPTION
The glob() function is a pathname generator that implements the rules
of the pattern matching notation, with optional support for patterns
used for filename expansion.
The structure type globt is defined in the header glob.h and includes
at least the following members:
______________________________________________________________________
|Member type|Member name| Description |
|___________|___________|_____________________________________________|
|sizet |glpathc | Count of paths matched by pattern |
|___________|___________|_____________________________________________|
|char ** |glpathv | Pointer to a list of matched pathnames |
|___________|___________|_____________________________________________|
|sizet |gloffs | Slots to reserve at the beginning of glpathv
|___________|___________|_____________________________________________|
The argument pattern is a pointer to a pathname pattern to be
expanded. The glob() function matches all accessible pathnames against
this pattern and develops a list of all pathnames that match. In order
to have access to a pathname, 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: *, ?, [.
The glob() function stores the number of matched pathnames into
pglob->glpathc and a pointer to a list of pointers to pathnames into
pglob->glpathv. The pathnames are in sort order as defined by the
current setting of the LCCOLLATE category. The first pointer after
the last pathname is a null pointer. If the pattern does not match any
pathnames, the returned number of matched paths is set to zero, and
the contents of pglob->glpathv are implementation-dependent.
It is the callers 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().
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 fol-
lowing constants, which are defined in the header glob.h:
Page 1 Reliant UNIX 5.44 Printed 11/98
glob(3C) glob(3C)
GLOBAPPEND
Append pathnames generated to the ones from a previous call to
glob().
GLOBDOOFFS
Make use of pglob->gloffs. If this flag is set, pglob->gloffs
is used to specify how many null pointers to add to the beginning
of pglob->glpathv. In other words, pglob->glpathv will point to
pglob->gloffs null pointers, followed by pglob->glpathc path-
name pointers, followed by a null pointer.
GLOBERR
Causes glob() to return when it encounters a directory that it
cannot open or read. Ordinarily, glob() continues to find
matches.
GLOBMARK
Each pathname that is a directory that matches pattern has a
slash appended.
GLOBNOCHECK
Support patterns used for filename expansion. If pattern does not
match any pathname, then glob() returns a list consisting of only
pattern, and the number of matched pathnames is 1.
GLOBNOESCAPE
Disable backslash escaping.
GLOBNOSORT
Ordinarily, glob() sorts the matching pathnames according to the
current setting of the LCCOLLATE category. When this flag is
used the order of pathnames returned is unspecified.
The GLOBAPPEND flag can be used to append a new set of pathnames to
those found in a previous call to glob(). The following 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 GLOBAPPEND. All subsequent calls
must set it.
2. All the calls must set GLOBDOOFFS, or all must not set it.
3. After the second call, pglob->glpathv points to a list containing
the following:
- Zero or more null pointers, as specified by GLOBDOOFFS and
pglob->gloffs.
- Pointers to the pathnames that were in the pglob->glpathv list
before the call, in the same order as before.
Page 2 Reliant UNIX 5.44 Printed 11/98
glob(3C) glob(3C)
- Pointers to the new pathnames generated by the second call, in
the specified order.
4. The count returned in pglob->glpathc will be the total number of
pathnames 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 GLOBAPPEND flag.
If, during the search, a directory is encountered that cannot be
opened or read and errfunc is not a null pointer, glob() calls
(*errfunc()) with two arguments:
- The epath argument is a pointer to the path that failed.
- The eerrno argument is the value from the failure, as set by the
opendir(), readdir() or stat() functions. (Other values may be used
to report other errors not explicitly documented for those func-
tions).
The following constants are defined as error values for glob():
GLOBABORTED
The scan was stopped because GLOBERR was set or (*errfunc())
returned non-zero.
GLOBBADPAT
An invalid pattern was specified.
GLOBNOMATCH
The pattern does not match any existing pathname, and
GLOBNOCHECK was not set in flags.
GLOBNOSPACE
An attempt to allocate memory failed.
If (*errfunc()) is called and returns non-zero, or if the GLOBERR
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 GLOBERR is not set and either errfunc is a null
pointer or (*errfunc()) returns zero, the error is ignored.
This function is not provided for the purpose of enabling utilities to
perform pathname 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
pathname expansion on strings obtained from other sources, such as
pattern typed by a user or read from a file.
Page 3 Reliant UNIX 5.44 Printed 11/98
glob(3C) glob(3C)
If a utility needs to see if a pathname matches a given pattern, it
can use fnmatch().
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 zero, glpathv is unspecified even if glob()
did not return an error.
The GLOBNOCHECK option could be used when an application wants to
expand a pathname if wildcards are specified, but wants to treat the
pattern as just a string otherwise. The sh utility might use this for
option-arguments, for example.
The new pathnames generated by a subsequent call with GLOBAPPEND are
not sorted together with the previous pathnames. This mirrors the way
that the shell handles pathname expansion when multiple expansions are
done on a command line.
Applications that need tilde and parameter expansion should use the
wordexp() function.
RESULT
On successful completion, glob() returns zero. The argument
pglob->glpathc returns the number of matched pathnames and the argu-
ment pglob->glpathv contains a pointer to a null-terminated list of
matched and sorted pathnames. However, if pglob->glpathc is zero, the
content of pglob->glpathv is undefined.
The globfree() function returns no value.
If glob() terminates due to an error, it returns one of the non-zero
constants defined in glob.h. The arguments pglob->glpathc and
pglob->glpathv are still set as defined.
Page 4 Reliant UNIX 5.44 Printed 11/98
glob(3C) glob(3C)
EXAMPLES
One use of the GLOBDOOFFS flag is by application that built an argu-
ment list for use with the execv(), execve() or execvp() functions.
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 approximately the same
result using the sequence:
globbuf.gloffs = 2;
glob ("*.c", GLOBDOOFFS, NULL, &globbuf);
globbuf.glpathv [0] = "ls";
globbuf.glpathvv[1] = "-l";
execvp ("ls", &globbuf.glpathv[0]);
Using the same example:
ls -l *.c *.h
could be approximately simulated using GLOBAPPEND as follows:
globbuf.gloffs = 2;
glob ("*.c", GLOBDOOFFS, NULL, &globbuf);
glob ("*.c", GLOBDOOFFS|GLOBAPPEND, NULL, &globbuf);
SEE ALSO
execv(2), stat(2), fnmatch(3C), opendir(3C), readdir(3C), wordexp(3C),
glob(5).
Page 5 Reliant UNIX 5.44 Printed 11/98