1.\" Copyright (c) 1989, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 29.\" 30.Dd January 12, 2014 31.Dt FTS 3 32.Os 33.Sh NAME 34.Nm fts 35.Nd traverse a file hierarchy 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In fts.h 40.Ft FTS * 41.Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)" 42.Ft FTSENT * 43.Fn fts_read "FTS *ftsp" 44.Ft FTSENT * 45.Fn fts_children "FTS *ftsp" "int options" 46.Ft int 47.Fn fts_set "FTS *ftsp" "FTSENT *f" "int options" 48.Ft void 49.Fn fts_set_clientptr "FTS *ftsp" "void *clientdata" 50.Ft void * 51.Fn fts_get_clientptr "FTS *ftsp" 52.Ft FTS * 53.Fn fts_get_stream "FTSENT *f" 54.Ft int 55.Fn fts_close "FTS *ftsp" 56.Sh DESCRIPTION 57The 58.Nm 59functions are provided for traversing 60.Ux 61file hierarchies. 62A simple overview is that the 63.Fn fts_open 64function returns a 65.Dq handle 66on a file hierarchy, which is then supplied to 67the other 68.Nm 69functions. 70The function 71.Fn fts_read 72returns a pointer to a structure describing one of the files in the file 73hierarchy. 74The function 75.Fn fts_children 76returns a pointer to a linked list of structures, each of which describes 77one of the files contained in a directory in the hierarchy. 78In general, directories are visited two distinguishable times; in pre-order 79(before any of their descendants are visited) and in post-order (after all 80of their descendants have been visited). 81Files are visited once. 82It is possible to walk the hierarchy 83.Dq logically 84(ignoring symbolic links) 85or physically (visiting symbolic links), order the walk of the hierarchy or 86prune and/or re-visit portions of the hierarchy. 87.Pp 88Two structures are defined (and typedef'd) in the include file 89.In fts.h . 90The first is 91.Vt FTS , 92the structure that represents the file hierarchy itself. 93The second is 94.Vt FTSENT , 95the structure that represents a file in the file 96hierarchy. 97Normally, an 98.Vt FTSENT 99structure is returned for every file in the file 100hierarchy. 101In this manual page, 102.Dq file 103and 104.Dq Vt FTSENT No structure 105are generally 106interchangeable. 107.Pp 108The 109.Vt FTS 110structure contains space for a single pointer, which may be used to 111store application data or per-hierarchy state. 112The 113.Fn fts_set_clientptr 114and 115.Fn fts_get_clientptr 116functions may be used to set and retrieve this pointer. 117This is likely to be useful only when accessed from the sort 118comparison function, which can determine the original 119.Vt FTS 120stream of its arguments using the 121.Fn fts_get_stream 122function. 123The two 124.Li get 125functions are also available as macros of the same name. 126.Pp 127The 128.Vt FTSENT 129structure contains at least the following fields, which are 130described in greater detail below: 131.Bd -literal 132typedef struct _ftsent { 133 int fts_info; /* status for FTSENT structure */ 134 char *fts_accpath; /* access path */ 135 char *fts_path; /* root path */ 136 size_t fts_pathlen; /* strlen(fts_path) */ 137 char *fts_name; /* file name */ 138 size_t fts_namelen; /* strlen(fts_name) */ 139 long fts_level; /* depth (\-1 to N) */ 140 int fts_errno; /* file errno */ 141 long long fts_number; /* local numeric value */ 142 void *fts_pointer; /* local address value */ 143 struct ftsent *fts_parent; /* parent directory */ 144 struct ftsent *fts_link; /* next file structure */ 145 struct ftsent *fts_cycle; /* cycle structure */ 146 struct stat *fts_statp; /* stat(2) information */ 147} FTSENT; 148.Ed 149.Pp 150These fields are defined as follows: 151.Bl -tag -width "fts_namelen" 152.It Fa fts_info 153One of the following values describing the returned 154.Vt FTSENT 155structure and 156the file it represents. 157With the exception of directories without errors 158.Pq Dv FTS_D , 159all of these 160entries are terminal, that is, they will not be revisited, nor will any 161of their descendants be visited. 162.Bl -tag -width FTS_DEFAULT 163.It Dv FTS_D 164A directory being visited in pre-order. 165.It Dv FTS_DC 166A directory that causes a cycle in the tree. 167(The 168.Fa fts_cycle 169field of the 170.Vt FTSENT 171structure will be filled in as well.) 172.It Dv FTS_DEFAULT 173Any 174.Vt FTSENT 175structure that represents a file type not explicitly described 176by one of the other 177.Fa fts_info 178values. 179.It Dv FTS_DNR 180A directory which cannot be read. 181This is an error return, and the 182.Fa fts_errno 183field will be set to indicate what caused the error. 184.It Dv FTS_DOT 185A file named 186.Ql .\& 187or 188.Ql ..\& 189which was not specified as a file name to 190.Fn fts_open 191(see 192.Dv FTS_SEEDOT ) . 193.It Dv FTS_DP 194A directory being visited in post-order. 195The contents of the 196.Vt FTSENT 197structure will be unchanged from when 198the directory was visited in pre-order, except for the 199.Fa fts_info 200field. 201.It Dv FTS_ERR 202This is an error return, and the 203.Fa fts_errno 204field will be set to indicate what caused the error. 205.It Dv FTS_F 206A regular file. 207.It Dv FTS_NS 208A file for which no 209.Xr stat 2 210information was available. 211The contents of the 212.Fa fts_statp 213field are undefined. 214This is an error return, and the 215.Fa fts_errno 216field will be set to indicate what caused the error. 217.It Dv FTS_NSOK 218A file for which no 219.Xr stat 2 220information was requested. 221The contents of the 222.Fa fts_statp 223field are undefined. 224.It Dv FTS_SL 225A symbolic link. 226.It Dv FTS_SLNONE 227A symbolic link with a non-existent target. 228The contents of the 229.Fa fts_statp 230field reference the file characteristic information for the symbolic link 231itself. 232.El 233.It Fa fts_accpath 234A path for accessing the file from the current directory. 235.It Fa fts_path 236The path for the file relative to the root of the traversal. 237This path contains the path specified to 238.Fn fts_open 239as a prefix. 240.It Fa fts_pathlen 241The length of the string referenced by 242.Fa fts_path . 243.It Fa fts_name 244The name of the file. 245.It Fa fts_namelen 246The length of the string referenced by 247.Fa fts_name . 248.It Fa fts_level 249The depth of the traversal, numbered from \-1 to N, where this file 250was found. 251The 252.Vt FTSENT 253structure representing the parent of the starting point (or root) 254of the traversal is numbered 255.Dv FTS_ROOTPARENTLEVEL 256(\-1), and the 257.Vt FTSENT 258structure for the root 259itself is numbered 260.Dv FTS_ROOTLEVEL 261(0). 262.It Fa fts_errno 263Upon return of a 264.Vt FTSENT 265structure from the 266.Fn fts_children 267or 268.Fn fts_read 269functions, with its 270.Fa fts_info 271field set to 272.Dv FTS_DNR , 273.Dv FTS_ERR 274or 275.Dv FTS_NS , 276the 277.Fa fts_errno 278field contains the value of the external variable 279.Va errno 280specifying the cause of the error. 281Otherwise, the contents of the 282.Fa fts_errno 283field are undefined. 284.It Fa fts_number 285This field is provided for the use of the application program and is 286not modified by the 287.Nm 288functions. 289It is initialized to 0. 290.It Fa fts_pointer 291This field is provided for the use of the application program and is 292not modified by the 293.Nm 294functions. 295It is initialized to 296.Dv NULL . 297.It Fa fts_parent 298A pointer to the 299.Vt FTSENT 300structure referencing the file in the hierarchy 301immediately above the current file, i.e., the directory of which this 302file is a member. 303A parent structure for the initial entry point is provided as well, 304however, only the 305.Fa fts_level , 306.Fa fts_number 307and 308.Fa fts_pointer 309fields are guaranteed to be initialized. 310.It Fa fts_link 311Upon return from the 312.Fn fts_children 313function, the 314.Fa fts_link 315field points to the next structure in the NULL-terminated linked list of 316directory members. 317Otherwise, the contents of the 318.Fa fts_link 319field are undefined. 320.It Fa fts_cycle 321If a directory causes a cycle in the hierarchy (see 322.Dv FTS_DC ) , 323either because 324of a hard link between two directories, or a symbolic link pointing to a 325directory, the 326.Fa fts_cycle 327field of the structure will point to the 328.Vt FTSENT 329structure in the hierarchy that references the same file as the current 330.Vt FTSENT 331structure. 332Otherwise, the contents of the 333.Fa fts_cycle 334field are undefined. 335.It Fa fts_statp 336A pointer to 337.Xr stat 2 338information for the file. 339.El 340.Pp 341A single buffer is used for all of the paths of all of the files in the 342file hierarchy. 343Therefore, the 344.Fa fts_path 345and 346.Fa fts_accpath 347fields are guaranteed to be 348.Dv NUL Ns -terminated 349.Em only 350for the file most recently returned by 351.Fn fts_read . 352To use these fields to reference any files represented by other 353.Vt FTSENT 354structures will require that the path buffer be modified using the 355information contained in that 356.Vt FTSENT 357structure's 358.Fa fts_pathlen 359field. 360Any such modifications should be undone before further calls to 361.Fn fts_read 362are attempted. 363The 364.Fa fts_name 365field is always 366.Dv NUL Ns -terminated . 367.Sh FTS_OPEN 368The 369.Fn fts_open 370function takes a pointer to an array of character pointers naming one 371or more paths which make up a logical file hierarchy to be traversed. 372The array must be terminated by a 373.Dv NULL 374pointer. 375.Pp 376There are 377a number of options, at least one of which (either 378.Dv FTS_LOGICAL 379or 380.Dv FTS_PHYSICAL ) 381must be specified. 382The options are selected by 383.Em or Ns 'ing 384the following values: 385.Bl -tag -width "FTS_PHYSICAL" 386.It Dv FTS_COMFOLLOW 387This option causes any symbolic link specified as a root path to be 388followed immediately whether or not 389.Dv FTS_LOGICAL 390is also specified. 391.It Dv FTS_LOGICAL 392This option causes the 393.Nm 394routines to return 395.Vt FTSENT 396structures for the targets of symbolic links 397instead of the symbolic links themselves. 398If this option is set, the only symbolic links for which 399.Vt FTSENT 400structures 401are returned to the application are those referencing non-existent files. 402Either 403.Dv FTS_LOGICAL 404or 405.Dv FTS_PHYSICAL 406.Em must 407be provided to the 408.Fn fts_open 409function. 410.It Dv FTS_NOCHDIR 411To allow descending to arbitrary depths 412(independent of 413.Brq Dv PATH_MAX ) 414and improve performance, the 415.Nm 416functions change directories as they walk the file hierarchy. 417This has the side-effect that an application cannot rely on being 418in any particular directory during the traversal. 419The 420.Dv FTS_NOCHDIR 421option turns off this feature, and the 422.Nm 423functions will not change the current directory. 424Note that applications should not themselves change their current directory 425and try to access files unless 426.Dv FTS_NOCHDIR 427is specified and absolute 428pathnames were provided as arguments to 429.Fn fts_open . 430.It Dv FTS_NOSTAT 431By default, returned 432.Vt FTSENT 433structures reference file characteristic information (the 434.Fa statp 435field) for each file visited. 436This option relaxes that requirement as a performance optimization, 437allowing the 438.Nm 439functions to set the 440.Fa fts_info 441field to 442.Dv FTS_NSOK 443and leave the contents of the 444.Fa statp 445field undefined. 446.It Dv FTS_PHYSICAL 447This option causes the 448.Nm 449routines to return 450.Vt FTSENT 451structures for symbolic links themselves instead 452of the target files they point to. 453If this option is set, 454.Vt FTSENT 455structures for all symbolic links in the 456hierarchy are returned to the application. 457Either 458.Dv FTS_LOGICAL 459or 460.Dv FTS_PHYSICAL 461.Em must 462be provided to the 463.Fn fts_open 464function. 465.It Dv FTS_SEEDOT 466By default, unless they are specified as path arguments to 467.Fn fts_open , 468any files named 469.Ql .\& 470or 471.Ql ..\& 472encountered in the file hierarchy are ignored. 473This option causes the 474.Nm 475routines to return 476.Vt FTSENT 477structures for them. 478.It Dv FTS_XDEV 479This option prevents 480.Nm 481from descending into directories that have a different device number 482than the file from which the descent began. 483.El 484.Pp 485The argument 486.Fn compar 487specifies a user-defined function which may be used to order the traversal 488of the hierarchy. 489It 490takes two pointers to pointers to 491.Vt FTSENT 492structures as arguments and 493should return a negative value, zero, or a positive value to indicate 494if the file referenced by its first argument comes before, in any order 495with respect to, or after, the file referenced by its second argument. 496The 497.Fa fts_accpath , 498.Fa fts_path 499and 500.Fa fts_pathlen 501fields of the 502.Vt FTSENT 503structures may 504.Em never 505be used in this comparison. 506If the 507.Fa fts_info 508field is set to 509.Dv FTS_NS 510or 511.Dv FTS_NSOK , 512the 513.Fa fts_statp 514field may not either. 515If the 516.Fn compar 517argument is 518.Dv NULL , 519the directory traversal order is in the order listed in 520.Fa path_argv 521for the root paths, and in the order listed in the directory for 522everything else. 523.Sh FTS_READ 524The 525.Fn fts_read 526function returns a pointer to an 527.Vt FTSENT 528structure describing a file in 529the hierarchy. 530Directories (that are readable and do not cause cycles) are visited at 531least twice, once in pre-order and once in post-order. 532All other files are visited at least once. 533(Hard links between directories that do not cause cycles or symbolic 534links to symbolic links may cause files to be visited more than once, 535or directories more than twice.) 536.Pp 537If all the members of the hierarchy have been returned, 538.Fn fts_read 539returns 540.Dv NULL 541and sets the external variable 542.Va errno 543to 0. 544If an error unrelated to a file in the hierarchy occurs, 545.Fn fts_read 546returns 547.Dv NULL 548and sets 549.Va errno 550appropriately. 551If an error related to a returned file occurs, a pointer to an 552.Vt FTSENT 553structure is returned, and 554.Va errno 555may or may not have been set (see 556.Fa fts_info ) . 557.Pp 558The 559.Vt FTSENT 560structures returned by 561.Fn fts_read 562may be overwritten after a call to 563.Fn fts_close 564on the same file hierarchy stream, or, after a call to 565.Fn fts_read 566on the same file hierarchy stream unless they represent a file of type 567directory, in which case they will not be overwritten until after a call to 568.Fn fts_read 569after the 570.Vt FTSENT 571structure has been returned by the function 572.Fn fts_read 573in post-order. 574.Sh FTS_CHILDREN 575The 576.Fn fts_children 577function returns a pointer to an 578.Vt FTSENT 579structure describing the first entry in a NULL-terminated linked list of 580the files in the directory represented by the 581.Vt FTSENT 582structure most recently returned by 583.Fn fts_read . 584The list is linked through the 585.Fa fts_link 586field of the 587.Vt FTSENT 588structure, and is ordered by the user-specified comparison function, if any. 589Repeated calls to 590.Fn fts_children 591will recreate this linked list. 592.Pp 593As a special case, if 594.Fn fts_read 595has not yet been called for a hierarchy, 596.Fn fts_children 597will return a pointer to the files in the logical directory specified to 598.Fn fts_open , 599i.e., the arguments specified to 600.Fn fts_open . 601Otherwise, if the 602.Vt FTSENT 603structure most recently returned by 604.Fn fts_read 605is not a directory being visited in pre-order, 606or the directory does not contain any files, 607.Fn fts_children 608returns 609.Dv NULL 610and sets 611.Va errno 612to zero. 613If an error occurs, 614.Fn fts_children 615returns 616.Dv NULL 617and sets 618.Va errno 619appropriately. 620.Pp 621The 622.Vt FTSENT 623structures returned by 624.Fn fts_children 625may be overwritten after a call to 626.Fn fts_children , 627.Fn fts_close 628or 629.Fn fts_read 630on the same file hierarchy stream. 631.Pp 632.Em Option 633may be set to the following value: 634.Bl -tag -width FTS_NAMEONLY 635.It Dv FTS_NAMEONLY 636Only the names of the files are needed. 637The contents of all the fields in the returned linked list of structures 638are undefined with the exception of the 639.Fa fts_name 640and 641.Fa fts_namelen 642fields. 643.El 644.Sh FTS_SET 645The function 646.Fn fts_set 647allows the user application to determine further processing for the 648file 649.Fa f 650of the stream 651.Fa ftsp . 652The 653.Fn fts_set 654function 655returns 0 on success, and \-1 if an error occurs. 656.Em Option 657must be set to one of the following values: 658.Bl -tag -width FTS_PHYSICAL 659.It Dv FTS_AGAIN 660Re-visit the file; any file type may be re-visited. 661The next call to 662.Fn fts_read 663will return the referenced file. 664The 665.Fa fts_stat 666and 667.Fa fts_info 668fields of the structure will be reinitialized at that time, 669but no other fields will have been changed. 670This option is meaningful only for the most recently returned 671file from 672.Fn fts_read . 673Normal use is for post-order directory visits, where it causes the 674directory to be re-visited (in both pre and post-order) as well as all 675of its descendants. 676.It Dv FTS_FOLLOW 677The referenced file must be a symbolic link. 678If the referenced file is the one most recently returned by 679.Fn fts_read , 680the next call to 681.Fn fts_read 682returns the file with the 683.Fa fts_info 684and 685.Fa fts_statp 686fields reinitialized to reflect the target of the symbolic link instead 687of the symbolic link itself. 688If the file is one of those most recently returned by 689.Fn fts_children , 690the 691.Fa fts_info 692and 693.Fa fts_statp 694fields of the structure, when returned by 695.Fn fts_read , 696will reflect the target of the symbolic link instead of the symbolic link 697itself. 698In either case, if the target of the symbolic link does not exist the 699fields of the returned structure will be unchanged and the 700.Fa fts_info 701field will be set to 702.Dv FTS_SLNONE . 703.Pp 704If the target of the link is a directory, the pre-order return, followed 705by the return of all of its descendants, followed by a post-order return, 706is done. 707.It Dv FTS_SKIP 708No descendants of this file are visited. 709The file may be one of those most recently returned by either 710.Fn fts_children 711or 712.Fn fts_read . 713.El 714.Sh FTS_CLOSE 715The 716.Fn fts_close 717function closes a file hierarchy stream 718.Fa ftsp 719and restores the current directory to the directory from which 720.Fn fts_open 721was called to open 722.Fa ftsp . 723The 724.Fn fts_close 725function 726returns 0 on success, and \-1 if an error occurs. 727.Sh ERRORS 728The function 729.Fn fts_open 730may fail and set 731.Va errno 732for any of the errors specified for the library functions 733.Xr open 2 734and 735.Xr malloc 3 . 736.Pp 737The function 738.Fn fts_close 739may fail and set 740.Va errno 741for any of the errors specified for the library functions 742.Xr chdir 2 743and 744.Xr close 2 . 745.Pp 746The functions 747.Fn fts_read 748and 749.Fn fts_children 750may fail and set 751.Va errno 752for any of the errors specified for the library functions 753.Xr chdir 2 , 754.Xr malloc 3 , 755.Xr opendir 3 , 756.Xr readdir 3 757and 758.Xr stat 2 . 759.Pp 760In addition, 761.Fn fts_children , 762.Fn fts_open 763and 764.Fn fts_set 765may fail and set 766.Va errno 767as follows: 768.Bl -tag -width Er 769.It Bq Er EINVAL 770The options were invalid, or the list were empty. 771.El 772.Sh SEE ALSO 773.Xr find 1 , 774.Xr chdir 2 , 775.Xr stat 2 , 776.Xr ftw 3 , 777.Xr qsort 3 778.Sh HISTORY 779The 780.Nm 781interface was first introduced in 782.Bx 4.4 . 783The 784.Fn fts_get_clientptr , 785.Fn fts_get_stream , 786and 787.Fn fts_set_clientptr 788functions were introduced in 789.Fx 5.0 , 790principally to provide for alternative interfaces to the 791.Nm 792functionality using different data structures. 793.Sh BUGS 794The 795.Fn fts_open 796function will automatically set the 797.Dv FTS_NOCHDIR 798option if the 799.Dv FTS_LOGICAL 800option is provided, or if it cannot 801.Xr open 2 802the current directory. 803