530 lines
12 KiB
HTML
530 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of FILEFUNCS</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>FILEFUNCS</H1>
|
|
Section: GNU Awk Extension Modules (3am)<BR>Updated: Feb 21 2018<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
filefuncs - provide some file related functionality to gawk
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
@load "filefuncs"
|
|
<P>
|
|
result = chdir("/some/directory")
|
|
<P>
|
|
result = stat("/some/path", statdata [, follow])
|
|
<P>
|
|
flags = or(FTS_PHYSICAL, ...)
|
|
<BR>
|
|
|
|
result = fts(pathlist, flags, filedata)
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<I>filefuncs</I>
|
|
|
|
extension adds several functions that provide access to
|
|
file-related facilities.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>chdir()</H3>
|
|
|
|
The
|
|
<B>chdir()</B>
|
|
|
|
function is a direct hook to the
|
|
<I><A HREF="/cgi-bin/man/man2html?2+chdir">chdir</A></I>(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
|
|
<B>ERRNO</B>.
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>stat()</H3>
|
|
|
|
The
|
|
<B>stat()</B>
|
|
|
|
function provides a hook into the
|
|
<I><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></I>(2)
|
|
|
|
system call.
|
|
It returns zero
|
|
upon success or less than zero upon error.
|
|
In the latter case it updates
|
|
<B>ERRNO</B>.
|
|
|
|
By default, it uses
|
|
<I><A HREF="/cgi-bin/man/man2html?2+lstat">lstat</A></I>(2).
|
|
|
|
However, if passed a third argument, it uses
|
|
<I><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></I>(2),
|
|
|
|
instead.
|
|
<P>
|
|
|
|
In all cases, it clears the
|
|
<B>statdata</B>
|
|
|
|
array.
|
|
When the call is successful,
|
|
<B>stat()</B>
|
|
|
|
fills the
|
|
<B>statdata</B>
|
|
|
|
array with information retrieved from the filesystem, as follows:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>statdata["name"]</B><DD>
|
|
The name of the file.
|
|
<DT id="2"><B>statdata["dev"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_dev</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="3"><B>statdata["ino"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_ino</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="4"><B>statdata["mode"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_mode</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="5"><B>statdata["nlink"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_nlink</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="6"><B>statdata["uid"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_uid</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="7"><B>statdata["gid"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_gid</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="8"><B>statdata["size"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_size</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="9"><B>statdata["atime"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_atime</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="10"><B>statdata["mtime"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_mtime</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="11"><B>statdata["ctime"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_ctime</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
<DT id="12"><B>statdata["rdev"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_rdev</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
This element is only present for device files.
|
|
<DT id="13"><B>statdata["major"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_major</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
This element is only present for device files.
|
|
<DT id="14"><B>statdata["minor"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_minor</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>.
|
|
|
|
This element is only present for device files.
|
|
<DT id="15"><B>statdata["blksize"]</B><DD>
|
|
Corresponds to the
|
|
<I>st_blksize</I>
|
|
|
|
field in the
|
|
<I>struct stat</I>,
|
|
|
|
if this field is present on your system.
|
|
(It is present on all modern systems that we know of.)
|
|
<DT id="16"><B>statdata["pmode"]</B><DD>
|
|
A human-readable version of the mode value, such as printed by
|
|
<I><A HREF="/cgi-bin/man/man2html?1+ls">ls</A></I>(1).
|
|
|
|
For example, <B>"-rwxr-xr-x"</B>.
|
|
<DT id="17"><B>statdata["linkval"]</B><DD>
|
|
If the named file is a symbolic link, this element will exist
|
|
and its value is the value of the symbolic link (where the
|
|
symbolic link points to).
|
|
<DT id="18"><B>statdata["type"]</B><DD>
|
|
The type of the file as a string. One of
|
|
<B>"file"</B>,
|
|
<B>"blockdev"</B>,
|
|
<B>"chardev"</B>,
|
|
<B>"directory"</B>,
|
|
<B>"socket"</B>,
|
|
<B>"fifo"</B>,
|
|
<B>"symlink"</B>,
|
|
<B>"door"</B>,
|
|
or
|
|
<B>"unknown"</B>.
|
|
Not all systems support all file types.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>fts()</H3>
|
|
|
|
The
|
|
<B>fts()</B>
|
|
|
|
function provides a hook to the
|
|
<I><A HREF="/cgi-bin/man/man2html?3+fts">fts</A></I>(3)
|
|
|
|
set of routines for traversing file hierarchies.
|
|
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 hierarchies.
|
|
<P>
|
|
|
|
The arguments are as follows:
|
|
<DL COMPACT>
|
|
<DT id="19"><B>pathlist</B>
|
|
|
|
<DD>
|
|
An array of filenames. The element values are used; the index values are ignored.
|
|
<DT id="20"><B>flags</B>
|
|
|
|
<DD>
|
|
This should be the bitwise OR of one or more of the following
|
|
predefined flag values. At least one of
|
|
<B>FTS_LOGICAL</B>
|
|
|
|
or
|
|
<B>FTS_PHYSICAL</B>
|
|
|
|
must be provided; otherwise
|
|
<B>fts()</B>
|
|
|
|
returns an error value and sets
|
|
<B>ERRNO</B>.
|
|
|
|
<DL COMPACT><DT id="21"><DD>
|
|
<DL COMPACT>
|
|
<DT id="22"><B>FTS_LOGICAL</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>FTS_PHYSICAL</B>.
|
|
|
|
<DT id="23"><B>FTS_PHYSICAL</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>FTS_LOGICAL</B>.
|
|
|
|
<DT id="24"><B>FTS_NOCHDIR</B>
|
|
|
|
<DD>
|
|
As a performance optimization, the
|
|
<I><A HREF="/cgi-bin/man/man2html?3+fts">fts</A></I>(3)
|
|
|
|
routines change directory as they traverse a file hierarchy.
|
|
This flag disables that optimization.
|
|
<DT id="25"><B>FTS_COMFOLLOW</B>
|
|
|
|
<DD>
|
|
Immediately follow a symbolic link named in
|
|
<B>pathlist</B>,
|
|
|
|
whether or not
|
|
<B>FTS_LOGICAL</B>
|
|
|
|
is set.
|
|
<DT id="26"><B>FTS_SEEDOT</B>
|
|
|
|
<DD>
|
|
By default, the
|
|
<I><A HREF="/cgi-bin/man/man2html?3+fts">fts</A></I>(3)
|
|
|
|
routines do not return entries for ``.'' and ``..''.
|
|
This option causes entries for ``..'' to also be included.
|
|
(The AWK extension always includes an entry for ``.'', see below.)
|
|
<DT id="27"><B>FTS_XDEV</B>
|
|
|
|
<DD>
|
|
During a traversal, do not cross onto a different mounted filesystem.
|
|
<DT id="28"><B>FTS_SKIP</B>
|
|
|
|
<DD>
|
|
When set, causes top level directories to not be descended into.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="29"><B>filedata</B>
|
|
|
|
<DD>
|
|
The
|
|
<B>filedata</B>
|
|
|
|
array is first cleared.
|
|
Then,
|
|
<B>fts()</B>
|
|
|
|
creates an element in
|
|
<B>filedata</B>
|
|
|
|
for every element in
|
|
<B>pathlist</B>.
|
|
|
|
The index is the name of the directory or file given in
|
|
<B>pathlist</B>.
|
|
|
|
The element for this index is itself an array.
|
|
There are two cases.
|
|
<DL COMPACT><DT id="30"><DD>
|
|
<DL COMPACT>
|
|
<DT id="31">The path is a file.<DD>
|
|
In this case, the array contains two or three elements:
|
|
<DL COMPACT><DT id="32"><DD>
|
|
<DL COMPACT>
|
|
<DT id="33"><B>"path"</B><DD>
|
|
The full path to this file, starting from the ``root'' that was given
|
|
in the
|
|
<B>pathlist</B>
|
|
|
|
array.
|
|
<DT id="34"><B>"stat"</B><DD>
|
|
This element is itself an array, containing the same information as provided
|
|
by the
|
|
<B>stat()</B>
|
|
|
|
function described earlier for its
|
|
<B>statdata</B>
|
|
|
|
argument.
|
|
The element may not be present if
|
|
<I><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></I>(2)
|
|
|
|
for the file failed.
|
|
<DT id="35"><B>"error"</B><DD>
|
|
If some kind of error was encountered, the array will also
|
|
contain an element named <B>"error"</B>, which is a string describing the error.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="36">The path is a directory.<DD>
|
|
In this case, the array contains one element for each entry in the directory.
|
|
If an entry is a file, that element is as for files, just described.
|
|
If the entry is a directory, that element is (recursively), an array describing
|
|
the subdirectory.
|
|
If
|
|
<B>FTS_SEEDOT</B>
|
|
|
|
was provided in the flags, then there will also be an element named
|
|
<B>".."</B>. This element will be an array containing the data
|
|
as provided by
|
|
<B>stat()</B>.
|
|
|
|
<P>
|
|
In addition, there will be an element whose index is <B>"."</B>.
|
|
This element is an array containing the same two or three elements
|
|
as for a file:
|
|
<B>"path"</B>,
|
|
<B>"stat"</B>,
|
|
and
|
|
<B>"error"</B>.
|
|
</DL>
|
|
</DL>
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
The
|
|
<B>fts()</B>
|
|
|
|
function returns 0 if there were no errors. Otherwise it returns -1.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The AWK
|
|
<B>fts()</B>
|
|
|
|
extension does not exactly mimic the interface of the
|
|
<I><A HREF="/cgi-bin/man/man2html?3+fts">fts</A></I>(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
|
|
<I>gawk</I>
|
|
|
|
already provides powerful array sorting facilities. While an
|
|
<I>fts_read()</I>-like
|
|
|
|
interface could have been provided, this felt less natural than
|
|
simply creating a multi-dimensional array to represent the file
|
|
hierarchy and its information.
|
|
<P>
|
|
|
|
Nothing prevents AWK code from changing the predefined
|
|
<B>FTS_</B><I>xx</I>
|
|
|
|
values, but doing so may cause strange results when
|
|
the changed values are passed to
|
|
<B>fts()</B>.
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
There are many more file-related functions for which AWK
|
|
interfaces would be desirable.
|
|
<P>
|
|
|
|
It's not clear why I thought adding
|
|
<B>FTS_SKIP</B>
|
|
|
|
was a good idea.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
See
|
|
<B>test/fts.awk</B>
|
|
|
|
in the
|
|
<I>gawk</I>
|
|
|
|
distribution for an example.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<I>GAWK: Effective AWK Programming</I>,
|
|
|
|
<I>fnmatch</I>(3am),
|
|
|
|
<I>fork</I>(3am),
|
|
|
|
<I>inplace</I>(3am),
|
|
|
|
<I>ordchr</I>(3am),
|
|
|
|
<I>readdir</I>(3am),
|
|
|
|
<I>readfile</I>(3am),
|
|
|
|
<I>revoutput</I>(3am),
|
|
|
|
<I>rwarray</I>(3am),
|
|
|
|
<I>time</I>(3am).
|
|
|
|
<P>
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?2+chdir">chdir</A></I>(2),
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?3+fts">fts</A></I>(3),
|
|
|
|
<I><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></I>(2).
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Arnold Robbins,
|
|
<B><A HREF="mailto:arnold@skeeve.com">arnold@skeeve.com</A></B>.
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>COPYING PERMISSIONS</H2>
|
|
|
|
Copyright © 2012, 2013, 2018,
|
|
Free Software Foundation, Inc.
|
|
<P>
|
|
|
|
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.
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Permission is granted to copy and distribute translations of this
|
|
manual page into another language, under the above conditions for
|
|
modified versions, except that this permission notice may be stated in
|
|
a translation approved by the Foundation.
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="37"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="38"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="39"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="40"><A HREF="#lbAE">chdir()</A><DD>
|
|
<DT id="41"><A HREF="#lbAF">stat()</A><DD>
|
|
<DT id="42"><A HREF="#lbAG">fts()</A><DD>
|
|
</DL>
|
|
<DT id="43"><A HREF="#lbAH">NOTES</A><DD>
|
|
<DT id="44"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="45"><A HREF="#lbAJ">EXAMPLE</A><DD>
|
|
<DT id="46"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="47"><A HREF="#lbAL">AUTHOR</A><DD>
|
|
<DT id="48"><A HREF="#lbAM">COPYING PERMISSIONS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:43 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|