1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)fts.3 5.15 (Berkeley) 01/09/92 7.\" 8.Dd 9.Dt FTS 3 10.Os 11.Sh NAME 12.Nm fts 13.Nd traverse a file hierarchy 14.Sh SYNOPSIS 15.Fd #include <sys/types.h> 16.Fd #include <sys/stat.h> 17.Fd #include <fts.h> 18.Ft FTS * 19.Fn fts_open "char * const *path_argv" "int options" "int *compar(const FTSENT *, const FTSENT *)" 20.Ft FTSENT * 21.Fn fts_read "FTS *ftsp" 22.Ft FTSENT * 23.Fn fts_children "FTS *ftsp" 24.Ft int 25.Fn fts_set "FTS ftsp" "FTSENT *f" "int options" 26.Ft int 27.Fn fts_close "FTS *ftsp" 28.Sh DESCRIPTION 29The 30.Nm fts 31functions are provided for traversing 32.Tn UNIX 33file hierarchies. 34.Pp 35The simple overview is that the 36.Fn fts_open 37function returns a ``handle'' on a file hierarchy, which is supplied to 38the other 39.Nm fts 40functions to determine which hierarchy they operate on. 41The function 42.Fn fts_read 43returns a pointer to a structure describing one of the files in the file 44hierarchy. 45The function 46.Fn fts_children 47returns a pointer to a linked list of structures, each of which describes 48one of the files contained in a directory in the hierarchy. 49In general, directories are visited two distinguishable times; in pre-order 50(before any of their descendants are visited) and in post-order (after all 51of their descendants have been visited). 52Files are visited once. 53It is possible to walk the hierarchy ``logically'' (ignoring symbolic links) 54or physically (visiting symbolic links), order the walk of the hierarchy or 55prune and/or re-visit portions of the hierarchy. 56.Pp 57Two structures are defined (and typedef'd) in the include file 58.Aq Pa fts.h . 59The first is 60.Fa FTS , 61the structure that represents the file hierarchy stream. 62The second is 63.Fa FTSENT , 64the structure that represents a file in the file 65hierarchy. 66Normally, an 67.Fa FTSENT 68structure is returned for every file in the file 69hierarchy. 70In this manual page, ``file'' and 71.Dq Fa FTSENT No structure 72are generally 73interchangeable. 74The 75.Fa FTSENT 76structure contains at least the following fields, which are 77described in greater detail below: 78.Bd -literal 79typedef struct _ftsent { 80 u_short fts_info; /* flags for FTSENT structure */ 81 char *fts_accpath; /* access path */ 82 char *fts_path; /* root path */ 83 short fts_pathlen; /* strlen(fts_path) */ 84 char *fts_name; /* file name */ 85 short fts_namelen; /* strlen(fts_name) */ 86 short fts_level; /* depth (\-1 to N) */ 87 int fts_error; /* node errno */ 88 long fts_number; /* local numeric value */ 89 void *fts_pointer; /* local address value */ 90 struct ftsent *fts_parent; /* parent directory */ 91 struct ftsent *fts_link; /* next file structure */ 92 struct ftsent *fts_cycle; /* cycle structure */ 93 struct stat fts_statb; /* stat(2) information */ 94} FTSENT; 95.Ed 96.Pp 97These fields are defined as follows: 98.Bl -tag -width "fts_namelen" 99.It Fa fts_info 100One of the following flags describing the returned 101.Fa FTSENT 102structure and 103the file it represents. 104With the exception of directories without errors 105.Pq Dv FTS_D , 106all of these 107entries are terminal, that is, they will not be revisited, nor will any 108of their descendants be visited. 109.Bl -tag -width FTS_DEFAULT 110.It Dv FTS_D 111A directory being visited in pre-order. 112.It Dv FTS_DC 113A directory that causes a cycle in the tree. 114(The 115.Fa fts_cycle 116field of the 117.Fa FTSENT 118structure will be filled in as well.) 119.It Dv FTS_DEFAULT 120Any 121.Fa FTSENT 122structure that represents a file type not explicitly described 123by one of the other 124.Fa fts_info 125values. 126.It Dv FTS_DNR 127A directory which cannot be read. 128This is an error return, and the 129.Fa fts_errno 130field will be set to indicate what caused the error. 131.It Dv FTS_DP 132A directory being visited in post-order. 133The contents of the 134.Fa FTSENT 135structure will be unchanged from when 136it was returned in pre-order, i.e. with the 137.Fa fts_info 138field set to 139.Dv FTS_D . 140.It Dv FTS_ERR 141This is an error return, and the 142.Fa fts_errno 143field will be set to indicate what caused the error. 144.It Dv FTS_F 145A regular file. 146.It Dv FTS_NS 147A file for which no 148.Xr stat 2 149information was available. 150The contents of the 151.Fa fts_statb 152field are undefined. 153This is an error return, and the 154.Fa fts_errno 155field will be set to indicate what caused the error. 156.It Dv FTS_NSOK 157A file for which no 158.Xr stat 2 159information was requested. 160The contents of the 161.Fa fts_statb 162field are undefined. 163.It Dv FTS_SL 164A symbolic link. 165.It Dv FTS_SLNONE 166A symbolic link with a non-existent target. 167The contents of the 168.Fa fts_statb 169field contain the file characteristic information for the symbolic link 170itself. 171.El 172.It Fa fts_accpath 173A path for accessing the file from the current directory. 174.It Fa fts_path 175The path for the file relative to the root of the traversal. 176This path contains the path specified to 177.Fn fts_open 178as a prefix. 179.It Fa fts_pathlen 180The length of the string referenced by 181.Fa fts_path . 182.It Fa fts_name 183The name of the file. 184.It Fa fts_namelen 185The length of the string referenced by 186.Fa fts_name . 187.It Fa fts_level 188The depth of the traversal, numbered from \-1 to N, where this file 189was found. 190The 191.Fa FTSENT 192structure representing the parent of the starting point (or root) 193of the traversal is numbered \-1, and the 194.Fa FTSENT 195structure for the root 196itself is numbered 0. 197.It Fa fts_errno 198Upon return of a node from the 199.Fn fts_children 200or 201.Fn fts_read 202functions, with its 203.Fa fts_info 204field set to 205.Dv FTS_ERR 206or 207.Dv FTS_NS , 208the 209.Fa fts_errno 210field contains the value of the external variable 211.Va errno 212specifying the cause of the error. 213Otherwise, the contents of the 214.Fa fts_errno 215field are undefined. 216.It Fa fts_number 217This field is provided for the use of the application program and is 218not modified by the 219.Nm fts 220functions. 221It is initialized to 0. 222The fields 223.Fa fts_number 224and 225.Fa fts_pointer 226occupy the same physical location; using both may cause undefined results. 227.It Fa fts_pointer 228This field is provided for the use of the application program and is 229not modified by the 230.Nm fts 231functions. 232It is initialized to 233.Dv NULL . 234The fields 235.Fa fts_number 236and 237.Fa fts_pointer 238occupy the same physical location; using both may cause undefined results. 239.It Fa fts_parent 240A pointer to the 241.Fa FTSENT 242structure referencing the file in the hierarchy 243immediately above the current file, i.e. the directory of which this 244file is a member. 245A parent structure for the initial entry point is provided as well, 246however, only the 247.Fa fts_level , 248.Fa fts_number 249and 250.Fa fts_pointer 251fields are guaranteed to be initialized. 252.It Fa fts_link 253Upon return from the 254.Fn fts_children 255function, the 256.Fa fts_link 257field points to the next structure in the NULL-terminated linked list of 258directory members. 259Otherwise, the contents of the 260.Fa fts_link 261field are undefined. 262.It Fa fts_cycle 263If a directory causes a cycle in the hierarchy (see 264.Dv FTS_DC ) , 265either because 266of a hard link between two directories, or a symbolic link pointing to a 267directory, the 268.Fa fts_cycle 269field of the structure will point to the 270.Fa FTSENT 271structure in the hierarchy that references the same file as the current 272.Fa FTSENT 273structure. 274Otherwise, the contents of the 275.Fa fts_cycle 276field are undefined. 277.It Fa fts_statb 278.Xr Stat 2 279information for the file. 280.El 281.Pp 282A single buffer is used for all of the paths of all of the files in the 283file hierarchy. 284Therefore, the 285.Fa fts_path 286and 287.Fa fts_accpath 288fields are guaranteed to be 289.Dv NULL Ns -terminated 290.Em only 291for the file most recently returned by 292.Fn fts_read . 293To use these fields to reference any files represented by other 294.Fa FTSENT 295structures will require that the path buffer be modified using the 296information contained in that 297.Fa FTSENT 298structure's 299.Fa fts_pathlen 300field. 301Any such modifications should be undone before further calls to 302.Fn fts_read 303are attempted. 304The 305.Fa fts_name 306field is always 307.Dv NULL Ns -terminated. 308.Sh FTS_OPEN 309The 310.Fn fts_open 311function takes a pointer to an array of character pointers naming one 312or more paths which make up a logical file hierarchy to be traversed. 313The array must be terminated by a 314.Dv NULL 315pointer. 316.Pp 317There are 318a number of options, at least one of which (either 319.Dv FTS_LOGICAL 320or 321.Dv FTS_PHYSICAL ) 322must be specified. 323The options are selected by 324.Em or Ns 'ing 325the following values: 326.Bl -tag -width "FTS_PHYSICAL" 327.It Dv FTS_LOGICAL 328This option causes the 329.Nm fts 330routines to return 331.Fa FTSENT 332structures for the targets of symbolic links 333instead of the symbolic links themselves. 334If this option is set, the only symbolic links for which 335.Fa FTSENT 336structures 337are returned to the application are those referencing non-existent files. 338Either 339.Dv FTS_LOGICAL 340or 341.Dv FTS_PHYSICAL 342.Em must 343be provided to the 344.Fn fts_open 345function. 346.It Dv FTS_NOCHDIR 347As a performance optimization, the 348.Nm fts 349functions change directories as they walk the file hierarchy. 350This has the side-effect that an application cannot rely on being 351in any particular directory during the traversal. 352The 353.Dv FTS_NOCHDIR 354option turns off this optimization, and the 355.Nm fts 356functions will not change the current directory. 357Note that applications should not themselves change their current directory 358and try to access files unless 359.Dv FTS_NOCHDIR 360is specified and absolute 361pathnames were provided as arguments to 362.Fn fts_open . 363.It Dv FTS_NOSTAT 364By default, returned 365.Fa FTSENT 366structures contain file characteristic 367information (the 368.Fa statb 369field) for each file visited. 370This option relaxes that requirement as a performance optimization, 371allowing the 372.Nm fts 373functions to set the 374.Fa fts_info 375field to 376.Dv FTS_NSOK 377and leave the contents of the 378.Fa statb 379field undefined. 380.It Dv FTS_PHYSICAL 381This option causes the 382.Nm fts 383routines to return 384.Fa FTSENT 385structures for symbolic links themselves instead 386of the target files they point to. 387If this option is set, 388.Fa FTSENT 389structures for all symbolic links in the 390hierarchy are returned to the application. 391Either 392.Dv FTS_LOGICAL 393or 394.Dv FTS_PHYSICAL 395.Em must 396be provided to the 397.Fn fts_open 398function. 399.It Dv FTS_SEEDOT 400By default, unless they are specified as path arguments to 401.Fn fts_open , 402any files named 403.Ql \&. 404or 405.Ql .. 406encountered in the file hierarchy are 407ignored. 408This option causes the 409.Nm fts 410routines to return 411.Fa FTSENT 412structures for them. 413.It Dv FTS_XDEV 414This option prevents 415.Nm fts 416from descending into directories that have a different device number 417than the file from which the descent began. 418.El 419.Pp 420The argument 421.Fn compar 422specifies a user-defined function which may be used to order the traversal 423of the hierarchy. 424It 425takes two pointers to pointers to 426.Fa FTSENT 427structures as arguments and 428should return a negative value, zero, or a positive value to indicate 429if the file referenced by its first argument comes before, in any order 430with respect to, or after, the file referenced by its second argument. 431The 432.Fa fts_accpath , 433.Fa fts_path 434and 435.Fa fts_pathlen 436fields of the 437.Fa FTSENT 438structures may 439.Em never 440be used in this comparison. 441If the 442.Fa fts_info 443field is set to 444.Dv FTS_NS 445or 446.DV FTS_NSOK , 447the 448.Fa fts_stab 449field may not either. 450If the 451.Fn compar 452argument is 453.Dv NULL , 454the directory traversal order is unspecified except 455for the root paths which are traversed in the order listed in 456.Fa path_argv . 457.Sh FTS_READ 458The 459.Fn fts_read 460function returns a pointer to an 461.Fa FTSENT 462structure describing a file in 463the hierarchy. 464Directories (that are readable and do not cause cycles) are visited at 465least twice, once in pre-order and once in post-order. 466All other files are visited at least once. 467(Hard links between directories that do not cause cycles or symbolic 468links to symbolic links may cause files to be visited more than once, 469or directories more than twice.) 470.Pp 471If all the members of the hierarchy have been returned, 472.Fn fts_read 473returns 474.Dv NULL 475and sets the external variable 476.Va errno 477to 0. 478If an error unrelated to a file in the hierarchy occurs, 479.Fn fts_read 480returns 481.Dv NULL 482and sets 483.Va errno 484appropriately. 485If an error related to a returned file occurs, a pointer to an 486.Fa FTSENT 487structure is returned, and 488.Va errno 489may or may not have been set (see 490.Fa fts_info ) . 491.Pp 492The 493.Fa FTSENT 494structures returned by 495.Fn fts_read 496may be overwritten after a call to 497.Fn fts_close 498on the same file hierarchy stream, or, after a call to 499.Fn fts_read 500on the same file hierarchy stream unless they represent a file of type 501directory, in which case they will not be overwritten until after a call to 502.Fn fts_read 503after the 504.Fa FTSENT 505structure has been returned by the function 506.Fn fts_read 507in post-order. 508.Sh FTS_CHILDREN 509The 510.Fn fts_children 511function returns a pointer to an 512.Fa FTSENT 513structure describing the first entry in a NULL-terminated linked list of 514the files in the directory represented by the 515.Fa FTSENT 516structure most recently returned by 517.Fn fts_read . 518The list is linked through the 519.Fa fts_link 520field of the 521.Fa FTSENT 522structure, and is ordered by the user-specified comparison function, if any. 523Repeated calls to 524.Fn fts_children 525will recreate this linked list. 526.Pp 527As a special case, if 528.Fn fts_read 529has not yet been called for a hierarchy, 530.Fn fts_children 531will return a pointer to the files in the logical directory specified to 532.Fn fts_open , 533i.e. the arguments specified to 534.Fn fts_open . 535Otherwise, if the 536.Fa FTSENT 537structure most recently returned by 538.Fn fts_read 539is not a directory being visited in pre-order, 540or the directory does not contain any files, 541.Fn fts_children 542returns 543.Dv NULL 544and sets 545.Va errno 546to zero. 547If an error occurs, 548.Fn fts_children 549returns 550.Dv NULL 551and sets 552.Va errno 553appropriately. 554.Pp 555The 556.Fa FTSENT 557structures returned by 558.Fn fts_children 559may be overwritten after a call to 560.Fn fts_children , 561.Fn fts_close 562or 563.Fn fts_read 564on the same file hierarchy stream. 565.Sh FTS_SET 566The function 567.Fn fts_set 568allows the user application to determine further processing for the 569file 570.Fa f 571of the stream 572.Fa ftsp . 573The 574.Fn fts_set 575function 576returns 0 on success, and \-1 if an error occurs. 577.Em Option 578must be set to one of the following values: 579.Bl -tag -width FTS_PHYSICAL 580.It Dv FTS_AGAIN 581Re-visit the file; any file type may be re-visited. 582The next call to 583.Fn fts_read 584will return the referenced file. 585The 586.Fa fts_stat 587and 588.Fa fts_info 589fields of the structure will be reinitialized at that time, 590but no other fields will have been changed. 591This option is meaningful only for the most recently returned 592file from 593.Fn fts_read . 594Normal use is for post-order directory visits, where it causes the 595directory to be re-visited (in both pre and post-order) as well as all 596of its descendants. 597.It Dv FTS_FOLLOW 598The referenced file must be a symbolic link. 599If the referenced file is the one most recently returned by 600.Fn fts_read , 601the next call to 602.Fn fts_read 603returns the file with the 604.Fa fts_info 605and 606.Fa fts_statb 607fields reinitialized to reflect the target of the symbolic link instead 608of the symbolic link itself. 609If the file is one of those most recently returned by 610.Fn fts_children , 611the 612.Fa fts_info 613and 614.Fa fts_statb 615fields of the structure, when returned by 616.Fn fts_read , 617will reflect the target of the symbolic link instead of the symbolic link 618itself. 619In either case, if the target of the symbolic link does not exist the 620fields of the returned structure will be unchanged and the 621.Fa fts_info 622field will be set to 623.Dv FTS_SLNONE . 624.Pp 625If the target of the link is a directory, the pre-order return, followed 626by the return of all of its descendants, followed by a post-order return, 627is done. 628.It Dv FTS_SKIP 629No descendants of this file are visited. 630The file may be one of those most recently returned by either 631.Fn fts_children 632or 633.Fn fts_read . 634.El 635.Sh FTS_CLOSE 636The 637.Fn fts_close 638function closes a file hierarchy stream 639.Fa ftsp 640and restores the current directory to the directory from which 641.Fn fts_open 642was called to open 643.Fa ftsp . 644The 645.Fn fts_close 646function 647returns 0 on success, and \-1 if an error occurs. 648.Sh ERRORS 649The function 650.Fn fts_open 651may fail and set errno for any of the errors specified for the library 652functions 653.Xr open 2 654and 655.Xr malloc 3 . 656.Pp 657The function 658.Fn fts_close 659may fail and set errno for any of the errors specified for the library 660functions 661.Xr chdir 2 662and 663.Xr close 2 . 664.Pp 665The functions 666.Fn fts_read 667and 668.Fn fts_children 669may fail and set errno for any of the errors specified for the library 670functions 671.Xr chdir 2 , 672.Xr malloc 3 , 673.Xr opendir 3 , 674.Xr readdir 3 675and 676.Xr stat 2 . 677.Sh SEE ALSO 678.Xr find 1 , 679.Xr chdir 2 , 680.Xr stat 2 , 681.Xr qsort 3 682.Sh STANDARDS 683The 684.Nm fts 685utility is expected to be a superset of the 686.St -p1003.1-88 687specification. 688