home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / man / cat3 / fts.0 < prev    next >
Text File  |  1993-12-07  |  22KB  |  397 lines
  1.  
  2. FTS(3)                     UNIX Programmer's Manual                     FTS(3)
  3.  
  4. NNAAMMEE
  5.      ffttss - traverse a file hierarchy
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  9.      ##iinncclluuddee <<ssyyss//ssttaatt..hh>>
  10.      ##iinncclluuddee <<ffttss..hh>>
  11.  
  12.      _F_T_S _*
  13.      ffttss__ooppeenn(_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,
  14.              _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 _*_))
  15.  
  16.      _F_T_S_E_N_T _*
  17.      ffttss__rreeaadd(_F_T_S _*_f_t_s_p)
  18.  
  19.      _F_T_S_E_N_T _*
  20.      ffttss__cchhiillddrreenn(_F_T_S _*_f_t_s_p)
  21.  
  22.      _i_n_t
  23.      ffttss__sseett(_F_T_S _f_t_s_p, _F_T_S_E_N_T _*_f, _i_n_t _o_p_t_i_o_n_s)
  24.  
  25.      _i_n_t
  26.      ffttss__cclloossee(_F_T_S _*_f_t_s_p)
  27.  
  28. DDEESSCCRRIIPPTTIIOONN
  29.      The ffttss functions are provided for traversing UNIX file hierarchies.
  30.  
  31.      The simple overview is that the ffttss__ooppeenn() function returns a ``handle''
  32.      on a file hierarchy, which is supplied to the other ffttss functions to de­
  33.      termine which hierarchy they operate on.  The function ffttss__rreeaadd() returns
  34.      a pointer to a structure describing one of the files in the file hierar­
  35.      chy.  The function ffttss__cchhiillddrreenn() returns a pointer to a linked list of
  36.      structures, each of which describes one of the files contained in a di­
  37.      rectory in the hierarchy.  In general, directories are visited two dis­
  38.      tinguishable times; in pre­order (before any of their descendants are
  39.      visited) and in post­order (after all of their descendants have been vis­
  40.      ited).  Files are visited once.  It is possible to walk the hierarchy
  41.      ``logically'' (ignoring symbolic links) or physically (visiting symbolic
  42.      links), order the walk of the hierarchy or prune and/or re­visit portions
  43.      of the hierarchy.
  44.  
  45.      Two structures are defined (and typedef'd) in the include file <_f_t_s_._h>.
  46.      The first is _F_T_S, the structure that represents the file hierarchy
  47.      stream.  The second is _F_T_S_E_N_T, the structure that represents a file in
  48.      the file hierarchy.  Normally, an _F_T_S_E_N_T structure is returned for every
  49.      file in the file hierarchy.  In this manual page, ``file'' and ``_F_T_S_E_N_T
  50.      structure'' are generally interchangeable.  The _F_T_S_E_N_T structure contains
  51.      at least the following fields, which are described in greater detail be­
  52.      low:
  53.  
  54.      typedef struct _ftsent {
  55.              u_short fts_info;               /* flags for FTSENT structure */
  56.              char *fts_accpath;              /* access path */
  57.              char *fts_path;                 /* root path */
  58.              short fts_pathlen;              /* strlen(fts_path) */
  59.              char *fts_name;                 /* file name */
  60.              short fts_namelen;              /* strlen(fts_name) */
  61.              short fts_level;                /* depth (-1 to N) */
  62.              long fts_number;                /* local numeric value */
  63.              void *fts_pointer;              /* local address value */
  64.              struct ftsent *fts_parent;      /* parent directory */
  65.              struct ftsent *fts_link;        /* cycle or next file structure */
  66.              struct stat fts_statb;          /* stat(2) information */
  67.      } FTSENT;
  68.  
  69.      These fields are defined as follows:
  70.  
  71.      _f_t_s___i_n_f_o     One of the following flags describing the returned _F_T_S_E_N_T
  72.                   structure and the file it represents.  With the exception of
  73.                   directories without errors (FTS_D), all of these entries are
  74.                   terminal, that is, they will not be revisited, nor will any
  75.                   of their descendants be visited.
  76.  
  77.                   FTS_D        A directory being visited in pre­order.
  78.  
  79.                   FTS_DC       A directory that causes a cycle in the tree.
  80.                                (The _f_t_s___l_i_n_k field of the _F_T_S_E_N_T structure
  81.                                will be filled in as well.)
  82.  
  83.                   FTS_DEFAULT  Any _F_T_S_E_N_T structure that represents a file
  84.                                type not explicitly described by one of the
  85.                                other _f_t_s___i_n_f_o values.
  86.  
  87.                   FTS_DNR      A directory which cannot be read.  An error re­
  88.                                turn; the external variable _e_r_r_n_o will be set
  89.                                to indicate the error.
  90.  
  91.                   FTS_DOT      A file named `.' or `..' which was not speci­
  92.                                fied as a file name to ffttss__ooppeenn() (see
  93.                                FTS_SEEDOT).
  94.  
  95.                   FTS_DP       A directory being visited in post­order.  The
  96.                                contents of the _F_T_S_E_N_T structure will be un­
  97.                                changed from when it was returned in pre­order,
  98.                                i.e. with the _f_t_s___i_n_f_o field set to FTS_D.
  99.  
  100.                   FTS_ERR      An error return; the external variable _e_r_r_n_o
  101.                                will be set to indicate the error.
  102.  
  103.                   FTS_F        A regular file.
  104.  
  105.                   FTS_NS       A file for which no stat(2) information was
  106.                                available.  The contents of the _f_t_s___s_t_a_t_b field
  107.                                are undefined.  An error return; the external
  108.                                variable _e_r_r_n_o will be set to indicate the er­
  109.                                ror.
  110.  
  111.                   FTS_NSOK     A file for which no stat(2) information was re­
  112.                                quested.  The contents of the _f_t_s___s_t_a_t_b field
  113.                                are undefined.
  114.  
  115.                   FTS_SL       A symbolic link.
  116.  
  117.                   FTS_SLNONE   A symbolic link with a non­existent target.
  118.                                The contents of the _f_t_s___s_t_a_t_b field contain the
  119.                                file characteristic information for the symbol­
  120.                                ic link itself.
  121.  
  122.      _f_t_s___a_c_c_p_a_t_h  A path for accessing the file from the current directory.
  123.  
  124.      _f_t_s___p_a_t_h     The path for the file relative to the root of the traversal.
  125.                   This path contains the path specified to ffttss__ooppeenn() as a
  126.                   prefix.
  127.  
  128.      _f_t_s___p_a_t_h_l_e_n  The length of the string referenced by _f_t_s___p_a_t_h.
  129.  
  130.  
  131.  
  132.      _f_t_s___n_a_m_e     The name of the file.
  133.  
  134.      _f_t_s___n_a_m_e_l_e_n  The length of the string referenced by _f_t_s___n_a_m_e.
  135.  
  136.      _f_t_s___l_e_v_e_l    The depth of the traversal, numbered from -1 to N, where
  137.                   this file was found.  The _F_T_S_E_N_T structure representing the
  138.                   parent of the starting point (or root) of the traversal is
  139.                   numbered -1, and the _F_T_S_E_N_T structure for the root itself is
  140.                   numbered 0.
  141.  
  142.      _f_t_s___n_u_m_b_e_r   This field is provided for the use of the application pro­
  143.                   gram and is not modified by the ffttss functions.  It is ini­
  144.                   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
  145.                   the same physical location; using both may cause undefined
  146.                   results.
  147.  
  148.      _f_t_s___p_o_i_n_t_e_r  This field is provided for the use of the application pro­
  149.                   gram and is not modified by the ffttss functions.  It is ini­
  150.                   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