---
name: "nftw"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/ftw"
---

# nftw(3)

traverse (walk) a file tree

Part of [ftw(3)](/ftw/3.md).

## NAME

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

## SYNOPSIS

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

*int*\

**ftw**(*const char \*path*, *int \*fnconst char \*, const struct stat \*, int*, *int maxfds*);

*int*\

**nftw**(*const char \*path*, *int \*fnconst char \*, const struct stat \*, int, struct FTW \**, *int maxfds*, *int flags*);

## DESCRIPTION

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 aNUL -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 *maxfds* 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, do not 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.

## EXAMPLES

Following there is an example that shows how **nftw** can be used. It traverses the file tree starting at the directory pointed by the only program argument and shows the complete path and a brief indicator about the file type.

```
#include <ftw.h>
#include <stdio.h>
#include <sysexits.h>
int
nftw_callback(const char *path, const struct stat *sb, int typeflag, struct FTW *ftw)
{
	char type;
	switch(typeflag) {
	case FTW_F:
		type = 'F';
		break;
	case FTW_D:
		type = 'D';
		break;
	case FTW_DNR:
		type = '-';
		break;
	case FTW_DP:
		type = 'd';
		break;
	case FTW_NS:
		type = 'X';
		break;
	case FTW_SL:
		type = 'S';
		break;
	case FTW_SLN:
		type = 's';
		break;
	default:
		type = '?';
		break;
	}
	printf("[%c] %s\n", type, path);
	return (0);
}
int
main(int argc, char **argv)
{
	if (argc != 2) {
		printf("Usage %s <directory>\n", argv[0]);
		return (EX_USAGE);
	} else
		return (nftw(argv[1], nftw_callback, /* UNUSED */ 1, 0));
}
```

## 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 *maxfds* argument is less than 1.

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

## STANDARDS

The **ftw**() and **nftw**() functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).

## HISTORY

These functions first appeared in AT&T System V Release 3 UNIX. Their first FreeBSD appearance was in FreeBSD 5.3.

## BUGS

The *maxfds* argument is currently ignored.