FILEFUNCS(3am)

📦
version 5.4.1 · 2 versions
, in arch rolling, nixos 26.05, nixpkgs unstable

💖 FILEFUNCS 💖

okay bestie, gather round, because this little page comes straight out of the GNU Awk Extension Modules manual (section 3am, iykyk) and it's giving file functionality for your gawk scripts. let's go 🫶

🌸 NAME 🌸

filefuncs — it provides some file related functionality to gawk. that's the whole vibe. ✨

🦋 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 give you access to file-related facilities. she's useful, she's iconic, she's loaded with @load. 💅

🎀 chdir() 🎀

The chdir() function is a direct hook into the chdir(2) system call, and its entire job is changing the current directory.

It returns zero on success, or less than zero on error. In the error case, it updates ERRNO. no cap. 😭

🦋 stat() 🦋

The stat() function is a hook into the stat(2) system call.

  • returns zero on success
  • returns less than zero on error, and in that case it updates ERRNO

By default, it uses lstat(2). However, if you pass it a third argument, it uses stat(2) instead. slay.

In all cases, it clears the statdata array. When the call succeeds, stat() fills statdata with information retrieved from the filesystem, like this:

  • 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. 🚨 also only present for device files.
  • statdata["minor"] — corresponds to the st_minor field in the struct stat. 🚨 again, only present for device files.
  • statdata["blksize"] — corresponds to the st_blksize field in the struct stat, if that 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, so vibe check your platform first. 🌈

🌳 fts() 🌳

The fts() function hooks into the fts(3) set of routines for traversing file hierarchies. instead of handing you data about one file at a time in a stream, it fills in a multi-dimensional array with data about every file and directory it encounters in the requested hierarchies. it's giving main character energy, honestly.

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 hierarchy. this flag disables that optimization.
    • FTS_COMFOLLOW — immediately 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.
    • 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 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. 💀

💾 statvfs() 💾

The statvfs() function provides a hook into the statvfs(2) system call — on systems that supply this system call, anyway. she's exclusive. 💅

It returns zero on success, or less than zero on error. in the error 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) routines. instead it chose to provide an interface 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. 💅

and while an fts_read()-like interface could have been provided, that felt less natural than simply creating a multi-dimensional array to represent the file hierarchy and its information. the vibes said: array. ✨

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(). 🚨 so like, don't.

💀 BUGS 💀

  • There are many more file-related functions for which AWK interfaces would be desirable. so many. 😭
  • 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. go look, it's cute. 🫶

👀 SEE ALSO 👀

  • GAWK: Effective AWK Programming, and the man pages for the other extensions shipped with gawk.
  • chdir(2), fts(3), stat(2), statvfs(2).

👑 AUTHOR 👑

Arnold Robbins, arnold@skeeve.com.

🎀 COPYING PERMISSIONS 🎀

Copyright © 2012, 2013, 2018, 2019, 2026, 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.

and that's the whole page, bestie!! 💖✨🎀 brought to you by the Free Software Foundation, dated Feb 25 2026, living in section FILEFUNCS(3am). read it, love it, @load it. mwah. 💅🦋🌸

📦 where this page comes from