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