# filefuncs(3am) - man - phpMan [FILEFUNCS(3am)](https://www.chedong.com/phpMan.php/man/FILEFUNCS/3am/markdown) GNU Awk Extension Modules [FILEFUNCS(3am)](https://www.chedong.com/phpMan.php/man/FILEFUNCS/3am/markdown) ## 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) result = statvfs("/some/path", fsdata) ## DESCRIPTION The _filefuncs_ extension adds several functions that provide access to file-related facili‐ ties. ### chdir() The **chdir()** function is a direct hook to the [_chdir_(2)](https://www.chedong.com/phpMan.php/man/chdir/2/markdown) system call to change the current di‐ rectory. 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)](https://www.chedong.com/phpMan.php/man/stat/2/markdown) system call. It returns zero upon suc‐ cess or less than zero upon error. In the latter case it updates **ERRNO**. By default, it uses [_lstat_(2)](https://www.chedong.com/phpMan.php/man/lstat/2/markdown). However, if passed a third argument, it uses [_stat_(2)](https://www.chedong.com/phpMan.php/man/stat/2/markdown), 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, equal to the first argument passed to **stat()**. ### 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)](https://www.chedong.com/phpMan.php/man/ls/1/markdown). 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)](https://www.chedong.com/phpMan.php/man/fts/3/markdown) set of routines for traversing file hierar‐ chies. 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 hier‐ archies. 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)](https://www.chedong.com/phpMan.php/man/fts/3/markdown) routines change directory as they traverse a file hierarchy. This flag disables that optimization. **FTS**___**COMFOLLOW** Immediately follow a symbolic link named in **pathlist**, whether or not **FTS**___**LOGI**‐‐ **CAL** is set. **FTS**___**SEEDOT** By default, the [_fts_(3)](https://www.chedong.com/phpMan.php/man/fts/3/markdown) 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. **FTS**___**SKIP** When set, causes top level directories to not be descended into. ### 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 pro‐ vided by the **stat()** function described earlier for its **statdata** argu‐ ment. The element may not be present if [_stat_(2)](https://www.chedong.com/phpMan.php/man/stat/2/markdown) 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. ### statvfs() The **statvfs()** function provides a hook into the [_statvfs_(2)](https://www.chedong.com/phpMan.php/man/statvfs/2/markdown) system call on systems that supply this system call. It returns zero upon success or less than zero upon error. In the latter case it updates **ERRNO**. When the call is successful, **statvfs()** fills the **fsdata** array with information retrieved about the filesystem, as follows: ### fsdata["bsize"] Corresponds to the **bsize** member in the _struct_ _statvfs_. ### fsdata["frsize"] Corresponds to the _f_frsize_ member in the _struct_ _statvfs_. ### fsdata["blocks"] Corresponds to the _f_blocks_ member in the _struct_ _statvfs_. ### fsdata["bfree"] Corresponds to the _f_bfree_ member in the _struct_ _statvfs_. ### fsdata["bavail"] Corresponds to the _f_bavail_ member in the _struct_ _statvfs_. ### fsdata["files"] Corresponds to the _f_files_ member in the _struct_ _statvfs_. ### fsdata["ffree"] Corresponds to the _f_ffree_ member in the _struct_ _statvfs_. ### fsdata["favail"] Corresponds to the _f_favail_ member in the _struct_ _statvfs_. ### fsdata["fsid"] Corresponds to the _f_fsid_ member in the _struct_ _statvfs_. This member is not available on all systems. ### fsdata["flag"] Corresponds to the _f_flag_ member in the _struct_ _statvfs_. ### fsdata["namemax"] Corresponds to the _f_namemax_ member in the _struct_ _statvfs_. ## NOTES The AWK **fts()** extension does not exactly mimic the interface of the [_fts_(3)](https://www.chedong.com/phpMan.php/man/fts/3/markdown) 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 in‐ terface could have been provided, this felt less natural than simply creating a multi-dimen‐ sional array to represent the file hierarchy and its information. Nothing prevents AWK code from changing the predefined **FTS**__xx_ values, but doing so 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. It's not clear why I thought adding **FTS**___**SKIP** was a good idea. ## EXAMPLE See **test/fts.awk** in the _gawk_ distribution for an example. ## SEE ALSO _GAWK:_ _Effective_ _AWK_ _Programming_, [_fnmatch_(3am)](https://www.chedong.com/phpMan.php/man/fnmatch/3am/markdown), [_fork_(3am)](https://www.chedong.com/phpMan.php/man/fork/3am/markdown), [_inplace_(3am)](https://www.chedong.com/phpMan.php/man/inplace/3am/markdown), [_ordchr_(3am)](https://www.chedong.com/phpMan.php/man/ordchr/3am/markdown), _read__‐ [_dir_(3am)](https://www.chedong.com/phpMan.php/man/dir/3am/markdown), [_readfile_(3am)](https://www.chedong.com/phpMan.php/man/readfile/3am/markdown), [_revoutput_(3am)](https://www.chedong.com/phpMan.php/man/revoutput/3am/markdown), [_rwarray_(3am)](https://www.chedong.com/phpMan.php/man/rwarray/3am/markdown), [_time_(3am)](https://www.chedong.com/phpMan.php/man/time/3am/markdown). [_chdir_(2)](https://www.chedong.com/phpMan.php/man/chdir/2/markdown), [_fts_(3)](https://www.chedong.com/phpMan.php/man/fts/3/markdown), [_stat_(2)](https://www.chedong.com/phpMan.php/man/stat/2/markdown), [_statvfs_(2)](https://www.chedong.com/phpMan.php/man/statvfs/2/markdown). ## AUTHOR Arnold Robbins, ****. ## COPYING PERMISSIONS Copyright © 2012, 2013, 2018, 2019, 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 distrib‐ uted 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 no‐ tice may be stated in a translation approved by the Foundation. Free Software Foundation Feb 21 2018 [FILEFUNCS(3am)](https://www.chedong.com/phpMan.php/man/FILEFUNCS/3am/markdown)