---
name: "ftw"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/ftw"
---

# ftw(3)

traverse (walk) a file tree

## NAME

**ftw,** **nftw** – traverse (walk) a file tree

## SYNOPSIS

**#include \<ftw.h\>**

*int*\

**ftw**(*const char \*path*, *int (\*fn)(const char \*, const struct stat \*ptr, int flag)*, *int depth*);

*int*\

**nftw**(*const char \*path*, *int (\*fn)(const char \*, const struct stat \*ptr,      int flag, struct FTW \*)*, *int depth*, *int flags*);

## DESCRIPTION

These functions are provided for compatibility with legacy code. New code should use the [fts(3)](/fts/3.md) functions.

The **ftw**() and **nftw**() functions traverse (walk) the directory hierarchy rooted in *path*. For each object in the hierarchy, these functions call the function pointed to by *fn*. The **ftw**() function passes this function a pointer to a NUL-terminated string containing the name of the object, a pointer to a stat structure corresponding to the object, and an integer flag. The **nftw**() function passes the aforementioned arguments plus a pointer to a FTW structure as defined by ⟨*ftw.h*⟩ (shown below):

```
struct FTW {
    int base;	/* offset of basename into pathname */
    int level;	/* directory depth relative to starting point */
};
```

Possible values for the flag passed to *fn* are:

- FTW\_F

  A regular file.

- FTW\_D

  A directory being visited in pre-order.

- FTW\_DNR

  A directory which cannot be read. The directory will not be descended into.

- FTW\_DP

  A directory being visited in post-order (**nftw**() only).

- FTW\_NS

  A file for which no [stat(2)](/stat/2.md) information was available. The contents of the stat structure are undefined.

- FTW\_SL

  A symbolic link.

- FTW\_SLN

  A symbolic link with a non-existent target (**nftw**() only).

The **ftw**() function traverses the tree in pre-order. That is, it processes the directory before the directory's contents.

The *depth* argument specifies the maximum number of file descriptors to keep open while traversing the tree. It has no effect in this implementation.

The **nftw**() function has an additional *flags* argument with the following possible values:

- FTW\_PHYS

  Physical walk, don't follow symbolic links.

- FTW\_MOUNT

  The walk will not cross a mount point.

- FTW\_DEPTH

  Process directories in post-order. Contents of a directory are visited before the directory itself. By default, **nftw**() traverses the tree in pre-order.

- FTW\_CHDIR

  Change to a directory before reading it. By default, **nftw**() will change its starting directory. The current working directory will be restored to its original value before **nftw**() returns.

## RETURN VALUES

If the tree was traversed successfully, the **ftw**() and **nftw**() functions return 0. If the function pointed to by *fn* returns a non-zero value, **ftw**() and **nftw**() will stop processing the tree and return the value from *fn*. Both functions return -1 if an error is detected.

## ERRORS

The **ftw**() and **nftw**() functions may fail and set *errno* for any of the errors specified for the library functions [close(2)](/close/2.md), [open(2)](/open/2.md), [stat(2)](/stat/2.md), [malloc(3)](/malloc/3.md), [opendir(3)](/opendir/3.md) and [readdir(3)](/readdir/3.md). If the FTW\_CHDIR flag is set, the **nftw**() function may fail and set *errno* for any of the errors specified for [chdir(2)](/chdir/2.md). In addition, either function may fail and set *errno* as follows:

- \[EINVAL\]

  The *depth* argument is less than 1 or greater than OPEN\_MAX.

## LEGACY ERRORS

The **ftw**() and **nftw**() functions are far more tolerant of symlink cycles and are lax in reporting errors while accessing the initial path.  When **nftw**() is passed FTW\_MOUNT, it will pass the mount point to the callback function.

## SEE ALSO

[chdir(2)](/chdir/2.md), [close(2)](/close/2.md), [open(2)](/open/2.md), [stat(2)](/stat/2.md), [fts(3)](/fts/3.md), [malloc(3)](/malloc/3.md), [opendir(3)](/opendir/3.md), [readdir(3)](/readdir/3.md), [compat(5)](/compat/5.md)

## STANDARDS

The **ftw**() and **nftw**() functions conform to IEEE Std 1003.1-2001 (“POSIX.1”) Version 3 of the Single UNIX Specification (“SUSv3”).

## HISTORY

Prior to MacOS X 10.4  **ftw** did not follow symlinks.

## BUGS

The *depth* argument is currently ignored.