# man > filefuncs(3am)

---
type: CommandReference
command: filefuncs
mode: man
section: 3am
source: man-pages
---

## Quick Reference

- `@load "filefuncs"` — load the extension
- `chdir("/some/directory")` — change current directory, returns 0 on success, -1 on error (sets ERRNO)
- `stat("/some/path", statdata [, follow])` — get file stats via lstat (default) or stat (if follow given), returns 0 on success, fills statdata array
- `fts(pathlist, flags, filedata)` — traverse file hierarchies, returns 0 on success, fills filedata array
- `statvfs("/some/path", fsdata)` — get filesystem stats, returns 0 on success, fills fsdata array

## 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)
## Options

### `chdir(directory)`

Change directory. Returns 0 upon success, or less than zero upon error (updates `ERRNO`).

### `stat(path, statdata [, follow])`

Hook into `stat(2)` / `lstat(2)`. Returns 0 on success, -1 on error (updates `ERRNO`).  
Clears `statdata` array and fills it with keys:

- `"name"` — the file name (equal to first argument)
- `"dev"` — st_dev field
- `"ino"` — st_ino field
- `"mode"` — st_mode field
- `"nlink"` — st_nlink field
- `"uid"` — st_uid field
- `"gid"` — st_gid field
- `"size"` — st_size field
- `"atime"` — st_atime field
- `"mtime"` — st_mtime field
- `"ctime"` — st_ctime field
- `"rdev"` — st_rdev (only for device files)
- `"major"` — st_major (only for device files)
- `"minor"` — st_minor (only for device files)
- `"blksize"` — st_blksize (if present on system)
- `"pmode"` — human-readable mode string (e.g., `"-rwxr-xr-x"`)
- `"linkval"` — if symbolic link, the target path
- `"type"` — file type string: `"file"`, `"blockdev"`, `"chardev"`, `"directory"`, `"socket"`, `"fifo"`, `"symlink"`, `"door"`, or `"unknown"`

### `fts(pathlist, flags, filedata)`

Hook into `fts(3)` routines for traversing file hierarchies.  
Returns 0 on success, -1 on error (updates `ERRNO`).

Arguments:
- `pathlist` — array of filenames (values used, indices ignored)
- `flags` — bitwise OR of the following constants (at least `FTS_LOGICAL` or `FTS_PHYSICAL` required):
  - `FTS_LOGICAL` — logical traversal (follow symlinks)
  - `FTS_PHYSICAL` — physical traversal (do not follow symlinks)
  - `FTS_NOCHDIR` — disable directory change optimization
  - `FTS_COMFOLLOW` — immediately follow symlinks named in pathlist
  - `FTS_SEEDOT` — include entries for `".."` (`.` always included)
  - `FTS_XDEV` — do not cross filesystem boundaries
  - `FTS_SKIP` — do not descend into top-level directories
- `filedata` — cleared first, then filled with multi-dimensional array:
  - For each element in `pathlist`, a sub-array indexed by the path name.
  - If the path is a file, the sub-array contains:
    - `"path"` — full path
    - `"stat"` — array with same structure as `statdata` (may be absent if `stat(2)` failed)
    - `"error"` — string describing error (if any)
  - If the path is a directory, the sub-array contains one element per entry; subdirectories are recursively nested arrays. Additionally, `"."` is an array with `"path"`, `"stat"`, and `"error"`. If `FTS_SEEDOT` is set, `".."` is also present with `stat` data.

### `statvfs(path, fsdata)`

Hook into `statvfs(2)`. Returns 0 on success, -1 on error (updates `ERRNO`).  
Clears `fsdata` array and fills with keys:

- `"bsize"` — bsize member
- `"frsize"` — f_frsize member
- `"blocks"` — f_blocks member
- `"bfree"` — f_bfree member
- `"bavail"` — f_bavail member
- `"files"` — f_files member
- `"ffree"` — f_ffree member
- `"favail"` — f_favail member
- `"fsid"` — f_fsid (not available on all systems)
- `"flag"` — f_flag member
- `"namemax"` — f_namemax member

## Examples

See `test/fts.awk` in the gawk distribution for an example.

## See Also

- `chdir(2)`, `fts(3)`, `stat(2)`, `statvfs(2)`
- `fnmatch(3am)`, `fork(3am)`, `inplace(3am)`, `ordchr(3am)`, `readdir(3am)`, `readfile(3am)`, `revoutput(3am)`, `rwarray(3am)`, `time(3am)`
- _GAWK: Effective AWK Programming_