Finish gettext section.
[kopensolaris-gnu/glibc.git] / manual / pattern.texi
index 0056700..1decfe3 100644 (file)
@@ -1,8 +1,10 @@
 @node Pattern Matching, I/O Overview, Searching and Sorting, Top
 @chapter Pattern Matching
 
-The GNU C Library provides pattern matching facilities for two kinds
-of patterns: regular expressions and file-name wildcards.
+The GNU C Library 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.
@@ -66,8 +68,10 @@ Treat the @samp{.} character specially if it appears at the beginning of
 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}.
+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.)
 
 @comment fnmatch.h
 @comment POSIX.2
@@ -114,8 +118,9 @@ 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}.
+* 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
@@ -130,14 +135,16 @@ it fills in the structure's fields to tell you about the results.
 @comment POSIX.2
 @deftp {Data Type} glob_t
 This data type holds a pointer to a word vector.  More precisely, it
-records both the address of the word vector and its size.
+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.
 
 @item gl_pathv
-The address of the vector.  This field has type @code{char **}.
+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
@@ -152,12 +159,53 @@ 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 *)}}.
+
+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{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 @w{@code{int
+(*) (const char *, struct stat *)}}.
+
+This is a GNU extension.
 @end table
 @end deftp
 
 @comment glob.h
 @comment POSIX.2
-@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})
+@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})
 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
@@ -174,7 +222,7 @@ 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 
+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
@@ -191,6 +239,13 @@ of these error codes:
 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}.
 
 @comment glob.h
 @comment POSIX.2
@@ -213,9 +268,9 @@ In the event of an error, @code{glob} stores information in
 @node Flags for Globbing
 @subsection Flags for Globbing
 
-This section describes the flags that you can specify in the 
+This section describes the flags that you can specify in the
 @var{flags} argument to @code{glob}.  Choose the flags you want,
-and combine them with the C operator @code{|}.
+and combine them with the C bitwise OR operator @code{|}.
 
 @table @code
 @comment glob.h
@@ -230,6 +285,12 @@ 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.
+
 @comment glob.h
 @comment POSIX.2
 @item GLOB_DOOFFS
@@ -246,15 +307,15 @@ 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
-nonzero, 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:
+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:
 
-@example
+@smallexample
 (*@var{errfunc}) (@var{filename}, @var{error-code})
-@end example
+@end smallexample
 
 @noindent
 The argument @var{filename} is the name of the directory that
@@ -301,6 +362,113 @@ repeatedly.  It handles the flag @code{GLOB_NOESCAPE} by turning on the
 @code{FNM_NOESCAPE} flag in calls to @code{fnmatch}.
 @end table
 
+@node More Flags for Globbing
+@subsection More Flags for Globbing
+
+Beside the flags descibed 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.
+
+@table @code
+@comment glob.h
+@comment GNU
+@item GLOB_PERIOD
+The @code{.} character (period) is treated special.  It cannot be
+matched by wildcards.  @xref{Wildcard Matching}, @code{FNM_PERIOD}.
+
+@comment glob.h
+@comment GNU
+@item GLOB_MAGCHAR
+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.
+
+@comment glob.h
+@comment GNU
+@item GLOB_ALTDIRFUNC
+Instead of the using the 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 @ref{Accessing Directories} and
+@ref{Reading Attributes}.
+
+@comment glob.h
+@comment GNU
+@item GLOB_BRACE
+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 mathing braces is separated into single
+expressions by splitting at @code{,} (comma) characters.  The commas
+themself 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.
+
+@comment glob.h
+@comment GNU
+@item GLOB_NOMAGIC
+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.
+
+@comment glob.h
+@comment GNU
+@item GLOB_TILDE
+If this flag is used the character @code{~} (tilde) is handled special
+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
+
+This functionality is equivalent to what is available in C-shells.
+@end table
+
+
 @node Regular Expressions
 @section Regular Expression Matching
 
@@ -309,10 +477,9 @@ expressions.  One is the standard POSIX.2 interface, and the other is
 what the GNU system has had for many years.
 
 Both interfaces are declared in the header file @file{regex.h}.
-If you define @code{_GNU_SOURCE}, then the GNU functions, structures
-and constants are declared.  Otherwise, only the POSIX names are
-declared.
-@c !!! wrong-- default is GNU
+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.
@@ -459,7 +626,7 @@ One of the endpoints in a range expression was invalid.
 @comment regex.h
 @comment POSIX.2
 @item REG_ESPACE
-@code{regcomp} or @code{regexec} ran out of memory.
+@code{regcomp} ran out of memory.
 @end table
 
 @node Flags for POSIX Regexps
@@ -467,7 +634,7 @@ One of the endpoints in a range expression was invalid.
 
 These are the bit flags that you can use in the @var{cflags} operand when
 compiling a regular expression with @code{regcomp}.
+
 @table @code
 @comment regex.h
 @comment POSIX.2
@@ -483,7 +650,7 @@ Ignore case when matching letters.
 @comment regex.h
 @comment POSIX.2
 @item REG_NOSUB
-Don't bother storing the contents of the @var{matches_ptr} array.
+Don't bother storing the contents of the @var{matches-ptr} array.
 
 @comment regex.h
 @comment POSIX.2
@@ -514,7 +681,7 @@ This function tries to match the compiled regular expression
 @code{regexec} returns @code{0} if the regular expression matches;
 otherwise, it returns a nonzero value.  See the table below for
 what nonzero values mean.  You can use @code{regerror} to produce an
-error message string describing the reason for a nonzero value; 
+error message string describing the reason for a nonzero value;
 see @ref{Regexp Cleanup}.
 
 The argument @var{eflags} is a word of bit flags that enable various
@@ -522,7 +689,7 @@ options.
 
 If you want to get information about what part of @var{string} actually
 matched the regular expression or its subexpressions, use the arguments
-@var{matchptr} and @var{nmatch}.  Otherwise, pass @code{0} for 
+@var{matchptr} and @var{nmatch}.  Otherwise, pass @code{0} for
 @var{nmatch}, and @code{NULL} for @var{matchptr}.  @xref{Regexp
 Subexpressions}.
 @end deftypefun
@@ -533,7 +700,7 @@ locales that were in effect when you compiled the regular expression.
 The function @code{regexec} accepts the following flags in the
 @var{eflags} argument:
 
-@table @code 
+@table @code
 @comment regex.h
 @comment POSIX.2
 @item REG_NOTBOL
@@ -559,27 +726,26 @@ The pattern didn't match the string.  This isn't really an error.
 @comment regex.h
 @comment POSIX.2
 @item REG_ESPACE
-@code{regcomp} or @code{regexec} ran out of memory.
+@code{regexec} ran out of memory.
 @end table
 
 @node Regexp Subexpressions
-@c !!! I think this title is awkward -rm 
-@subsection Subexpressions Match Results
+@subsection Match Results with Subexpressions
 
 When @code{regexec} matches parenthetical subexpressions of
 @var{pattern}, it records which parts of @var{string} they match.  It
 returns that information by storing the offsets into an array whose
 elements are structures of type @code{regmatch_t}.  The first element of
-the array records the part of the string that matched the entire regular
-expression.  Each other element of the array records the beginning and
-end of the part that matched a single parenthetical subexpression.
-@c !!! in this paragraph, [0] is called "first"; see below
+the array (index @code{0}) records the part of the string that matched
+the entire regular expression.  Each other element of the array records
+the beginning and end of the part that matched a single parenthetical
+subexpression.
 
 @comment regex.h
 @comment POSIX.2
 @deftp {Data Type} regmatch_t
 This is the data type of the @var{matcharray} array that you pass to
-@code{regexec}.  It containes two structure fields, as follows:
+@code{regexec}.  It contains two structure fields, as follows:
 
 @table @code
 @item rm_so
@@ -599,10 +765,10 @@ The fields of @code{regmatch_t} have type @code{regoff_t}.
 @end deftp
 
 The @code{regmatch_t} elements correspond to subexpressions
-positionally; the first element records where the first subexpression
-matched, the second element records the second subexpression, and so on.
-The order of the subexpressions is the order in which they begin.
-@c !!! here [1] is called "first"; see above
+positionally; the first element (index @code{1}) records where the first
+subexpression matched, the second element records the second
+subexpression, and so on.  The order of the subexpressions is the order
+in which they begin.
 
 When you call @code{regexec}, you specify how long the @var{matchptr}
 array is, with the @var{nmatch} argument.  This tells @code{regexec} how
@@ -644,19 +810,20 @@ accurate to say that the last @emph{opportunity} to match is the one
 that takes precedence.  What this means is that when one subexpression
 appears within another, then the results reported for the inner
 subexpression reflect whatever happened on the last match of the outer
-subexpression.  For an example, consider @samp{\(ba\(na\)*s \)} matching
+subexpression.  For an example, consider @samp{\(ba\(na\)*s \)*} matching
 the string @samp{bananas bas }.  The last time the inner expression
-actually matches is near the end of the first word.  But it is 
+actually matches is near the end of the first word.  But it is
 @emph{considered} again in the second word, and fails to match there.
 @code{regexec} reports nonuse of the ``na'' subexpression.
 
-Another place where this rule applies is when @samp{\(ba\(na\)*s
-\|nefer\(ti\)* \)*} matches @samp{bananas nefertiti}.  The ``na''
-subexpression does match in the first word, but it doesn't match in the
-second word because the other alternative is used there.  Once again,
-the second repetition of the outer subexpression overrides the first,
-and within that second repetition, the ``na'' subexpression is not used.
-So @code{regexec} reports nonuse of the ``na'' subexpression.
+Another place where this rule applies is when the regular expression
+@w{@samp{\(ba\(na\)*s \|nefer\(ti\)* \)*}} matches @samp{bananas nefertiti}.
+The ``na'' subexpression does match in the first word, but it doesn't
+match in the second word because the other alternative is used there.
+Once again, the second repetition of the outer subexpression overrides
+the first, and within that second repetition, the ``na'' subexpression
+is not used.  So @code{regexec} reports nonuse of the ``na''
+subexpression.
 
 @node Regexp Cleanup
 @subsection POSIX Regexp Matching Cleanup
@@ -702,8 +869,10 @@ store the entire error message.  If this is less than @var{length}, then
 the error message was not truncated, and you can use it.  Otherwise, you
 should call @code{regerror} again with a larger buffer.
 
-@c !!! i wrote this example of how to do it right (i think) -- intro it. -rm
-@example
+Here is a function which uses @code{regerror}, but always dynamically
+allocates a buffer for the error message:
+
+@smallexample
 char *get_regerror (int errcode, regex_t *compiled)
 @{
   size_t length = regerror (errcode, compiled, NULL, 0);
@@ -711,7 +880,7 @@ char *get_regerror (int errcode, regex_t *compiled)
   (void) regerror (errcode, compiled, buffer, length);
   return buffer;
 @}
-@end example
+@end smallexample
 @end deftypefun
 
 @c !!!! this is not actually in the library....
@@ -720,7 +889,7 @@ char *get_regerror (int errcode, regex_t *compiled)
 @cindex word expansion
 @cindex expansion of shell words
 
-@dfn{Word expansion} means the process of splitting a string into 
+@dfn{Word expansion} means the process of splitting a string into
 @dfn{words} and substituting for variables, commands, and wildcards
 just as the shell does.
 
@@ -767,19 +936,19 @@ from left to right:
 @item
 @cindex variable substitution
 @cindex substitution of variables and commands
-@dfn{Variable substitution}: The substitution of environment variables
-for references such as @samp{$foo}.
+@dfn{Variable substitution}: Environment variables are substituted for
+references such as @samp{$foo}.
 
 @item
 @cindex command substitution
-@dfn{Command substitution}: Replacement of constructs such as 
-@samp{`cat foo`} or @samp{$(cat foo)} with the output from the inner
-command.
+@dfn{Command substitution}: Constructs such as @w{@samp{`cat foo`}} and
+the equivalent @w{@samp{$(cat foo)}} are replaced with the output from
+the inner command.
 
 @item
 @cindex arithmetic expansion
-@dfn{Arithmetic expansion}: Replacement of constructs such as
-@samp{$(($x-1))} with the result of the arithmetic computation.
+@dfn{Arithmetic expansion}: Constructs such as @samp{$(($x-1))} are
+replaced with the result of the arithmetic computation.
 @end itemize
 
 @item
@@ -825,7 +994,7 @@ records both the address of the word vector and its size.
 The number of elements in the vector.
 
 @item we_wordv
-The address of the vector.  This field has type @code{char **}.
+The address of the vector.  This field has type @w{@code{char **}}.
 
 @item we_offs
 The offset of the first real element of the vector, from its nominal
@@ -918,7 +1087,7 @@ data it points to.
 @node Flags for Wordexp
 @subsection Flags for Word Expansion
 
-This section describes the flags that you can specify in the 
+This section describes the flags that you can specify in the
 @var{flags} argument to @code{wordexp}.  Choose the flags you want,
 and combine them with the C operator @code{|}.
 
@@ -955,6 +1124,10 @@ Reuse a word vector made by a previous call to @code{wordexp}.
 Instead of allocating a new vector of words, this call to @code{wordexp}
 will use the vector that already exists (making it larger if necessary).
 
+Note that the vector may move, so it is not safe to save an old pointer
+and use it again after calling @code{wordexp}.  You must fetch
+@code{we_pathv} anew after each call.
+
 @comment wordexp.h
 @comment POSIX.2
 @item WRDE_SHOWERR
@@ -978,7 +1151,7 @@ and use the results to run a shell command.  It also shows the use of
 @code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}
 to free the space allocated by @code{wordexp}.
 
-@example
+@smallexample
 int
 expand_and_execute (const char *program, const char *options)
 @{
@@ -1027,11 +1200,8 @@ expand_and_execute (const char *program, const char *options)
   wordfree (&result);
   return status;
 @}
-@end example
+@end smallexample
 
-In practice, since @code{wordexp} is executed by running a subshell, it
-would be faster to do this by concatenating the strings with spaces
-between them and running that as a shell command using @samp{sh -c}.
 
 @c No sense finishing this for here.
 @ignore
@@ -1117,7 +1287,7 @@ characters in the value of @var{variable}.  @samp{$@{#foo@}} stands for
 @end table
 
 These variants of variable substitution let you remove part of the
-variable's value before substituting it.  The @var{prefix} and 
+variable's value before substituting it.  The @var{prefix} and
 @var{suffix} are not mere strings; they are wildcard patterns, just
 like the patterns that you use to match multiple file names.  But
 in this context, they match against parts of the variable value