about summary refs log tree commit diff
path: root/manual/pattern.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/pattern.texi')
-rw-r--r--manual/pattern.texi125
1 files changed, 119 insertions, 6 deletions
diff --git a/manual/pattern.texi b/manual/pattern.texi
index 1a90ddc240..6479a1fbec 100644
--- a/manual/pattern.texi
+++ b/manual/pattern.texi
@@ -205,6 +205,84 @@ 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}.
+
+@comment glob.h
+@comment GNU
+@deftp {Data Type} glob64_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.  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.
+@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})
@@ -234,7 +312,7 @@ that your application is making.
 If @code{glob} succeeds, it returns 0.  Otherwise, it returns one
 of these error codes:
 
-@table @code
+@vtable @code
 @comment glob.h
 @comment POSIX.2
 @item GLOB_ABORTED
@@ -261,10 +339,38 @@ at least one file.
 @comment POSIX.2
 @item GLOB_NOSPACE
 It was impossible to allocate memory to hold the result.
-@end table
+@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 notive 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 assumptions made by
+the Unix standard.  The GNU extension of allowing the user to provide
+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
+
+@comment glob.h
+@comment GNU
+@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})
+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 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.
+
+Beside this difference the @code{glob64} works just like @code{glob} in
+all aspects.
+
+This function is a GNU extension.
 @end deftypefun
 
 @node Flags for Globbing
@@ -274,7 +380,7 @@ 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{|}.
 
-@table @code
+@vtable @code
 @comment glob.h
 @comment POSIX.2
 @item GLOB_APPEND
@@ -362,7 +468,7 @@ 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}.
-@end table
+@end vtable
 
 @node More Flags for Globbing
 @subsection More Flags for Globbing
@@ -372,7 +478,7 @@ Beside the flags described in the last section, the GNU implementation of
 @file{glob.h} file.  Some of the extensions implement functionality
 which is available in modern shell implementations.
 
-@table @code
+@vtable @code
 @comment glob.h
 @comment GNU
 @item GLOB_PERIOD
@@ -502,7 +608,7 @@ 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 table
+@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
@@ -519,6 +625,13 @@ calls to @code{glob} associated with the object pointed to by
 @code{glob_t} typed object isn't used anymore.
 @end deftypefun
 
+@comment glob.h
+@comment GNU
+@deftypefun void globfree64 (glob64_t *@var{pglob})
+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