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