NAME
filefuncs - provide some file related functionality to gawk
SYNOPSIS
@load "filefuncs" result = chdir("/some/directory") result = stat("/some/path", statdata [, follow]) flags = or(FTS_PHYSICAL, ...) result = fts(pathlist, flags, filedata)
DESCRIPTION
The filefuncs extension adds several functions that provide access to file-related facilities. chdir() 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. stat() 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 successful, stat() fills the statdata array with information retrieved from the filesystem, as follows: statdata["name"] The name of the file. statdata["dev"] Corresponds to the st_dev field in the struct stat. statdata["ino"] Corresponds to the st_ino field in the struct stat. statdata["mode"] Corresponds to the st_mode field in the struct stat. statdata["nlink"] Corresponds to the st_nlink field in the struct stat. statdata["uid"] Corresponds to the st_uid field in the struct stat. statdata["gid"] Corresponds to the st_gid field in the struct stat. statdata["size"] Corresponds to the st_size field in the struct stat. statdata["atime"] Corresponds to the st_atime field in the struct stat. statdata["mtime"] Corresponds to the st_mtime field in the struct stat. statdata["ctime"] Corresponds to the st_ctime field in the struct stat. statdata["rdev"] Corresponds to the st_rdev field in the struct stat. This element is only present for device files. statdata["major"] Corresponds to the st_major field in the struct stat. This element is only present for device files. statdata["minor"] Corresponds to the st_minor field in the struct stat. This element is only present for device files. statdata["blksize"] 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.) statdata["pmode"] A human-readable version of the mode value, such as printed by ls(1). For example, "-rwxr-xr-x". statdata["linkval"] 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). statdata["type"] 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. fts() 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: pathlist 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. FTS_LOGICAL 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. 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_LOGICAL. FTS_NOCHDIR As a performance optimization, the fts(3) routines change directory as they traverse a file heirarchy. This flag disables that optimization. FTS_COMFOLLOW Immediatly follow a symbolic link named in pathlist, whether or not FTS_LOGICAL is set. FTS_SEEDOT By default, the fts(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.) FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. filedata 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 element 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() function described earlier for its statdata argument. The element may not be present if stat(2) for the file failed. "error" 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 element 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 returns -1.
NOTES
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 fts_read()-like interface could have been provided, this felt less natural than simply creating a multi-dimensional array to represent the file heirarchy and its information. Nothing prevents AWK code from changing the predefined FTS_xx values, but doing so is may cause strange results when the changed values are passed to fts().
BUGS
There are many more file-related functions for which AWK interfaces would be desirable.
EXAMPLE
See test/fts.awk in the gawk distribution for an example.
SEE ALSO
GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am), ordchr(3am), readdir(3am), readfile(3am), revoutput(3am), rwarray(3am), time(3am). chdir(2), fts(3), stat(2).
AUTHOR
Arnold Robbins, arnold@skeeve.com.
COPYING PERMISSIONS
Copyright 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 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.
More Linux Commands
manpages/groff_mdoc.7.html
groff_mdoc(7) - reference for groff's mdoc implementation...
groff_mdoc.7 - In most cases the first text in the DESCRIPTION section is a brief paragraph on the command, function or file, followed by a lexical list of opti
manpages/wcsncat.3.html
wcsncat(3) - concatenate two wide-character strings.........
The wcsncat() function is the wide-character equivalent of the strncat(3) function. It copies at most n wide characters from the wide-character string pointed t
manpages/ipcrm.1.html
ipcrm(1) - remove a message queue, semaphore set or shared m
ipcrm removes System V interprocess communication (IPC) objects and associated data structures from the system. In order to delete such objects, you must be sup
manpages/IsFunctionKey.3.html
IsFunctionKey(3) - keysym classification macros (Man Page)
The IsCursorKey macro returns True if the specified KeySym is a cursor key. The IsFunctionKey macro returns True if the KeySym is a function key. The IsKeypadKe
manpages/TIFFClose.3tiff.html
TIFFClose(3tiff) - close a previously opened TIFF file......
TIFFClose closes a file that was previously opened with TIFFOpen(3TIFF). Any buffered data are flushed to the file, including the contents of the current direct
manpages/glutSpecialUpFunc.3.html
glutSpecialUpFunc(3) - sets the special keyboard up (key rel
glutSpecialUpFunc sets the special keyboard up (key release) callback for the current window. The special keyboard up callback is triggered when keyboard functi
manpages/run-with-aspell.1.html
run-with-aspell(1) script to help use GNU Aspell as an ispel
The recommended way to use Aspell as a replacement for Ispell is to change the Ispell command from within the program being used. If that is not possible, the r
manpages/glSelectBuffer.3gl.html
glSelectBuffer(3gl) - establish a buffer for selection mode
glSelectBuffer has two arguments: buffer is a pointer to an array of unsigned integers, and size indicates the size of the array. buffer returns values from the
manpages/xev.1.html
xev(1) - print contents of X events - Linux manual page.....
Xev creates a window and then asks the X server to send it events whenever anything happens to the window (such as it being moved, resized, typed in, clicked in
manpages/FcInitLoadConfig.3.html
FcInitLoadConfig(3) - load configuration - Linux man page...
Loads the default configuration file and returns the resulting configuration. Does not load any font information. VERSION Fontconfig version 2.8.0 FcInitLoadCon
manpages/XvUngrabPort.3.html
XvUngrabPort(3) - release port grabbed for video operation
XvUngrabPort(3) releases a grabbed port. If time specifies a time before the last XvGrabPort(3) was executed, the request is ignored. RETURN VALUES [Success] Re
manpages/db.3.html
db(3) - database access methods (Library - Linux man page)
db.3 - Note well: This page documents interfaces provided in glibc up until version 2.1. Since version 2.2, glibc no longer provides these interfaces. Probably,
