filefuncs extension provides three different functions, as follows.
The usage is:
This is how you load the extension.
result = chdir("/some/directory")
chdir() function is a direct hook to the
system call to change the current directory. It returns zero
upon success or a value less than zero upon error.
In the latter case, it updates
result = stat("/some/path", statdata[
stat() function provides a hook into the
stat() system call.
It returns zero upon success or a value less than zero upon error.
In the latter case, it updates
By default, it uses the
lstat() system call. However, if passed
a third argument, it uses
In all cases, it clears the
When the call is successful,
stat() fills the
array with information retrieved from the filesystem, as follows:
|Subscript||Field in ||File type|
|The file name||All|
|A human-readable version of the mode value, like that printed by
|The value of the symbolic link||Symbolic links|
|The type of the file as a string—one of
flags = or(FTS_PHYSICAL, ...)
result = fts(pathlist, flags, filedata)
Walk the file trees provided in
pathlist and fill in the
filedata array, as described next.
flags is the bitwise
OR of several predefined values, also described in a moment.
Return zero if there were no errors, otherwise return -1.
fts() function provides a hook to the C library
routines for traversing file hierarchies. Instead of returning data
about one file at a time in a stream, it fills in a multidimensional
array with data about each file and directory encountered in the requested
The arguments are as follows:
An array of file names. The element values are used; the index values are ignored.
This should be the bitwise OR of one or more of the following
predefined constant flag values. At least one of
FTS_PHYSICAL must be provided; otherwise
fts() returns an error value and sets
The flags are:
Do a “logical” file traversal, where the information returned for
a symbolic link refers to the linked-to file, and not to the symbolic
link itself. This flag is mutually exclusive with
Do a “physical” file traversal, where the information returned for a
symbolic link refers to the symbolic link itself. This flag is mutually
As a performance optimization, the C library
change directory as they traverse a file hierarchy. This flag disables
Immediately follow a symbolic link named in
whether or not
FTS_LOGICAL is set.
By default, the C library
fts() routines do not return entries for
. (dot) and .. (dot-dot). This option causes entries for
dot-dot to also be included. (The extension always includes an entry
for dot; more on this in a moment.)
During a traversal, do not cross onto a different mounted filesystem.
filedata array holds the results.
fts() first clears it. Then it creates
an element in
filedata for every element in
The index is the name of the directory or file given in
The element for this index is itself an array. There are two cases:
In this case, the array contains two or three elements:
The full path to this file, starting from the “root” that was given
This element is itself an array, containing the same information as provided
stat() function described earlier for its
statdata argument. The element may not be present if
stat() system call for the file failed.
If some kind of error was encountered, the array will also
contain an element named
"error", which is a string describing the error.
In this case, the array contains one element for each entry in the
directory. If an entry is a file, that element is the same as for files, just
described. If the entry is a directory, that element is (recursively)
an array describing the subdirectory. If
FTS_SEEDOT was provided
in the flags, then there will also be an element named
element will be an array containing the data as provided by
In addition, there will be an element whose index is
This element is an array containing the same two or three elements as
for a file:
fts() function returns zero if there were no errors.
Otherwise, it returns -1.
fts()extension does not exactly mimic the interface of the C library
fts()routines, choosing instead to provide an interface that is based on associative arrays, which is more comfortable to use from an
awkprogram. This includes the lack of a comparison function, because
gawkalready provides powerful array sorting facilities. Although an
fts_read()-like interface could have been provided, this felt less natural than simply creating a multidimensional array to represent the file hierarchy and its information.
See test/fts.awk in the
gawk distribution for an example
use of the
fts() extension function.