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