Finish gettext section.
[kopensolaris-gnu/glibc.git] / manual / pattern.texi
index 903aa48..1decfe3 100644 (file)
@@ -70,7 +70,7 @@ 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} falgs together for matching
+@code{FNM_PERIOD} and @code{FNM_FILE_NAME} flags together for matching
 file names.)
 
 @comment fnmatch.h
@@ -118,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
@@ -134,7 +135,9 @@ 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
@@ -156,6 +159,47 @@ 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
 
@@ -178,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
@@ -224,7 +268,7 @@ 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 bitwise OR operator @code{|}.
 
@@ -318,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
 
@@ -483,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
@@ -530,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
@@ -538,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
@@ -549,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
@@ -594,7 +745,7 @@ subexpression.
 @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
@@ -661,7 +812,7 @@ 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
 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.
 
@@ -738,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.
 
@@ -936,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{|}.
 
@@ -1051,9 +1202,6 @@ expand_and_execute (const char *program, const char *options)
 @}
 @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
@@ -1139,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