@node Pattern Matching, I/O Overview, Searching and Sorting, Top

@c %MENU% Matching shell ``globs'' and regular expressions

@chapter Pattern Matching

@Theglibc{} provides pattern matching facilities for two kinds of

patterns: regular expressions and file-name wildcards.  The library also

provides a facility for expanding variable and command references and

parsing text into words in the way the shell does.

@menu

* Wildcard Matching::    Matching a wildcard pattern against a single string.

* Globbing::             Finding the files that match a wildcard pattern.

* Regular Expressions::  Matching regular expressions against strings.

* Word Expansion::       Expanding shell variables, nested commands,

			    arithmetic, and wildcards.

			    This is what the shell does with shell commands.

@end menu

@node Wildcard Matching

@section Wildcard Matching

@pindex fnmatch.h

This section describes how to match a wildcard pattern against a

particular string.  The result is a yes or no answer: does the

string fit the pattern or not.  The symbols described here are all

declared in @file{fnmatch.h}.

@deftypefun int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})

@standards{POSIX.2, fnmatch.h}

@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}

@c fnmatch @mtsenv @mtslocale @ascuheap @acsmem

@c  strnlen dup ok

@c  mbsrtowcs

@c  memset dup ok

@c  malloc dup @ascuheap @acsmem

@c  mbsinit dup ok

@c  free dup @ascuheap @acsmem

@c  FCT = internal_fnwmatch @mtsenv @mtslocale @ascuheap @acsmem

@c   FOLD @mtslocale

@c    towlower @mtslocale

@c   EXT @mtsenv @mtslocale @ascuheap @acsmem

@c    STRLEN = wcslen dup ok

@c    getenv @mtsenv

@c    malloc dup @ascuheap @acsmem

@c    MEMPCPY = wmempcpy dup ok

@c    FCT dup @mtsenv @mtslocale @ascuheap @acsmem

@c    STRCAT = wcscat dup ok

@c    free dup @ascuheap @acsmem

@c   END @mtsenv

@c    getenv @mtsenv

@c   MEMCHR = wmemchr dup ok

@c   getenv @mtsenv

@c   IS_CHAR_CLASS = is_char_class @mtslocale

@c    wctype @mtslocale

@c   BTOWC ok

@c   ISWCTYPE ok

@c   auto findidx dup ok

@c   elem_hash dup ok

@c   memcmp dup ok

@c   collseq_table_lookup dup ok

@c   NO_LEADING_PERIOD ok

This function tests whether the string @var{string} matches the pattern

@var{pattern}.  It returns @code{0} if they do match; otherwise, it

returns the nonzero value @code{FNM_NOMATCH}.  The arguments

@var{pattern} and @var{string} are both strings.

The argument @var{flags} is a combination of flag bits that alter the

details of matching.  See below for a list of the defined flags.

In @theglibc{}, @code{fnmatch} might sometimes report ``errors'' by

returning nonzero values that are not equal to @code{FNM_NOMATCH}.

@end deftypefun

These are the available flags for the @var{flags} argument:

@vtable @code

@item FNM_FILE_NAME

@standards{GNU, fnmatch.h}

Treat the @samp{/} character specially, for matching file names.  If

this flag is set, wildcard constructs in @var{pattern} cannot match

@samp{/} in @var{string}.  Thus, the only way to match @samp{/} is with

an explicit @samp{/} in @var{pattern}.

@item FNM_PATHNAME

@standards{POSIX.2, fnmatch.h}

This is an alias for @code{FNM_FILE_NAME}; it comes from POSIX.2.  We

don't recommend this name because we don't use the term ``pathname'' for

file names.

@item FNM_PERIOD

@standards{POSIX.2, fnmatch.h}

Treat the @samp{.} character specially if it appears at the beginning of

@var{string}.  If this flag is set, wildcard constructs in @var{pattern}

cannot match @samp{.} as the first character of @var{string}.

If you set both @code{FNM_PERIOD} and @code{FNM_FILE_NAME}, then the

special treatment applies to @samp{.} following @samp{/} as well as to

@samp{.} at the beginning of @var{string}.  (The shell uses the

@code{FNM_PERIOD} and @code{FNM_FILE_NAME} flags together for matching

file names.)

@item FNM_NOESCAPE

@standards{POSIX.2, fnmatch.h}

Don't treat the @samp{\} character specially in patterns.  Normally,

@samp{\} quotes the following character, turning off its special meaning

(if any) so that it matches only itself.  When quoting is enabled, the

pattern @samp{\?} matches only the string @samp{?}, because the question

mark in the pattern acts like an ordinary character.

If you use @code{FNM_NOESCAPE}, then @samp{\} is an ordinary character.

@item FNM_LEADING_DIR

@standards{GNU, fnmatch.h}

Ignore a trailing sequence of characters starting with a @samp{/} in

@var{string}; that is to say, test whether @var{string} starts with a

directory name that @var{pattern} matches.

If this flag is set, either @samp{foo*} or @samp{foobar} as a pattern

would match the string @samp{foobar/frobozz}.

@item FNM_CASEFOLD

@standards{GNU, fnmatch.h}

Ignore case in comparing @var{string} to @var{pattern}.

@item FNM_EXTMATCH

@standards{GNU, fnmatch.h}

@cindex Korn Shell

@pindex ksh

Besides the normal patterns, also recognize the extended patterns

introduced in @file{ksh}.  The patterns are written in the form

explained in the following table where @var{pattern-list} is a @code{|}

separated list of patterns.

@table @code

@item ?(@var{pattern-list})

The pattern matches if zero or one occurrences of any of the patterns

in the @var{pattern-list} allow matching the input string.

@item *(@var{pattern-list})

The pattern matches if zero or more occurrences of any of the patterns

in the @var{pattern-list} allow matching the input string.

@item +(@var{pattern-list})

The pattern matches if one or more occurrences of any of the patterns

in the @var{pattern-list} allow matching the input string.

@item @@(@var{pattern-list})

The pattern matches if exactly one occurrence of any of the patterns in

the @var{pattern-list} allows matching the input string.

@item !(@var{pattern-list})

The pattern matches if the input string cannot be matched with any of

the patterns in the @var{pattern-list}.

@end table

@end vtable

@node Globbing

@section Globbing

@cindex globbing

The archetypal use of wildcards is for matching against the files in a

directory, and making a list of all the matches.  This is called

@dfn{globbing}.

You could do this using @code{fnmatch}, by reading the directory entries

one by one and testing each one with @code{fnmatch}.  But that would be

slow (and complex, since you would have to handle subdirectories by

hand).

The library provides a function @code{glob} to make this particular use

of wildcards convenient.  @code{glob} and the other symbols in this

section are declared in @file{glob.h}.

@menu

* Calling Glob::             Basic use of @code{glob}.

* Flags for Globbing::       Flags that enable various options in @code{glob}.

* More Flags for Globbing::  GNU specific extensions to @code{glob}.

@end menu

@node Calling Glob

@subsection Calling @code{glob}

The result of globbing is a vector of file names (strings).  To return

this vector, @code{glob} uses a special data type, @code{glob_t}, which

is a structure.  You pass @code{glob} the address of the structure, and

it fills in the structure's fields to tell you about the results.

@deftp {Data Type} glob_t

@standards{POSIX.2, glob.h}

This data type holds a pointer to a word vector.  More precisely, it

records both the address of the word vector and its size.  The GNU

implementation contains some more fields which are non-standard

extensions.

@table @code

@item gl_pathc

The number of elements in the vector, excluding the initial null entries

if the GLOB_DOOFFS flag is used (see gl_offs below).

@item gl_pathv

The address of the vector.  This field has type @w{@code{char **}}.

@item gl_offs

The offset of the first real element of the vector, from its nominal

address in the @code{gl_pathv} field.  Unlike the other fields, this

is always an input to @code{glob}, rather than an output from it.

If you use a nonzero offset, then that many elements at the beginning of

the vector are left empty.  (The @code{glob} function fills them with

null pointers.)

The @code{gl_offs} field is meaningful only if you use the

@code{GLOB_DOOFFS} flag.  Otherwise, the offset is always zero

regardless of what is in this field, and the first real element comes at

the beginning of the vector.

@item gl_closedir

The address of an alternative implementation of the @code{closedir}

function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in

the flag parameter.  The type of this field is

@w{@code{void (*) (void *)}}.

This is a GNU extension.

@item gl_readdir

The address of an alternative implementation of the @code{readdir}

function used to read the contents of a directory.  It is used if the

@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of

this field is @w{@code{struct dirent *(*) (void *)}}.

An implementation of @code{gl_readdir} needs to initialize the following

members of the @code{struct dirent} object:

@table @code

@item d_type

This member should be set to the file type of the entry if it is known.

Otherwise, the value @code{DT_UNKNOWN} can be used.  The @code{glob}

function may use the specified file type to avoid callbacks in cases

where the file type indicates that the data is not required.

@item d_ino

This member needs to be non-zero, otherwise @code{glob} may skip the

current entry and call the @code{gl_readdir} callback function again to

retrieve another entry.

@item d_name

This member must be set to the name of the entry.  It must be

null-terminated.

@end table

The example below shows how to allocate a @code{struct dirent} object

containing a given name.

@smallexample

@include mkdirent.c.texi

@end smallexample

The @code{glob} function reads the @code{struct dirent} members listed

above and makes a copy of the file name in the @code{d_name} member

immediately after the @code{gl_readdir} callback function returns.

Future invocations of any of the callback functions may dealloacte or

reuse the buffer.  It is the responsibility of the caller of the

@code{glob} function to allocate and deallocate the buffer, around the

call to @code{glob} or using the callback functions.  For example, an

application could allocate the buffer in the @code{gl_readdir} callback

function, and deallocate it in the @code{gl_closedir} callback function.

The @code{gl_readdir} member is a GNU extension.

@item gl_opendir

The address of an alternative implementation of the @code{opendir}

function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in

the flag parameter.  The type of this field is

@w{@code{void *(*) (const char *)}}.

This is a GNU extension.

@item gl_stat

The address of an alternative implementation of the @code{stat} function

to get information about an object in the filesystem.  It is used if the

@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of

this field is @w{@code{int (*) (const char *, struct stat *)}}.

This is a GNU extension.

@item gl_lstat

The address of an alternative implementation of the @code{lstat}

function to get information about an object in the filesystems, not

following symbolic links.  It is used if the @code{GLOB_ALTDIRFUNC} bit

is set in the flag parameter.  The type of this field is @code{@w{int

(*) (const char *,} @w{struct stat *)}}.

This is a GNU extension.

@item gl_flags

The flags used when @code{glob} was called.  In addition, @code{GLOB_MAGCHAR}

might be set.  See @ref{Flags for Globbing} for more details.

This is a GNU extension.

@end table

@end deftp

For use in the @code{glob64} function @file{glob.h} contains another

definition for a very similar type.  @code{glob64_t} differs from

@code{glob_t} only in the types of the members @code{gl_readdir},

@code{gl_stat}, and @code{gl_lstat}.

@deftp {Data Type} glob64_t

@standards{GNU, glob.h}

This data type holds a pointer to a word vector.  More precisely, it

records both the address of the word vector and its size.  The GNU

implementation contains some more fields which are non-standard

extensions.

@table @code

@item gl_pathc

The number of elements in the vector, excluding the initial null entries

if the GLOB_DOOFFS flag is used (see gl_offs below).

@item gl_pathv

The address of the vector.  This field has type @w{@code{char **}}.

@item gl_offs

The offset of the first real element of the vector, from its nominal

address in the @code{gl_pathv} field.  Unlike the other fields, this

is always an input to @code{glob}, rather than an output from it.

If you use a nonzero offset, then that many elements at the beginning of

the vector are left empty.  (The @code{glob} function fills them with

null pointers.)

The @code{gl_offs} field is meaningful only if you use the

@code{GLOB_DOOFFS} flag.  Otherwise, the offset is always zero

regardless of what is in this field, and the first real element comes at

the beginning of the vector.

@item gl_closedir

The address of an alternative implementation of the @code{closedir}

function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in

the flag parameter.  The type of this field is

@w{@code{void (*) (void *)}}.

This is a GNU extension.

@item gl_readdir

The address of an alternative implementation of the @code{readdir64}

function used to read the contents of a directory.  It is used if the

@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of

this field is @w{@code{struct dirent64 *(*) (void *)}}.

This is a GNU extension.

@item gl_opendir

The address of an alternative implementation of the @code{opendir}

function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in

the flag parameter.  The type of this field is

@w{@code{void *(*) (const char *)}}.

This is a GNU extension.

@item gl_stat

The address of an alternative implementation of the @code{stat64} function

to get information about an object in the filesystem.  It is used if the

@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of

this field is @w{@code{int (*) (const char *, struct stat64 *)}}.

This is a GNU extension.

@item gl_lstat

The address of an alternative implementation of the @code{lstat64}

function to get information about an object in the filesystems, not

following symbolic links.  It is used if the @code{GLOB_ALTDIRFUNC} bit

is set in the flag parameter.  The type of this field is @code{@w{int

(*) (const char *,} @w{struct stat64 *)}}.

This is a GNU extension.

@item gl_flags

The flags used when @code{glob} was called.  In addition, @code{GLOB_MAGCHAR}

might be set.  See @ref{Flags for Globbing} for more details.

This is a GNU extension.

@end table

@end deftp

@deftypefun int glob (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob_t *@var{vector-ptr})

@standards{POSIX.2, glob.h}

@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}

@c glob @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem

@c  strlen dup ok

@c  strchr dup ok

@c  malloc dup @ascuheap @acsmem

@c  mempcpy dup ok

@c  next_brace_sub ok

@c  free dup @ascuheap @acsmem

@c  globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem

@c  glob_pattern_p ok

@c   glob_pattern_type dup ok

@c  getenv dup @mtsenv

@c  GET_LOGIN_NAME_MAX ok

@c  getlogin_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem

@c  GETPW_R_SIZE_MAX ok

@c  getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem

@c  realloc dup @ascuheap @acsmem

@c  memcpy dup ok

@c  memchr dup ok

@c  *pglob->gl_stat user-supplied

@c  stat64 dup ok

@c  S_ISDIR dup ok

@c  strdup dup @ascuheap @acsmem

@c  glob_pattern_type ok

@c  glob_in_dir @mtsenv @mtslocale @asucorrupt @ascuheap @acucorrupt @acsfd @acsmem

@c   strlen dup ok

@c   glob_pattern_type dup ok

@c   malloc dup @ascuheap @acsmem

@c   mempcpy dup ok

@c   *pglob->gl_stat user-supplied

@c   stat64 dup ok

@c   free dup @ascuheap @acsmem

@c   *pglob->gl_opendir user-supplied

@c   opendir dup @ascuheap @acsmem @acsfd

@c   dirfd dup ok

@c   *pglob->gl_readdir user-supplied

@c   CONVERT_DIRENT_DIRENT64 ok

@c   readdir64 ok [protected by exclusive use of the stream]

@c   REAL_DIR_ENTRY ok

@c   DIRENT_MIGHT_BE_DIR ok

@c   fnmatch dup @mtsenv @mtslocale @ascuheap @acsmem

@c   DIRENT_MIGHT_BE_SYMLINK ok

@c   link_exists_p ok

@c    link_exists2_p ok

@c     strlen dup ok

@c     mempcpy dup ok

@c     *pglob->gl_stat user-supplied

@c    fxstatat64 dup ok

@c   realloc dup @ascuheap @acsmem

@c   pglob->gl_closedir user-supplied

@c   closedir @ascuheap @acsmem @acsfd

@c  prefix_array dup @asucorrupt @ascuheap @acucorrupt @acsmem

@c   strlen dup ok

@c   malloc dup @ascuheap @acsmem

@c   free dup @ascuheap @acsmem

@c   mempcpy dup ok

@c  strcpy dup ok

The function @code{glob} does globbing using the pattern @var{pattern}

in the current directory.  It puts the result in a newly allocated

vector, and stores the size and address of this vector into

@code{*@var{vector-ptr}}.  The argument @var{flags} is a combination of

bit flags; see @ref{Flags for Globbing}, for details of the flags.

The result of globbing is a sequence of file names.  The function

@code{glob} allocates a string for each resulting word, then

allocates a vector of type @code{char **} to store the addresses of

these strings.  The last element of the vector is a null pointer.

This vector is called the @dfn{word vector}.

To return this vector, @code{glob} stores both its address and its

length (number of elements, not counting the terminating null pointer)

into @code{*@var{vector-ptr}}.

Normally, @code{glob} sorts the file names alphabetically before

returning them.  You can turn this off with the flag @code{GLOB_NOSORT}

if you want to get the information as fast as possible.  Usually it's

a good idea to let @code{glob} sort them---if you process the files in

alphabetical order, the users will have a feel for the rate of progress

that your application is making.

If @code{glob} succeeds, it returns 0.  Otherwise, it returns one

of these error codes:

@vtable @code

@item GLOB_ABORTED

@standards{POSIX.2, glob.h}

There was an error opening a directory, and you used the flag

@code{GLOB_ERR} or your specified @var{errfunc} returned a nonzero

value.

@iftex

See below

@end iftex

@ifinfo

@xref{Flags for Globbing},

@end ifinfo

for an explanation of the @code{GLOB_ERR} flag and @var{errfunc}.

@item GLOB_NOMATCH

@standards{POSIX.2, glob.h}

The pattern didn't match any existing files.  If you use the

@code{GLOB_NOCHECK} flag, then you never get this error code, because

that flag tells @code{glob} to @emph{pretend} that the pattern matched

at least one file.

@item GLOB_NOSPACE

@standards{POSIX.2, glob.h}

It was impossible to allocate memory to hold the result.

@end vtable

In the event of an error, @code{glob} stores information in

@code{*@var{vector-ptr}} about all the matches it has found so far.

It is important to notice that the @code{glob} function will not fail if

it encounters directories or files which cannot be handled without the

LFS interfaces.  The implementation of @code{glob} is supposed to use

these functions internally.  This at least is the assumption made by

the Unix standard.  The GNU extension of allowing the user to provide their

own directory handling and @code{stat} functions complicates things a

bit.  If these callback functions are used and a large file or directory

is encountered @code{glob} @emph{can} fail.

@end deftypefun

@deftypefun int glob64 (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob64_t *@var{vector-ptr})

@standards{GNU, glob.h}

@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}

@c Same code as glob, but with glob64_t #defined as glob_t.

The @code{glob64} function was added as part of the Large File Summit

extensions but is not part of the original LFS proposal.  The reason for

this is simple: it is not necessary.  The necessity for a @code{glob64}

function is added by the extensions of the GNU @code{glob}

implementation which allows the user to provide their own directory handling

and @code{stat} functions.  The @code{readdir} and @code{stat} functions

do depend on the choice of @code{_FILE_OFFSET_BITS} since the definition

of the types @code{struct dirent} and @code{struct stat} will change

depending on the choice.

Besides this difference, @code{glob64} works just like @code{glob} in

all aspects.

This function is a GNU extension.

@end deftypefun

@node Flags for Globbing

@subsection Flags for Globbing

This section describes the standard flags that you can specify in the

@var{flags} argument to @code{glob}.  Choose the flags you want,

and combine them with the C bitwise OR operator @code{|}.

Note that there are @ref{More Flags for Globbing} available as GNU extensions.

@vtable @code

@item GLOB_APPEND

@standards{POSIX.2, glob.h}

Append the words from this expansion to the vector of words produced by

previous calls to @code{glob}.  This way you can effectively expand

several words as if they were concatenated with spaces between them.

In order for appending to work, you must not modify the contents of the

word vector structure between calls to @code{glob}.  And, if you set

@code{GLOB_DOOFFS} in the first call to @code{glob}, you must also

set it when you append to the results.

Note that the pointer stored in @code{gl_pathv} may no longer be valid

after you call @code{glob} the second time, because @code{glob} might

have relocated the vector.  So always fetch @code{gl_pathv} from the

@code{glob_t} structure after each @code{glob} call; @strong{never} save

the pointer across calls.

@item GLOB_DOOFFS

@standards{POSIX.2, glob.h}

Leave blank slots at the beginning of the vector of words.

The @code{gl_offs} field says how many slots to leave.

The blank slots contain null pointers.

@item GLOB_ERR

@standards{POSIX.2, glob.h}

Give up right away and report an error if there is any difficulty

reading the directories that must be read in order to expand @var{pattern}

fully.  Such difficulties might include a directory in which you don't

have the requisite access.  Normally, @code{glob} tries its best to keep

on going despite any errors, reading whatever directories it can.

You can exercise even more control than this by specifying an

error-handler function @var{errfunc} when you call @code{glob}.  If

@var{errfunc} is not a null pointer, then @code{glob} doesn't give up

right away when it can't read a directory; instead, it calls

@var{errfunc} with two arguments, like this:

@smallexample

(*@var{errfunc}) (@var{filename}, @var{error-code})

@end smallexample

@noindent

The argument @var{filename} is the name of the directory that

@code{glob} couldn't open or couldn't read, and @var{error-code} is the

@code{errno} value that was reported to @code{glob}.

If the error handler function returns nonzero, then @code{glob} gives up

right away.  Otherwise, it continues.

@item GLOB_MARK

@standards{POSIX.2, glob.h}

If the pattern matches the name of a directory, append @samp{/} to the

directory's name when returning it.

@item GLOB_NOCHECK

@standards{POSIX.2, glob.h}

If the pattern doesn't match any file names, return the pattern itself

as if it were a file name that had been matched.  (Normally, when the

pattern doesn't match anything, @code{glob} returns that there were no

matches.)

@item GLOB_NOESCAPE

@standards{POSIX.2, glob.h}

Don't treat the @samp{\} character specially in patterns.  Normally,

@samp{\} quotes the following character, turning off its special meaning

(if any) so that it matches only itself.  When quoting is enabled, the

pattern @samp{\?} matches only the string @samp{?}, because the question

mark in the pattern acts like an ordinary character.

If you use @code{GLOB_NOESCAPE}, then @samp{\} is an ordinary character.

@code{glob} does its work by calling the function @code{fnmatch}

repeatedly.  It handles the flag @code{GLOB_NOESCAPE} by turning on the

@code{FNM_NOESCAPE} flag in calls to @code{fnmatch}.

@item GLOB_NOSORT

@standards{POSIX.2, glob.h}

Don't sort the file names; return them in no particular order.

(In practice, the order will depend on the order of the entries in

the directory.)  The only reason @emph{not} to sort is to save time.

@end vtable

@node More Flags for Globbing

@subsection More Flags for Globbing

Beside the flags described in the last section, the GNU implementation of

@code{glob} allows a few more flags which are also defined in the

@file{glob.h} file.  Some of the extensions implement functionality

which is available in modern shell implementations.

@vtable @code

@item GLOB_PERIOD

@standards{GNU, glob.h}

The @code{.} character (period) is treated special.  It cannot be

matched by wildcards.  @xref{Wildcard Matching}, @code{FNM_PERIOD}.

@item GLOB_MAGCHAR

@standards{GNU, glob.h}

The @code{GLOB_MAGCHAR} value is not to be given to @code{glob} in the

@var{flags} parameter.  Instead, @code{glob} sets this bit in the

@var{gl_flags} element of the @var{glob_t} structure provided as the

result if the pattern used for matching contains any wildcard character.

@item GLOB_ALTDIRFUNC

@standards{GNU, glob.h}

Instead of using the normal functions for accessing the

filesystem the @code{glob} implementation uses the user-supplied

functions specified in the structure pointed to by @var{pglob}

parameter.  For more information about the functions refer to the

sections about directory handling see @ref{Accessing Directories}, and

@ref{Reading Attributes}.

@item GLOB_BRACE

@standards{GNU, glob.h}

If this flag is given, the handling of braces in the pattern is changed.

It is now required that braces appear correctly grouped.  I.e., for each

opening brace there must be a closing one.  Braces can be used

recursively.  So it is possible to define one brace expression in

another one.  It is important to note that the range of each brace

expression is completely contained in the outer brace expression (if

there is one).

The string between the matching braces is separated into single

expressions by splitting at @code{,} (comma) characters.  The commas

themselves are discarded.  Please note what we said above about recursive

brace expressions.  The commas used to separate the subexpressions must

be at the same level.  Commas in brace subexpressions are not matched.

They are used during expansion of the brace expression of the deeper

level.  The example below shows this

@smallexample

glob ("@{foo/@{,bar,biz@},baz@}", GLOB_BRACE, NULL, &result)

@end smallexample

@noindent

is equivalent to the sequence

@smallexample

glob ("foo/", GLOB_BRACE, NULL, &result)

glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)

glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)

glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)

@end smallexample

@noindent

if we leave aside error handling.

@item GLOB_NOMAGIC

@standards{GNU, glob.h}

If the pattern contains no wildcard constructs (it is a literal file name),

return it as the sole ``matching'' word, even if no file exists by that name.

@item GLOB_TILDE

@standards{GNU, glob.h}

If this flag is used the character @code{~} (tilde) is handled specially

if it appears at the beginning of the pattern.  Instead of being taken

verbatim it is used to represent the home directory of a known user.

If @code{~} is the only character in pattern or it is followed by a

@code{/} (slash), the home directory of the process owner is

substituted.  Using @code{getlogin} and @code{getpwnam} the information

is read from the system databases.  As an example take user @code{bart}

with his home directory at @file{/home/bart}.  For him a call like

@smallexample

glob ("~/bin/*", GLOB_TILDE, NULL, &result)

@end smallexample

@noindent

would return the contents of the directory @file{/home/bart/bin}.

Instead of referring to the own home directory it is also possible to

name the home directory of other users.  To do so one has to append the

user name after the tilde character.  So the contents of user

@code{homer}'s @file{bin} directory can be retrieved by

@smallexample

glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)

@end smallexample

If the user name is not valid or the home directory cannot be determined

for some reason the pattern is left untouched and itself used as the

result.  I.e., if in the last example @code{home} is not available the

tilde expansion yields to @code{"~homer/bin/*"} and @code{glob} is not

looking for a directory named @code{~homer}.

This functionality is equivalent to what is available in C-shells if the

@code{nonomatch} flag is set.

@item GLOB_TILDE_CHECK

@standards{GNU, glob.h}

If this flag is used @code{glob} behaves as if @code{GLOB_TILDE} is

given.  The only difference is that if the user name is not available or

the home directory cannot be determined for other reasons this leads to

an error.  @code{glob} will return @code{GLOB_NOMATCH} instead of using

the pattern itself as the name.

This functionality is equivalent to what is available in C-shells if

the @code{nonomatch} flag is not set.

@item GLOB_ONLYDIR

@standards{GNU, glob.h}

If this flag is used the globbing function takes this as a

@strong{hint} that the caller is only interested in directories

matching the pattern.  If the information about the type of the file

is easily available non-directories will be rejected but no extra

work will be done to determine the information for each file.  I.e.,

the caller must still be able to filter directories out.

This functionality is only available with the GNU @code{glob}

implementation.  It is mainly used internally to increase the

performance but might be useful for a user as well and therefore is

documented here.

@end vtable

Calling @code{glob} will in most cases allocate resources which are used

to represent the result of the function call.  If the same object of

type @code{glob_t} is used in multiple call to @code{glob} the resources

are freed or reused so that no leaks appear.  But this does not include

the time when all @code{glob} calls are done.

@deftypefun void globfree (glob_t *@var{pglob})

@standards{POSIX.2, glob.h}

@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}

@c globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem

@c  free dup @ascuheap @acsmem

The @code{globfree} function frees all resources allocated by previous

calls to @code{glob} associated with the object pointed to by

@var{pglob}.  This function should be called whenever the currently used

@code{glob_t} typed object isn't used anymore.

@end deftypefun

@deftypefun void globfree64 (glob64_t *@var{pglob})

@standards{GNU, glob.h}

@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}

This function is equivalent to @code{globfree} but it frees records of

type @code{glob64_t} which were allocated by @code{glob64}.

@end deftypefun

@node Regular Expressions

@section Regular Expression Matching

@Theglibc{} supports two interfaces for matching regular

expressions.  One is the standard POSIX.2 interface, and the other is

what @theglibc{} has had for many years.

Both interfaces are declared in the header file @file{regex.h}.

If you define @w{@code{_POSIX_C_SOURCE}}, then only the POSIX.2

functions, structures, and constants are declared.

@c !!! we only document the POSIX.2 interface here!!

@menu

* POSIX Regexp Compilation::    Using @code{regcomp} to prepare to match.

* Flags for POSIX Regexps::     Syntax variations for @code{regcomp}.

* Matching POSIX Regexps::      Using @code{regexec} to match the compiled

				   pattern that you get from @code{regcomp}.

* Regexp Subexpressions::       Finding which parts of the string were matched.

* Subexpression Complications:: Find points of which parts were matched.

* Regexp Cleanup::		Freeing storage; reporting errors.

@end menu

@node POSIX Regexp Compilation

@subsection POSIX Regular Expression Compilation

Before you can actually match a regular expression, you must

@dfn{compile} it.  This is not true compilation---it produces a special

data structure, not machine instructions.  But it is like ordinary

compilation in that its purpose is to enable you to ``execute'' the

pattern fast.  (@xref{Matching POSIX Regexps}, for how to use the

compiled regular expression for matching.)

There is a special data type for compiled regular expressions:

@deftp {Data Type} regex_t

@standards{POSIX.2, regex.h}

This type of object holds a compiled regular expression.

It is actually a structure.  It has just one field that your programs

should look at:

@table @code

@item re_nsub

This field holds the number of parenthetical subexpressions in the

regular expression that was compiled.

@end table

There are several other fields, but we don't describe them here, because

only the functions in the library should use them.

@end deftp

After you create a @code{regex_t} object, you can compile a regular

expression into it by calling @code{regcomp}.

@deftypefun int regcomp (regex_t *restrict @var{compiled}, const char *restrict @var{pattern}, int @var{cflags})

@standards{POSIX.2, regex.h}

@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}

@c All of the issues have to do with memory allocation and multi-byte

@c character handling present in the input string, or implied by ranges

@c or inverted character classes.

@c (re_)malloc @ascuheap @acsmem

@c re_compile_internal @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c  (re_)realloc @ascuheap @acsmem [no @asucorrupt @acucorrupt for we zero the buffer]

@c  init_dfa @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c   (re_)malloc @ascuheap @acsmem

@c   calloc @ascuheap @acsmem

@c   _NL_CURRENT ok

@c   _NL_CURRENT_WORD ok

@c   btowc @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c  libc_lock_init ok

@c  re_string_construct @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c   re_string_construct_common ok

@c   re_string_realloc_buffers @ascuheap @acsmem

@c    (re_)realloc dup @ascuheap @acsmem

@c   build_wcs_upper_buffer @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c    isascii ok

@c    mbsinit ok

@c    toupper ok

@c    mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c    iswlower @mtslocale

@c    towupper @mtslocale

@c    wcrtomb dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c    (re_)malloc dup @ascuheap @acsmem

@c   build_upper_buffer ok (@mtslocale but optimized)

@c    islower ok

@c    toupper ok

@c   build_wcs_buffer @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c    mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c   re_string_translate_buffer ok

@c  parse @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c   fetch_token @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd

@c    peek_token @mtslocale

@c     re_string_eoi ok

@c     re_string_peek_byte ok

@c     re_string_cur_idx ok

@c     re_string_length ok

@c     re_string_peek_byte_case @mtslocale

@c      re_string_peek_byte dup ok

@c      re_string_is_single_byte_char ok

@c      isascii ok

@c      re_string_peek_byte dup ok

@c     re_string_wchar_at ok

@c     re_string_skip_bytes ok