*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> nftw (3)              



NAME    [Toc]    [Back]

       nftw - Walk a file tree

SYNOPSIS    [Toc]    [Back]

       #include <ftw.h>

       int nftw(
               const char *path,
               int (*function)(const char *, const struct stat *,
       int, struct FTW *),
               int depth,
               int flags );

       The following definition of the nftw() function  does  not
       conform  to  current  standards  and is supported only for
       backward compatibility:

       int nftw(
               const char *path,
               int (*function)(const char *, const struct stat *,
       int, struct FTW),
               int depth,
               int flags );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       nftw():  XSH5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Specifies  the directory hierarchy to be searched.  Specifies
 the function to be invoked for  each  object  in  the
       directory  hierarchy.   Limits the directory depth for the
       search. At most one file descriptor will be used for  each
       directory level.

              In  the backward-compatible version of nftw(), this
              parameter can be supplied but is not used.   Specifies
  optional options that modify the operation of
              the nftw() function.

DESCRIPTION    [Toc]    [Back]

       The nftw() function  recursively  searches  the  directory
       hierarchy  that  descends  from the directory specified by
       the path parameter.  The nftw() function performs the same
       operations  as  ftw(),  except that it takes an additional
       argument options, which is a bitwise inclusive-OR of  zero
       or  more  of the following options: If set, nftw() changes
       the current working directory  to  each  directory  as  it
       reports files in that directory. If clear, nftw() does not
       change the current  working  directory.   If  set,  nftw()
       reports  all  files  in  a  directory before reporting the
       directory itself. If clear, nftw() reports  any  directory
       before  reporting files in that directory.  If set, nftw()
       reports only files in the same file  system  as  path.  If
       clear,  nftw()  reports  all  files encountered during the
       walk.  If set, nftw() performs a physical  walk  and  does
       not  follow symbolic links. If clear, nftw() follows links
       instead of reporting them, and does not  report  the  same
       file twice.

       The nftw() function calls the function parameter with four
       arguments at each file and directory. The  first  argument
       is  the pathname of the object. The second argument points
       to the stat buffer containing information on  the  object.
       The  third argument is an integer that identifies the file
       type or condition of the object. The value of the  integer
       is  one  of  the following: A directory.  A directory that
       cannot be read. When nftw() reports this condition,  function
 is not called for any of the directory's descendants.
       A directory whose subdirectories have been visited.  (This
       condition  occurs only if the FTW_DEPTH option is included
       in flags.)  A regular  file.   An  object  for  which  the
       stat() function failed because of lack of appropriate permission.
 The content of the stat() buffer passed to  function
  is meaningless. Failure of nftw() for any other reason
 is considered an error and results in a  return  value
       of  -l.   A  symbolic link. (This condition occurs only if
       the FTW_PHYS option is included  in  flags.)   A  symbolic
       link  that  names  a  non-existent  file.  (This condition
       occurs only if the FTW_PHYS  option  is  not  included  in

              In  the  backward-compatible  version  of nftw, the
              FTW_SLN value is not used.

       The fourth argument to function is a  pointer  to  an  FTW

       In  the  backward-compatible version of nftw(), the fourth
       argument is an FTW structure rather than a pointer to one.

       The FTW structure includes the following members:

       int base; int level;

       The  value  of base is the offset into the pathname of the
       object. This pathname is passed as the first  argument  to
       the  function  parameter. The value of level specifies the
       depth relative to the root of the  walk,  where  the  root
       level has a value of 0 (zero).

NOTES    [Toc]    [Back]

       [Tru64  UNIX]  When  compiled  in the X/Open UNIX environment,
 calls to the nftw() function are internally  renamed
       by  prepending  _E  to the function name. When debugging a
       module that includes the nftw()  function  and  for  which
       _XOPEN_SOURCE_EXTENDED  has  been  defined,  use _Enftw to
       refer to the nftw() call. See standards(5) for information
       on when the _XOPEN_SOURCE_EXTENDED macro is defined.

       [Tru64  UNIX]  The  nftw()  function  is  reentrant;  care
       should be taken to ensure that the  function  supplied  as
       argument function is also reentrant.

RETURN VALUES    [Toc]    [Back]

       If  the directory hierarchy is completed, the nftw() function
 returns a value of 0 (zero).

       If  the  function  specified  by  the  function  parameter
       returns  a  nonzero  value,  the nftw() function stops the
       search and returns the value  that  was  returned  by  the

       If  the  nftw() function detects an error other than [EACCES],
 a value of -1 is returned, and errno is set to indicate
 the error.

ERRORS    [Toc]    [Back]

       If  any  of  the  following  conditions occurs, the nftw()
       function sets errno to the value that corresponds  to  the
       condition.   Search permission is denied for any component
       of the path parameter or read permission is denied for the
       path  parameter, or function returns -1 and does not reset
       errno.  The length of the path string exceeds PATH_MAX, or
       a   pathname  component  is  longer  than  NAME_MAX  while
       _POSIX_NO_TRUNC is in effect.

              Pathname resolution of a symbolic link produced  an
              intermediate  result whose length exceeds PATH_MAX.
              The path parameter points to the  name  of  a  file
              that  does  not exist or points to an empty string.
              A component of the path parameter is not  a  directory.
   [Tru64  UNIX]  There is insufficient memory
              for this operation.

       In addition, if the function pointed to  by  the  function
       parameter  encounters  an  error, errno may be set accordingly.

SEE ALSO    [Toc]    [Back]

       Functions: stat(2), ftw(3)

       Standards: standards(5)

[ Back ]
 Similar pages
Name OS Title
ftw Linux file tree walk
ftw OpenBSD traverse (walk) a file tree
nftw OpenBSD traverse (walk) a file tree
find OpenBSD walk a file hierarchy
find FreeBSD walk a file hierarchy
DXmSvnSetTreePosition Tru64 Sets the position of the tree in tree display mode.
ftw Tru64 Walks a file tree
dtfilsys HP-UX CDE file system; directory tree structure
tlink IRIX clone a file tree using symbolic links
mount_nullfs FreeBSD mount a loopback file system sub-tree; demonstrate the use of a null file system layer
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service