View Source: glob(3) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
GLOB
!!!GLOB
NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLES
CONFORMING TO
BUGS
NOTES
SEE ALSO
----
!!NAME


glob, globfree - find pathnames matching a pattern, free memory from glob()
!!SYNOPSIS


__#include
__''pattern''__, int__ ''flags''__,
int__ ''errfunc''__(const char *__ ''epath''__, int__ ''eerrno''__),
glob_t__ ''*pglob''__);
void globfree(glob_t *__''pglob''__);
__
!!DESCRIPTION


The __glob()__ function searches for all the pathnames
matching ''pattern'' according to the rules used by the
shell (see glob(7)). No tilde expansion or parameter
substitution is done; if you want these, use
wordexp(3).


The __globfree()__ function frees the dynamically
allocated storage from an earlier call to
__glob()__.


The results of a __glob()__ call are stored in the
structure pointed to by ''pglob'', which is a
__glob_t__ which is declared in ____ and
includes the following elements defined by POSIX.2 (more may
be present as an extension):


typedef struct
{
size_t gl_pathc;    /* Count of paths matched so far  */
char **gl_pathv;    /* List of matched pathnames.  */
size_t gl_offs;     /* Slots to reserve in `gl_pathv'.  */
} glob_t;
Results are stored in dynamically allocated storage.


The parameter ''flags'' is made up of bitwise OR of zero
or more the following symbolic constants, which modify the
of behaviour of __glob()__:


__GLOB_ERR__


which means to return upon read error (because a directory
does not have read permission, for example),


__GLOB_MARK__


which means to append a slash to each path which corresponds
to a directory,


__GLOB_NOSORT__


which means don't sort the returned pathnames (they are by
default),


__GLOB_DOOFFS__


which means that ''pglob-'' slots will be
reserved at the beginning of the list of strings in
''pglob-'',


__GLOB_NOCHECK__


which means that, if no pattern matches, to return the
original pattern,


__GLOB_APPEND__


which means to append to the results of a previous call. Do
not set this flag on the first invocation of
__glob()__.


__GLOB_NOESCAPE__


which means that meta characters cannot be quoted by
backslashes.


The flags may also include some of the following, which are
GNU extensions and not defined by POSIX.2:


__GLOB_PERIOD__


which means that a leading period can be matched by meta
characters,


__GLOB_ALTDIRFUNC__


which means that alternative functions
''pglob-'', ''pglob-'',
''pglob-'', ''pglob-'', and
''pglob-'' are used for file system access
instead of the normal library functions,


__GLOB_BRACE__


which means that csh(1) style brace expresions
__{a,b}__ are expanded,


__GLOB_NOMAGIC__


which means that the pattern is returned if it contains no
metacharacters,


__GLOB_TILDE__


which means that tilde expansion is carried out,
and


__GLOB_ONLYDIR__


which means that only directories are matched.


If ''errfunc'' is not __NULL__, it will be called in
case of an error with the arguments ''epath'', a pointer
to the path which failed, and ''eerrno'', the value of
''errno'' as returned from one of the calls to
__opendir()__, __readdir()__, or __stat()__. If
''errfunc'' returns non-zero, or if __GLOB_ERR__ is
set, __glob()__ will terminate after the call to
''errfunc''.


Upon successful return, ''pglob-'' contains
the number of matched pathnames and
''pglob-'' a pointer to the list of matched
pathnames. The first pointer after the last pathname is
__NULL__.


It is possible to call __glob()__ several times. In that
case, the __GLOB_APPEND__ flag has to be set in
''flags'' on the second and later
invocations.


As a GNU extension, ''pglob-'' is set to the
flags specified, __or__ed with __GLOB_MAGCHAR__ if any
metacharacters were found.
!!RETURN VALUE


On successful completion, __glob()__ returns zero. Other
possible returns are:


__GLOB_NOSPACE__


for running out of memory,


__GLOB_ABORTED__


for a read error, and


__GLOB_NOMATCH__


for no found matches.
!!EXAMPLES


One example of use is the following code, which simulates
typing __ls -l *.c ../*.c__ in the shell.


glob_t globbuf;
globbuf.gl_offs = 2;
glob(
!!CONFORMING TO


POSIX.2
!!BUGS


The __glob()__ function may fail due to failure of
underlying function calls, such as __malloc()__ or
__opendir()__. These will store their error code in
''errno''.
!!NOTES


The structure elements ''gl_pathc'' and ''gl_offs''
are declared as __size_t__ in glibc 2.1, as they should
according to POSIX.2, but are declared as __int__ in
libc4, libc5 and glibc 2.0.
!!SEE ALSO


ls(1), sh(1), stat(2), exec(3),
malloc(3), opendir(3), readdir(3),
wordexp(3)
----
5 pages link to glob(3):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:24:23 am by "perry"
Edit PageHistory Diff Info LikePages