FTW(3)                     POSIX Programmer's Manual                    FTW(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       ftw -- traverse (walk) a file tree

SSYYNNOOPPSSIISS
       #include <ftw.h>

       int ftw(const char *_p_a_t_h, int (*_f_n)(const char *,
           const struct stat *_p_t_r, int _f_l_a_g), int _n_d_i_r_s);

DDEESSCCRRIIPPTTIIOONN
       The _f_t_w() function shall recursively descend the directory hierarchy
       rooted in _p_a_t_h.  For each object in the hierarchy, _f_t_w() shall call the
       function pointed to by _f_n, passing it a pointer to a null-terminated
       character string containing the name of the object, a pointer to a ssttaatt
       structure containing information about the object, filled in as if
       _s_t_a_t() or _l_s_t_a_t() had been called to retrieve the information. Possible
       values of the integer, defined in the _<_f_t_w_._h_> header, are:

       FTW_D     For a directory.

       FTW_DNR   For a directory that cannot be read.

       FTW_F     For a non-directory file.

       FTW_SL    For a symbolic link (but see also FTW_NS below).

       FTW_NS    For an object other than a symbolic link on which _s_t_a_t()
                 could not successfully be executed. If the object is a
                 symbolic link and _s_t_a_t() failed, it is unspecified whether
                 _f_t_w() passes FTW_SL or FTW_NS to the user-supplied function.

       If the integer is FTW_DNR, descendants of that directory shall not be
       processed. If the integer is FTW_NS, the ssttaatt structure contains
       undefined values. An example of an object that would cause FTW_NS to be
       passed to the function pointed to by _f_n would be a file in a directory
       with read but without execute (search) permission.

       The _f_t_w() function shall visit a directory before visiting any of its
       descendants.

       The _f_t_w() function shall use at most one file descriptor for each level
       in the tree.

       The argument _n_d_i_r_s should be in the range [1,{OPEN_MAX}].

       The tree traversal shall continue until either the tree is exhausted,
       an invocation of _f_n returns a non-zero value, or some error, other than
       [[EEAACCCCEESS]], is detected within _f_t_w().

       The _n_d_i_r_s argument shall specify the maximum number of directory
       streams or file descriptors or both available for use by _f_t_w() while
       traversing the tree. When _f_t_w() returns it shall close any directory
       streams and file descriptors it uses not counting any opened by the
       application-supplied _f_n function.

       The results are unspecified if the application-supplied _f_n function
       does not preserve the current working directory.

       The _f_t_w() function need not be thread-safe.

RREETTUURRNN VVAALLUUEE
       If the tree is exhausted, _f_t_w() shall return 0. If the function pointed
       to by _f_n returns a non-zero value, _f_t_w() shall stop its tree traversal
       and return whatever value was returned by the function pointed to by
       _f_n.  If _f_t_w() detects an error, it shall return -1 and set _e_r_r_n_o to
       indicate the error.

       If _f_t_w() encounters an error other than [[EEAACCCCEESS]] (see FTW_DNR and
       FTW_NS above), it shall return -1 and set _e_r_r_n_o to indicate the error.
       The external variable _e_r_r_n_o may contain any error value that is
       possible when a directory is opened or when one of the _s_t_a_t functions
       is executed on a directory or file.

EERRRROORRSS
       The _f_t_w() function shall fail if:

       EEAACCCCEESS Search permission is denied for any component of _p_a_t_h or read
              permission is denied for _p_a_t_h.

       EELLOOOOPP  A loop exists in symbolic links encountered during resolution of
              the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a component of a pathname is longer than
              {NAME_MAX}.

       EENNOOEENNTT A component of _p_a_t_h does not name an existing file or _p_a_t_h is an
              empty string.

       EENNOOTTDDIIRR
              A component of _p_a_t_h names an existing file that is neither a
              directory nor a symbolic link to a directory.

       EEOOVVEERRFFLLOOWW
              A field in the ssttaatt structure cannot be represented correctly in
              the current programming environment for one or more files found
              in the file hierarchy.

       The _f_t_w() function may fail if:

       EEIINNVVAALL The value of the _n_d_i_r_s argument is invalid.

       EELLOOOOPP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a pathname exceeds {PATH_MAX}, or pathname
              resolution of a symbolic link produced an intermediate result
              with a length that exceeds {PATH_MAX}.

       In addition, if the function pointed to by _f_n encounters system errors,
       _e_r_r_n_o may be set accordingly.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   WWaallkkiinngg aa DDiirreeccttoorryy SSttrruuccttuurree
       The following example walks the current directory structure, calling
       the _f_n function for every directory entry, using at most 10 file
       descriptors:


           #include <ftw.h>
           ...
           if (ftw(".", fn, 10) != 0) {
               perror("ftw"); exit(2);
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _f_t_w() function may allocate dynamic storage during its operation.
       If _f_t_w() is forcibly terminated, such as by _l_o_n_g_j_m_p() or _s_i_g_l_o_n_g_j_m_p()
       being executed by the function pointed to by _f_n or an interrupt
       routine, _f_t_w() does not 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 the
       function pointed to by _f_n return a non-zero value at its next
       invocation.

       Applications should use the _n_f_t_w() function instead of the obsolescent
       _f_t_w() function.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       The _f_t_w() function may be removed in a future version.

SSEEEE AALLSSOO
       _f_d_o_p_e_n_d_i_r(), _f_s_t_a_t_a_t(), _l_o_n_g_j_m_p(), _n_f_t_w(), _s_i_g_l_o_n_g_j_m_p()

       The Base Definitions volume of POSIX.1-2017, <<ffttww..hh>>, <<ssyyss__ssttaatt..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                               FTW(3)
