path: root/manual/pattern.texi
diff options
authorFlorian Weimer <fweimer@redhat.com>2016-04-29 09:33:07 +0200
committerFlorian Weimer <fweimer@redhat.com>2016-04-29 09:35:30 +0200
commit137fe72eca6923a00381a3ca9f0e7672c1f85e3f (patch)
treefc4a07ab79ee0f89a6b9d4141d9f4639c87f2f33 /manual/pattern.texi
parenta7657f3012765b9c2d80c7387d487fc5156d3bc2 (diff)
glob: Simplify the interface for the GLOB_ALTDIRFUNC callback gl_readdir
Previously, application code had to set up the d_namlen member if the target supported it, involving conditional compilation. After this change, glob will use the length of the string in d_name instead of d_namlen to determine the file name length. All glibc targets provide the d_type and d_ino members, and setting them as needed for gl_readdir is straightforward. Changing the behavior with regards to d_ino is left to a future cleanup.
Diffstat (limited to 'manual/pattern.texi')
1 files changed, 38 insertions, 1 deletions
diff --git a/manual/pattern.texi b/manual/pattern.texi
index d1b9275cf9c..565e7eb6d4b 100644
--- a/manual/pattern.texi
+++ b/manual/pattern.texi
@@ -237,7 +237,44 @@ 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.
+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
+@end table
+The example below shows how to allocate a @code{struct dirent} object
+containing a given name.
+@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}