nftw(), nftw64()

Обойти файловое дерево

Прототип:

#include <ftw.h>
                                       
int nftw( const char *path, 
         int (*fn)( const char *fname,
                    const struct stat *sbuf,
                    int flags, 
                    struct FTW *ftw ),
         int depth,
         int flags );

Аргументы:

path

The path of the directory whose file tree you want to walk.

fn

A pointer to a function that you want to call for each file.

depth

The maximum number of file descriptors that nftw() can use. The nftw() function uses one file descriptor for each level in the tree. If depth is zero or negative, the effect is the same as if it were 1. The depth must not be greater than the number of file descriptors currently available for use. The nftw() function is faster if depth is at least as large as the number of levels in the tree.

flags

The value of flags is constructed by the bitwise ORing of values from the following list, defined in the <ftw.h> header file.

FTW_CHDIR

If set, nftw() changes the current working directory to each directory as it reports files in that directory.

FTW_DEPTH

If set, nftw() reports all files in a directory before reporting the directory itself (otherwise the directory is reported before any file it contains).

FTW_MOUNT

If set, nftw() only reports files on the same filesystem as path.

FTW_PHYS

If set, nftw() performs a physical walk and doesn't follow any symbolic link.

Библиотека:

libc

Описание:

The nftw() function recursively descends the directory hierarchy identified by path. For each object in the hierarchy, nftw() calls the user-defined function fn(), passing to it:

• a pointer to a NULL-terminated character string containing the name of the object
• a pointer to a struct stat structure containing information about the object
• an integer. Possible values of the integer, defined in the <nftw.h> header, are:

  FTW_F

  The object is a file.

  FTW_D

  The object is a directory.

  FTW_DNR

  The object is a directory that can't be read. Descendents of the directory aren't processed.

  FTW_DP

  The object is a directory, and its contents have been reported. See the FTW_DEPTH flag above.

  FTW_NS

  The stat() failed on the object because the permissions weren't appropriate. The stat buffer passed to fn() is undefined.

  FTW_SL

  The object is a symbolic link. See the FTW_PHYS flag above.

  FTW_SLN

  The object is a symbolic link that does not name an existing file.

• a pointer to a struct FTW.

The tree traversal continues until the tree is exhausted, an invocation of fn() returns a nonzero value, or some error is detected within nftw() (such as an I/O error). If the tree is exhausted, nftw() returns zero. If fn() returns a nonzero value, nftw() stops its tree traversal and returns whatever value was returned by fn().

When nftw() returns, it closes any file descriptors it opened; it doesn't close any file descriptors that may have been opened by fn().

Возвращаемое значение:

0

Успешное завершение.

-1

Возникла ошибка (отличная от EACCESS). Код ошибки записан в errno.

Классификация:

nftw() — POSIX 1003.1 XSI; nftw64() — Поддержка больших файлов

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Да

В потоке

Да

Предостережения:

Because nftw() is recursive, it might terminate with a memory fault when applied to very deep file structures.

This function uses malloc() to allocate dynamic storage during its operation. If nftw() is forcibly terminated, for example if longjmp() longjmp() is executed by fn() or an interrupt routine, nftw() doesn't have a chance to free that storage, so it remains permanently allocated. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have fn() return a nonzero value at its next invocation.

Тематические ссылки:

struct stat, struct FTW, ftw(), longjmp(), malloc(), stat()

Предыдущий раздел: Описание API системной библиотеки