result = chdir("/some/directory")
result = stat("/some/path", statdata [, follow])
flags = or(FTS_PHYSICAL, ...)
result = fts(pathlist, flags, filedata)
The filefuncs extension adds several functions that provide access to
The chdir() function is a direct hook to the chdir(2) system call to
change the current directory. It returns zero upon success or less
than zero upon error. In the latter case it updates ERRNO.
The stat() function provides a hook into the stat(2) system call. It
returns zero upon success or less than zero upon error. In the latter
case it updates ERRNO. By default, it uses lstat(2). However, if
passed a third argument, it uses stat(2), instead.
In all cases, it clears the statdata array. When the call is success-
ful, stat() fills the statdata array with information retrieved from
the filesystem, as follows:
The name of the file.
Corresponds to the st_dev field in the struct stat.
Corresponds to the st_ino field in the struct stat.
Corresponds to the st_mode field in the struct stat.
Corresponds to the st_nlink field in the struct stat.
Corresponds to the st_uid field in the struct stat.
Corresponds to the st_gid field in the struct stat.
Corresponds to the st_size field in the struct stat.
Corresponds to the st_atime field in the struct stat.
Corresponds to the st_major field in the struct stat. This ele-
ment is only present for device files.
Corresponds to the st_minor field in the struct stat. This ele-
ment is only present for device files.
Corresponds to the st_blksize field in the struct stat, if this
field is present on your system. (It is present on all modern
systems that we know of.)
A human-readable version of the mode value, such as printed by
ls(1). For example, "-rwxr-xr-x".
If the named file is a symbolic link, this element will exist
and its value is the value of the symbolic link (where the sym-
bolic link points to).
The type of the file as a string. One of "file", "blockdev",
"chardev", "directory", "socket", "fifo", "symlink", "door", or
"unknown". Not all systems support all file types.
The fts() function provides a hook to the fts(3) set of routines for
traversing file heirarchies. Instead of returning data about one file
at a time in a stream, it fills in a multi-dimensional array with data
about each file and directory encountered in the requested heirarchies.
The arguments are as follows:
An array of filenames. The element values are used; the index
values are ignored.
flags This should be the bitwise OR of one or more of the following
predefined flag values. At least one of FTS_LOGICAL or
FTS_PHYSICAL must be provided; otherwise fts() returns an error
value and sets ERRNO.
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 FTS_PHYSICAL.
Do a ``physical'' file traversal, where the information
returned for a symbolic link refers to the symbolic link
itself. This flag is mutually exclusive with FTS_LOGI-
``.'' and ``..''. This option causes entries for ``..''
to also be included. (The AWK extension always includes
an entry for ``.'', see below.)
During a traversal, do not cross onto a different mounted
The filedata array is first cleared. Then, fts() creates an
element in filedata for every element in pathlist. The index is
the name of the directory or file given in pathlist. The ele-
ment for this index is itself an array. There are two cases.
The path is a file.
In this case, the array contains two or three elements:
"path" The full path to this file, starting from the
``root'' that was given in the pathlist array.
"stat" This element is itself an array, containing the
same information as provided by the stat() func-
tion described earlier for its statdata argument.
The element may not be present if stat(2) for the
If some kind of error was encountered, the array
will also contain an element named "error", which
is a string describing the error.
The path is a directory.
In this case, the array contains one element for each
entry in the directory. If an entry is a file, that ele-
ment is 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
"..". This element will be an array containing the data
as provided by stat().
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: "path", "stat", and "error".
The fts() function returns 0 if there were no errors. Otherwise it
The AWK fts() extension does not exactly mimic the interface of the
fts(3) routines, choosing instead to provide an interface that is based
on associative arrays, which should be more comfortable to use from an
AWK program. This includes the lack of a comparison function, since
gawk already provides powerful array sorting facilities. While an
See test/fts.awk in the gawk distribution for an example.
GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am),
ordchr(3am), readdir(3am), readfile(3am), revoutput(3am), rwarray(3am),
chdir(2), fts(3), stat(2).
Arnold Robbins, email@example.com.
Copyright (C) 2012, 2013, Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual page provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual page under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this man-
ual page into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a trans-
lation approved by the Foundation.
Free Software Foundation Jan 15 2013 FILEFUNCS(3am)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2019
All Rights Reserved.