{ "mode": "man", "parameter": "filefuncs", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/filefuncs/3am/json", "generated": "2026-05-30T06:06:53Z", "synopsis": "@load \"filefuncs\"\nresult = chdir(\"/some/directory\")\nresult = stat(\"/some/path\", statdata [, follow])\nflags = or(FTSPHYSICAL, ...)\nresult = fts(pathlist, flags, filedata)\nresult = statvfs(\"/some/path\", fsdata)", "sections": { "NAME": { "content": "filefuncs - provide some file related functionality to gawk\n", "subsections": [] }, "SYNOPSIS": { "content": "@load \"filefuncs\"\n\nresult = chdir(\"/some/directory\")\n\nresult = stat(\"/some/path\", statdata [, follow])\n\nflags = or(FTSPHYSICAL, ...)\nresult = fts(pathlist, flags, filedata)\n\nresult = statvfs(\"/some/path\", fsdata)\n", "subsections": [] }, "DESCRIPTION": { "content": "The filefuncs extension adds several functions that provide access to file-related facili‐\nties.\n", "subsections": [ { "name": "chdir()", "content": "The chdir() function is a direct hook to the chdir(2) system call to change the current di‐\nrectory. It returns zero upon success or less than zero upon error. In the latter case it\nupdates ERRNO.\n" }, { "name": "stat()", "content": "The stat() function provides a hook into the stat(2) system call. It returns zero upon suc‐\ncess or less than zero upon error. In the latter case it updates ERRNO. By default, it uses\nlstat(2). However, if passed a third argument, it uses stat(2), instead.\n\nIn all cases, it clears the statdata array. When the call is successful, stat() fills the\nstatdata array with information retrieved from the filesystem, as follows:\n" }, { "name": "statdata[\"name\"]", "content": "The name of the file, equal to the first argument passed to stat().\n" }, { "name": "statdata[\"dev\"]", "content": "Corresponds to the stdev field in the struct stat.\n" }, { "name": "statdata[\"ino\"]", "content": "Corresponds to the stino field in the struct stat.\n" }, { "name": "statdata[\"mode\"]", "content": "Corresponds to the stmode field in the struct stat.\n" }, { "name": "statdata[\"nlink\"]", "content": "Corresponds to the stnlink field in the struct stat.\n" }, { "name": "statdata[\"uid\"]", "content": "Corresponds to the stuid field in the struct stat.\n" }, { "name": "statdata[\"gid\"]", "content": "Corresponds to the stgid field in the struct stat.\n" }, { "name": "statdata[\"size\"]", "content": "Corresponds to the stsize field in the struct stat.\n" }, { "name": "statdata[\"atime\"]", "content": "Corresponds to the statime field in the struct stat.\n" }, { "name": "statdata[\"mtime\"]", "content": "Corresponds to the stmtime field in the struct stat.\n" }, { "name": "statdata[\"ctime\"]", "content": "Corresponds to the stctime field in the struct stat.\n" }, { "name": "statdata[\"rdev\"]", "content": "Corresponds to the strdev field in the struct stat. This element is only present for\ndevice files.\n" }, { "name": "statdata[\"major\"]", "content": "Corresponds to the stmajor field in the struct stat. This element is only present\nfor device files.\n" }, { "name": "statdata[\"minor\"]", "content": "Corresponds to the stminor field in the struct stat. This element is only present\nfor device files.\n" }, { "name": "statdata[\"blksize\"]", "content": "Corresponds to the stblksize field in the struct stat, if this field is present on\nyour system. (It is present on all modern systems that we know of.)\n" }, { "name": "statdata[\"pmode\"]", "content": "A human-readable version of the mode value, such as printed by ls(1). For example,\n\"-rwxr-xr-x\".\n" }, { "name": "statdata[\"linkval\"]", "content": "If the named file is a symbolic link, this element will exist and its value is the\nvalue of the symbolic link (where the symbolic link points to).\n" }, { "name": "statdata[\"type\"]", "content": "The type of the file as a string. One of \"file\", \"blockdev\", \"chardev\", \"directory\",\n\"socket\", \"fifo\", \"symlink\", \"door\", or \"unknown\". Not all systems support all file\ntypes.\n" }, { "name": "fts()", "content": "The fts() function provides a hook to the fts(3) set of routines for traversing file hierar‐\nchies. Instead of returning data about one file at a time in a stream, it fills in a multi-\ndimensional array with data about each file and directory encountered in the requested hier‐\narchies.\n\nThe arguments are as follows:\n" }, { "name": "pathlist", "content": "An array of filenames. The element values are used; the index values are ignored.\n\nflags This should be the bitwise OR of one or more of the following predefined flag values.\nAt least one of FTSLOGICAL or FTSPHYSICAL must be provided; otherwise fts() returns\nan error value and sets ERRNO.\n\nFTSLOGICAL\nDo a ``logical'' file traversal, where the information returned for a symbolic\nlink refers to the linked-to file, and not to the symbolic link itself. This\nflag is mutually exclusive with FTSPHYSICAL.\n\nFTSPHYSICAL\nDo a ``physical'' file traversal, where the information returned for a symbolic\nlink refers to the symbolic link itself. This flag is mutually exclusive with\nFTSLOGICAL.\n\nFTSNOCHDIR\nAs a performance optimization, the fts(3) routines change directory as they\ntraverse a file hierarchy. This flag disables that optimization.\n\nFTSCOMFOLLOW\nImmediately follow a symbolic link named in pathlist, whether or not FTSLOGI‐‐\nCAL is set.\n\nFTSSEEDOT\nBy default, the fts(3) routines do not return entries for ``.'' and ``..''.\nThis option causes entries for ``..'' to also be included. (The AWK extension\nalways includes an entry for ``.'', see below.)\n\nFTSXDEV\nDuring a traversal, do not cross onto a different mounted filesystem.\n\nFTSSKIP\nWhen set, causes top level directories to not be descended into.\n" }, { "name": "filedata", "content": "The filedata array is first cleared. Then, fts() creates an element in filedata for\nevery element in pathlist. The index is the name of the directory or file given in\npathlist. The element for this index is itself an array. There are two cases.\n\nThe path is a file.\nIn this case, the array contains two or three elements:\n\n\"path\" The full path to this file, starting from the ``root'' that was given in\nthe pathlist array.\n\n\"stat\" This element is itself an array, containing the same information as pro‐\nvided by the stat() function described earlier for its statdata argu‐\nment. The element may not be present if stat(2) for the file failed.\n\n\"error\"\nIf some kind of error was encountered, the array will also contain an\nelement named \"error\", which is a string describing the error.\n\nThe path is a directory.\nIn this case, the array contains one element for each entry in the directory.\nIf an entry is a file, that element is as for files, just described. If the\nentry is a directory, that element is (recursively), an array describing the\nsubdirectory. If FTSSEEDOT was provided in the flags, then there will also be\nan element named \"..\". This element will be an array containing the data as\nprovided by stat().\n\nIn addition, there will be an element whose index is \".\". This element is an\narray containing the same two or three elements as for a file: \"path\", \"stat\",\nand \"error\".\n\nThe fts() function returns 0 if there were no errors. Otherwise it returns -1.\n" }, { "name": "statvfs()", "content": "The statvfs() function provides a hook into the statvfs(2) system call on systems that supply\nthis system call. It returns zero upon success or less than zero upon error. In the latter\ncase it updates ERRNO.\n\nWhen the call is successful, statvfs() fills the fsdata array with information retrieved\nabout the filesystem, as follows:\n" }, { "name": "fsdata[\"bsize\"]", "content": "Corresponds to the bsize member in the struct statvfs.\n" }, { "name": "fsdata[\"frsize\"]", "content": "Corresponds to the ffrsize member in the struct statvfs.\n" }, { "name": "fsdata[\"blocks\"]", "content": "Corresponds to the fblocks member in the struct statvfs.\n" }, { "name": "fsdata[\"bfree\"]", "content": "Corresponds to the fbfree member in the struct statvfs.\n" }, { "name": "fsdata[\"bavail\"]", "content": "Corresponds to the fbavail member in the struct statvfs.\n" }, { "name": "fsdata[\"files\"]", "content": "Corresponds to the ffiles member in the struct statvfs.\n" }, { "name": "fsdata[\"ffree\"]", "content": "Corresponds to the fffree member in the struct statvfs.\n" }, { "name": "fsdata[\"favail\"]", "content": "Corresponds to the ffavail member in the struct statvfs.\n" }, { "name": "fsdata[\"fsid\"]", "content": "Corresponds to the ffsid member in the struct statvfs. This member is not available\non all systems.\n" }, { "name": "fsdata[\"flag\"]", "content": "Corresponds to the fflag member in the struct statvfs.\n" }, { "name": "fsdata[\"namemax\"]", "content": "Corresponds to the fnamemax member in the struct statvfs.\n" } ] }, "NOTES": { "content": "The AWK fts() extension does not exactly mimic the interface of the fts(3) routines, choosing\ninstead to provide an interface that is based on associative arrays, which should be more\ncomfortable to use from an AWK program. This includes the lack of a comparison function,\nsince gawk already provides powerful array sorting facilities. While an ftsread()-like in‐\nterface could have been provided, this felt less natural than simply creating a multi-dimen‐\nsional array to represent the file hierarchy and its information.\n\nNothing prevents AWK code from changing the predefined FTSxx values, but doing so may cause\nstrange results when the changed values are passed to fts().\n", "subsections": [] }, "BUGS": { "content": "There are many more file-related functions for which AWK interfaces would be desirable.\n\nIt's not clear why I thought adding FTSSKIP was a good idea.\n", "subsections": [] }, "EXAMPLE": { "content": "See test/fts.awk in the gawk distribution for an example.\n", "subsections": [] }, "SEE ALSO": { "content": "GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am), ordchr(3am), read‐\ndir(3am), readfile(3am), revoutput(3am), rwarray(3am), time(3am).\n\nchdir(2), fts(3), stat(2), statvfs(2).\n", "subsections": [] }, "AUTHOR": { "content": "Arnold Robbins, arnold@skeeve.com.\n", "subsections": [] }, "COPYING PERMISSIONS": { "content": "Copyright © 2012, 2013, 2018, 2019, Free Software Foundation, Inc.\n\nPermission is granted to make and distribute verbatim copies of this manual page provided the\ncopyright notice and this permission notice are preserved on all copies.\n\nPermission is granted to copy and distribute modified versions of this manual page under the\nconditions for verbatim copying, provided that the entire resulting derived work is distrib‐\nuted under the terms of a permission notice identical to this one.\n\nPermission is granted to copy and distribute translations of this manual page into another\nlanguage, under the above conditions for modified versions, except that this permission no‐\ntice may be stated in a translation approved by the Foundation.\n\n\n\nFree Software Foundation Feb 21 2018 FILEFUNCS(3am)", "subsections": [] } }, "summary": "filefuncs - provide some file related functionality to gawk", "flags": [], "examples": [ "See test/fts.awk in the gawk distribution for an example." ], "see_also": [ { "name": "fnmatch", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/fnmatch/3am/json" }, { "name": "fork", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/fork/3am/json" }, { "name": "inplace", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/inplace/3am/json" }, { "name": "ordchr", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/ordchr/3am/json" }, { "name": "dir", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/dir/3am/json" }, { "name": "readfile", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/readfile/3am/json" }, { "name": "revoutput", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/revoutput/3am/json" }, { "name": "rwarray", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/rwarray/3am/json" }, { "name": "time", "section": "3am", "url": "https://www.chedong.com/phpMan.php/man/time/3am/json" }, { "name": "chdir", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/chdir/2/json" }, { "name": "fts", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/fts/3/json" }, { "name": "stat", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/stat/2/json" }, { "name": "statvfs", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/statvfs/2/json" } ] }