
FTS(3)                     UNIX Programmer's Manual                     FTS(3)

NNAAMMEE
     ffttss - traverse a file hierarchy

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
     ##iinncclluuddee <<ssyyss//ssttaatt..hh>>
     ##iinncclluuddee <<ffttss..hh>>

     _F_T_S _*
     ffttss__ooppeenn(_c_h_a_r _* _c_o_n_s_t _*_p_a_t_h___a_r_g_v, _i_n_t _o_p_t_i_o_n_s,
             _i_n_t _*_c_o_m_p_a_r_(_c_o_n_s_t _F_T_S_E_N_T _*_, _c_o_n_s_t _F_T_S_E_N_T _*_))

     _F_T_S_E_N_T _*
     ffttss__rreeaadd(_F_T_S _*_f_t_s_p)

     _F_T_S_E_N_T _*
     ffttss__cchhiillddrreenn(_F_T_S _*_f_t_s_p)

     _i_n_t
     ffttss__sseett(_F_T_S _f_t_s_p, _F_T_S_E_N_T _*_f, _i_n_t _o_p_t_i_o_n_s)

     _i_n_t
     ffttss__cclloossee(_F_T_S _*_f_t_s_p)

DDEESSCCRRIIPPTTIIOONN
     The ffttss functions are provided for traversing UNIX file hierarchies.

     The simple overview is that the ffttss__ooppeenn() function returns a ``handle''
     on a file hierarchy, which is supplied to the other ffttss functions to de-
     termine which hierarchy they operate on.  The function ffttss__rreeaadd() returns
     a pointer to a structure describing one of the files in the file hierar-
     chy.  The function ffttss__cchhiillddrreenn() returns a pointer to a linked list of
     structures, each of which describes one of the files contained in a di-
     rectory in the hierarchy.  In general, directories are visited two dis-
     tinguishable times; in pre-order (before any of their descendants are
     visited) and in post-order (after all of their descendants have been vis-
     ited).  Files are visited once.  It is possible to walk the hierarchy
     ``logically'' (ignoring symbolic links) or physically (visiting symbolic
     links), order the walk of the hierarchy or prune and/or re-visit portions
     of the hierarchy.

     Two structures are defined (and typedef'd) in the include file <_f_t_s_._h>.
     The first is _F_T_S, the structure that represents the file hierarchy
     stream.  The second is _F_T_S_E_N_T, the structure that represents a file in
     the file hierarchy.  Normally, an _F_T_S_E_N_T structure is returned for every
     file in the file hierarchy.  In this manual page, ``file'' and ``_F_T_S_E_N_T
     structure'' are generally interchangeable.  The _F_T_S_E_N_T structure contains
     at least the following fields, which are described in greater detail be-
     low:

     typedef struct _ftsent {
             u_short fts_info;               /* flags for FTSENT structure */
             char *fts_accpath;              /* access path */
             char *fts_path;                 /* root path */
             short fts_pathlen;              /* strlen(fts_path) */
             char *fts_name;                 /* file name */
             short fts_namelen;              /* strlen(fts_name) */
             short fts_level;                /* depth (-1 to N) */
             long fts_number;                /* local numeric value */
             void *fts_pointer;              /* local address value */
             struct ftsent *fts_parent;      /* parent directory */
             struct ftsent *fts_link;        /* cycle or next file structure */
             struct stat fts_statb;          /* stat(2) information */
     } FTSENT;

     These fields are defined as follows:

     _f_t_s___i_n_f_o     One of the following flags describing the returned _F_T_S_E_N_T
                  structure and the file it represents.  With the exception of
                  directories without errors (FTS_D), all of these entries are
                  terminal, that is, they will not be revisited, nor will any
                  of their descendants be visited.

                  FTS_D        A directory being visited in pre-order.

                  FTS_DC       A directory that causes a cycle in the tree.
                               (The _f_t_s___l_i_n_k field of the _F_T_S_E_N_T structure
                               will be filled in as well.)

                  FTS_DEFAULT  Any _F_T_S_E_N_T structure that represents a file
                               type not explicitly described by one of the
                               other _f_t_s___i_n_f_o values.

                  FTS_DNR      A directory which cannot be read.  An error re-
                               turn; the external variable _e_r_r_n_o will be set
                               to indicate the error.

                  FTS_DOT      A file named `.' or `..' which was not speci-
                               fied as a file name to ffttss__ooppeenn() (see
                               FTS_SEEDOT).

                  FTS_DP       A directory being visited in post-order.  The
                               contents of the _F_T_S_E_N_T structure will be un-
                               changed from when it was returned in pre-order,
                               i.e. with the _f_t_s___i_n_f_o field set to FTS_D.

                  FTS_ERR      An error return; the external variable _e_r_r_n_o
                               will be set to indicate the error.

                  FTS_F        A regular file.

                  FTS_NS       A file for which no stat(2) information was
                               available.  The contents of the _f_t_s___s_t_a_t_b field
                               are undefined.  An error return; the external
                               variable _e_r_r_n_o will be set to indicate the er-
                               ror.

                  FTS_NSOK     A file for which no stat(2) information was re-
                               quested.  The contents of the _f_t_s___s_t_a_t_b field
                               are undefined.

                  FTS_SL       A symbolic link.

                  FTS_SLNONE   A symbolic link with a non-existent target.
                               The contents of the _f_t_s___s_t_a_t_b field contain the
                               file characteristic information for the symbol-
                               ic link itself.

     _f_t_s___a_c_c_p_a_t_h  A path for accessing the file from the current directory.

     _f_t_s___p_a_t_h     The path for the file relative to the root of the traversal.
                  This path contains the path specified to ffttss__ooppeenn() as a
                  prefix.

     _f_t_s___p_a_t_h_l_e_n  The length of the string referenced by _f_t_s___p_a_t_h.



     _f_t_s___n_a_m_e     The name of the file.

     _f_t_s___n_a_m_e_l_e_n  The length of the string referenced by _f_t_s___n_a_m_e.

     _f_t_s___l_e_v_e_l    The depth of the traversal, numbered from -1 to N, where
                  this file was found.  The _F_T_S_E_N_T structure representing the
                  parent of the starting point (or root) of the traversal is
                  numbered -1, and the _F_T_S_E_N_T structure for the root itself is
                  numbered 0.

     _f_t_s___n_u_m_b_e_r   This field is provided for the use of the application pro-
                  gram and is not modified by the ffttss functions.  It is ini-
                  tialized to 0.  The fields _f_t_s___n_u_m_b_e_r and _f_t_s___p_o_i_n_t_e_r occupy
                  the same physical location; using both may cause undefined
                  results.

     _f_t_s___p_o_i_n_t_e_r  This field is provided for the use of the application pro-
                  gram and is not modified by the ffttss functions.  It is ini-
                  tialized to NULL. The fields _f_t_s___n_u_m_b_e_r and _f_t_s___p_o_i_n_t_e_r oc-
                  cupy the same physical location; using both may cause unde-
                  fined results.

     _f_t_s___p_a_r_e_n_t   A pointer to the _F_T_S_E_N_T structure referencing the file in
                  the hierarchy immediately above the current file, i.e. the
                  directory of which this file is a member.  A parent struc-
                  ture for the initial entry point is provided as well, howev-
                  er, only the _f_t_s___l_e_v_e_l, _f_t_s___n_u_m_b_e_r and _f_t_s___p_o_i_n_t_e_r fields
                  are guaranteed to be initialized.

     _f_t_s___l_i_n_k     The _f_t_s___l_i_n_k field has two separate uses.  If a directory
                  causes a cycle in the hierarchy (see FTS_DC), either because
                  of a hard link between two directories, or a symbolic link
                  pointing to a directory, the _f_t_s___l_i_n_k field of the structure
                  will point to the _F_T_S_E_N_T structure in the hierarchy that
                  references the same file as the current _F_T_S_E_N_T structure.
                  Also, upon return from the ffttss__cchhiillddrreenn() function, the
                  _f_t_s___l_i_n_k field points to the next structure in the linked
                  list of directory members.  Otherwise, the contents of the
                  _f_t_s___l_i_n_k field are undefined.

     _f_t_s___s_t_a_t_b    Stat(2) information for the file.

FFTTSS__OOPPEENN
     The ffttss__ooppeenn() function takes a pointer to an array of character pointers
     naming one or more paths which make up a logical file hierarchy to be
     traversed.  The array must be terminated by a NULL pointer.

     There are a number of options, at least one of which (either FTS_LOGICAL
     or FTS_PHYSICAL) must be specified.  The options are selected by _o_r'ing
     the following values:

     FTS_LOGICAL   This option causes the ffttss routines to return _F_T_S_E_N_T struc-
                   tures for the targets of symbolic links instead of the sym-
                   bolic links themselves.  If this option is set, the only
                   symbolic links for which _F_T_S_E_N_T structures are returned to
                   the application are those referencing non-existent files.
                   Either FTS_LOGICAL or FTS_PHYSICAL _m_u_s_t be provided to the
                   ffttss__ooppeenn() function.

     FTS_NOCHDIR   As a performance optimization, the ffttss functions change di-
                   rectories as they walk the file hierarchy.  This has the
                   side-effect that an application cannot rely on being in any
                   particular directory during the traversal.  The FTS_NOCHDIR
                   option turns off this optimization, and the ffttss functions
                   will not change the current directory.  Note that applica-
                   tions should not themselves change their current directory
                   and try to access files unless FTS_NOCHDIR is specified and
                   absolute pathnames were provided as arguments to
                   ffttss__ooppeenn().

     FTS_NOSTAT    By default, returned _F_T_S_E_N_T structures contain file charac-
                   teristic information (the _s_t_a_t_b field) for each file visit-
                   ed.  This option relaxes that requirement as a performance
                   optimization, allowing the ffttss functions to set the
                   _f_t_s___i_n_f_o field to FTS_NSOK and leave the contents of the
                   _s_t_a_t_b field undefined.

     FTS_PHYSICAL  This option causes the ffttss routines to return _F_T_S_E_N_T struc-
                   tures for symbolic links themselves instead of the target
                   files they point to.  If this option is set, _F_T_S_E_N_T struc-
                   tures for all symbolic links in the hierarchy are returned
                   to the application.  Either FTS_LOGICAL or FTS_PHYSICAL
                   _m_u_s_t be provided to the ffttss__ooppeenn() function.

     FTS_SEEDOT    By default, unless they are specified as path arguments to
                   ffttss__ooppeenn(), any files named `.' and `..' encountered in the
                   file hierarchy are ignored.  This option causes the ffttss
                   routines to return _F_T_S_E_N_T structures for them.

     FTS_XDEV      This option prevents ffttss from descending into directories
                   that have a different device number than the file from
                   which the descent began.

     The argument ccoommppaarr() specifies a user-defined function which may be used
     to order the traversal of the hierarchy.  It takes two pointers to point-
     ers to _F_T_S_E_N_T structures as arguments and should return a negative value,
     zero, or a positive value to indicate if the file referenced by its first
     argument comes before, in any order with respect to, or after, the file
     referenced by its second argument.  The _f_t_s___a_c_c_p_a_t_h, _f_t_s___p_a_t_h and
     _f_t_s___p_a_t_h_l_e_n fields of the _F_T_S_E_N_T structures may _n_e_v_e_r be used in this
     comparison.  If the _f_t_s___i_n_f_o field is set to FTS_NS or the _f_t_s___s_t_a_b field
     may not either.  If the ccoommppaarr() argument is NULL, the directory traver-
     sal order is unspecified except for the root paths which are traversed in
     the order listed in _p_a_t_h___a_r_g_v.

FFTTSS__RREEAADD
     The ffttss__rreeaadd() function returns a pointer to an _F_T_S_E_N_T structure describ-
     ing a file in the hierarchy.  Directories (that are readable and do not
     cause cycles) are visited at least twice, once in pre-order and once in
     post-order.  All other files are visited at least once.  (Hard links be-
     tween directories that do not cause cycles or symbolic links to symbolic
     links may cause files to be visited more than once, or directories more
     than twice.)

     If all the members of the hierarchy have been returned, ffttss__rreeaadd() re-
     turns NULL and sets the external variable _e_r_r_n_o to 0.  If an error unre-
     lated to a file in the hierarchy occurs, ffttss__rreeaadd() returns NULL and sets
     _e_r_r_n_o appropriately.  If an error related to a returned file occurs, a
     pointer to an _F_T_S_E_N_T structure is returned, and _e_r_r_n_o may or may not have
     been set (see _f_t_s___i_n_f_o).

     The _F_T_S_E_N_T structures returned by ffttss__rreeaadd() may be overwritten after a
     call to ffttss__cclloossee() on the same file hierarchy stream, or, after a call
     to ffttss__rreeaadd() on the same file hierarchy stream unless they represent a
     file of type directory, in which case they will not be overwritten until
     after a call to ffttss__rreeaadd() after the _F_T_S_E_N_T structure has been returned
     by the function ffttss__rreeaadd() in post-order.

FFTTSS__CCHHIILLDDRREENN
     The ffttss__cchhiillddrreenn() function returns a pointer to an _F_T_S_E_N_T structure de-
     scribing the first entry in a linked list of the files in the directory
     represented by the _F_T_S_E_N_T structure most recently returned by ffttss__rreeaadd().
     The list is linked through the _f_t_s___l_i_n_k field of the _F_T_S_E_N_T structure,
     and is ordered by the user-specified comparison function, if any.  Re-
     peated calls to ffttss__cchhiillddrreenn() will recreate this linked list.

     If the _F_T_S_E_N_T structure most recently returned by ffttss__rreeaadd() is not a di-
     rectory being visited in pre-order, or the directory does not contain any
     files, ffttss__cchhiillddrreenn() returns NULL and sets _e_r_r_n_o to zero.  If an error
     occurs, ffttss__cchhiillddrreenn() returns NULL and sets _e_r_r_n_o appropriately.

     The _F_T_S_E_N_T structures returned by ffttss__cchhiillddrreenn() may be overwritten after
     a call to ffttss__cclloossee() on the same file hierarchy stream, or after a call
     to ffttss__cchhiillddrreenn() or ffttss__rreeaadd() on the same file hierarchy stream.

     A single buffer is used for all of the paths of all of the files in the
     file hierarchy.  Therefore, the _f_t_s___p_a_t_h and _f_t_s___a_c_c_p_a_t_h fields are guar-
     anteed to be NULL-terminated _o_n_l_y for the file most recently returned by
     ffttss__rreeaadd().  To use these fields to reference any files represented by
     other _F_T_S_E_N_T structures will require that the path buffer be modified us-
     ing the information contained in that _F_T_S_E_N_T structure's _f_t_s___p_a_t_h_l_e_n
     field.  Any such modifications should be undone before further calls to
     ffttss__rreeaadd() are attempted.  The _f_t_s___n_a_m_e field is always NULL-terminated.

FFTTSS__SSEETT
     The function ffttss__sseett() allows the user application to determine further
     processing for the file _f of the stream _f_t_s_p. The ffttss__sseett() function re-
     turns 0 on success, and -1 if an error occurs.  _O_p_t_i_o_n must be set to one
     of the following values:

     FTS_AGAIN     Re-visit the file; any file type may be re-visited.  The
                   next call to ffttss__rreeaadd() will return the referenced file.
                   The _f_t_s___s_t_a_t and _f_t_s___i_n_f_o fields of the structure will be
                   reinitialized at that time, but no other fields will have
                   been changed.  This option is meaningful only for the most
                   recently returned file from ffttss__rreeaadd().  Normal use is for
                   post-order directory visits, where it causes the directory
                   to be re-visited (in both pre and post-order) as well as
                   all of its descendants.

     FTS_FOLLOW    The referenced file must be a symbolic link.  If the refer-
                   enced file is the one most recently returned by ffttss__rreeaadd(),
                   the next call to ffttss__rreeaadd() returns the file with the
                   _f_t_s___i_n_f_o and _f_t_s___s_t_a_t_b fields reinitialized to reflect the
                   target of the symbolic link instead of the symbolic link
                   itself.  If the file is one of those most recently returned
                   by ffttss__cchhiillddrreenn(), the _f_t_s___i_n_f_o and _f_t_s___s_t_a_t_b fields of the
                   structure, when returned by ffttss__rreeaadd(), will reflect the
                   target of the symbolic link instead of the symbolic link
                   itself.  In either case, if the target of the symbolic link
                   does not exist the fields of the returned structure will be
                   unchanged and the _f_t_s___i_n_f_o field will be set to FTS_SLNONE.

                   If the target of the link is a directory, the pre-order re-
                   turn, followed by the return of all of its descendants,
                   followed by a post-order return, is done.

     FTS_SKIP      No descendants of this file are visited.  The file may be
                   one of those most recently returned by either
                   ffttss__cchhiillddrreenn() or ffttss__rreeaadd().

FFTTSS__CCLLOOSSEE
     The ffttss__cclloossee() function closes a file hierarchy stream _f_t_s_p and restores
     the current directory to the directory from which ffttss__ooppeenn() was called
     to open _f_t_s_p. The ffttss__cclloossee() function returns 0 on success, and -1 if an
     error occurs.

EERRRROORRSS
     The function ffttss__ooppeenn() may fail and set errno for any of the errors
     specified for the library functions open(2) and malloc(3).

     The function ffttss__cclloossee() may fail and set errno for any of the errors
     specified for the library functions chdir(2) and close(2).

     The functions FFttss__rreeaadd() and ffttss__cchhiillddrreenn() may fail and set errno for
     any of the errors specified for the library functions chdir(2),
     malloc(3),  opendir(3),  readdir(3) and stat(2).

SSEEEE AALLSSOO
     find(1),  chdir(2),  stat(2),  qsort(3)

SSTTAANNDDAARRDDSS
     The ffttss utility is expected to be a superset of the IEEE Std1003.1-1988
     (``POSIX'') specification.

BSD Experimental                 July 31, 1991                               6

















































