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 November 25, 2009 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 422As a performance optimization, the 423.Nm 424functions change directories as they walk the file hierarchy. 425This has the side-effect that an application cannot rely on being 426in any particular directory during the traversal. 427The 428.Dv FTS_NOCHDIR 429option turns off this optimization, and the 430.Nm 431functions will not change the current directory. 432Note that applications should not themselves change their current directory 433and try to access files unless 434.Dv FTS_NOCHDIR 435is specified and absolute 436pathnames were provided as arguments to 437.Fn fts_open . 438.It Dv FTS_NOSTAT 439By default, returned 440.Vt FTSENT 441structures reference file characteristic information (the 442.Fa statp 443field) for each file visited. 444This option relaxes that requirement as a performance optimization, 445allowing the 446.Nm 447functions to set the 448.Fa fts_info 449field to 450.Dv FTS_NSOK 451and leave the contents of the 452.Fa statp 453field undefined. 454.It Dv FTS_PHYSICAL 455This option causes the 456.Nm 457routines to return 458.Vt FTSENT 459structures for symbolic links themselves instead 460of the target files they point to. 461If this option is set, 462.Vt FTSENT 463structures for all symbolic links in the 464hierarchy are returned to the application. 465Either 466.Dv FTS_LOGICAL 467or 468.Dv FTS_PHYSICAL 469.Em must 470be provided to the 471.Fn fts_open 472function. 473.It Dv FTS_SEEDOT 474By default, unless they are specified as path arguments to 475.Fn fts_open , 476any files named 477.Ql .\& 478or 479.Ql ..\& 480encountered in the file hierarchy are ignored. 481This option causes the 482.Nm 483routines to return 484.Vt FTSENT 485structures for them. 486.It Dv FTS_XDEV 487This option prevents 488.Nm 489from descending into directories that have a different device number 490than the file from which the descent began. 491.El 492.Pp 493The argument 494.Fn compar 495specifies a user-defined function which may be used to order the traversal 496of the hierarchy. 497It 498takes two pointers to pointers to 499.Vt FTSENT 500structures as arguments and 501should return a negative value, zero, or a positive value to indicate 502if the file referenced by its first argument comes before, in any order 503with respect to, or after, the file referenced by its second argument. 504The 505.Fa fts_accpath , 506.Fa fts_path 507and 508.Fa fts_pathlen 509fields of the 510.Vt FTSENT 511structures may 512.Em never 513be used in this comparison. 514If the 515.Fa fts_info 516field is set to 517.Dv FTS_NS 518or 519.Dv FTS_NSOK , 520the 521.Fa fts_statp 522field may not either. 523If the 524.Fn compar 525argument is 526.Dv NULL , 527the directory traversal order is in the order listed in 528.Fa path_argv 529for the root paths, and in the order listed in the directory for 530everything else. 531.Sh FTS_READ 532The 533.Fn fts_read 534function returns a pointer to an 535.Vt FTSENT 536structure describing a file in 537the hierarchy. 538Directories (that are readable and do not cause cycles) are visited at 539least twice, once in pre-order and once in post-order. 540All other files are visited at least once. 541(Hard links between directories that do not cause cycles or symbolic 542links to symbolic links may cause files to be visited more than once, 543or directories more than twice.) 544.Pp 545If all the members of the hierarchy have been returned, 546.Fn fts_read 547returns 548.Dv NULL 549and sets the external variable 550.Va errno 551to 0. 552If an error unrelated to a file in the hierarchy occurs, 553.Fn fts_read 554returns 555.Dv NULL 556and sets 557.Va errno 558appropriately. 559If an error related to a returned file occurs, a pointer to an 560.Vt FTSENT 561structure is returned, and 562.Va errno 563may or may not have been set (see 564.Fa fts_info ) . 565.Pp 566The 567.Vt FTSENT 568structures returned by 569.Fn fts_read 570may be overwritten after a call to 571.Fn fts_close 572on the same file hierarchy stream, or, after a call to 573.Fn fts_read 574on the same file hierarchy stream unless they represent a file of type 575directory, in which case they will not be overwritten until after a call to 576.Fn fts_read 577after the 578.Vt FTSENT 579structure has been returned by the function 580.Fn fts_read 581in post-order. 582.Sh FTS_CHILDREN 583The 584.Fn fts_children 585function returns a pointer to an 586.Vt FTSENT 587structure describing the first entry in a NULL-terminated linked list of 588the files in the directory represented by the 589.Vt FTSENT 590structure most recently returned by 591.Fn fts_read . 592The list is linked through the 593.Fa fts_link 594field of the 595.Vt FTSENT 596structure, and is ordered by the user-specified comparison function, if any. 597Repeated calls to 598.Fn fts_children 599will recreate this linked list. 600.Pp 601As a special case, if 602.Fn fts_read 603has not yet been called for a hierarchy, 604.Fn fts_children 605will return a pointer to the files in the logical directory specified to 606.Fn fts_open , 607i.e., the arguments specified to 608.Fn fts_open . 609Otherwise, if the 610.Vt FTSENT 611structure most recently returned by 612.Fn fts_read 613is not a directory being visited in pre-order, 614or the directory does not contain any files, 615.Fn fts_children 616returns 617.Dv NULL 618and sets 619.Va errno 620to zero. 621If an error occurs, 622.Fn fts_children 623returns 624.Dv NULL 625and sets 626.Va errno 627appropriately. 628.Pp 629The 630.Vt FTSENT 631structures returned by 632.Fn fts_children 633may be overwritten after a call to 634.Fn fts_children , 635.Fn fts_close 636or 637.Fn fts_read 638on the same file hierarchy stream. 639.Pp 640.Em Option 641may be set to the following value: 642.Bl -tag -width FTS_NAMEONLY 643.It Dv FTS_NAMEONLY 644Only the names of the files are needed. 645The contents of all the fields in the returned linked list of structures 646are undefined with the exception of the 647.Fa fts_name 648and 649.Fa fts_namelen 650fields. 651.El 652.Sh FTS_SET 653The function 654.Fn fts_set 655allows the user application to determine further processing for the 656file 657.Fa f 658of the stream 659.Fa ftsp . 660The 661.Fn fts_set 662function 663returns 0 on success, and \-1 if an error occurs. 664.Em Option 665must be set to one of the following values: 666.Bl -tag -width FTS_PHYSICAL 667.It Dv FTS_AGAIN 668Re-visit the file; any file type may be re-visited. 669The next call to 670.Fn fts_read 671will return the referenced file. 672The 673.Fa fts_stat 674and 675.Fa fts_info 676fields of the structure will be reinitialized at that time, 677but no other fields will have been changed. 678This option is meaningful only for the most recently returned 679file from 680.Fn fts_read . 681Normal use is for post-order directory visits, where it causes the 682directory to be re-visited (in both pre and post-order) as well as all 683of its descendants. 684.It Dv FTS_FOLLOW 685The referenced file must be a symbolic link. 686If the referenced file is the one most recently returned by 687.Fn fts_read , 688the next call to 689.Fn fts_read 690returns the file with the 691.Fa fts_info 692and 693.Fa fts_statp 694fields reinitialized to reflect the target of the symbolic link instead 695of the symbolic link itself. 696If the file is one of those most recently returned by 697.Fn fts_children , 698the 699.Fa fts_info 700and 701.Fa fts_statp 702fields of the structure, when returned by 703.Fn fts_read , 704will reflect the target of the symbolic link instead of the symbolic link 705itself. 706In either case, if the target of the symbolic link does not exist the 707fields of the returned structure will be unchanged and the 708.Fa fts_info 709field will be set to 710.Dv FTS_SLNONE . 711.Pp 712If the target of the link is a directory, the pre-order return, followed 713by the return of all of its descendants, followed by a post-order return, 714is done. 715.It Dv FTS_SKIP 716No descendants of this file are visited. 717The file may be one of those most recently returned by either 718.Fn fts_children 719or 720.Fn fts_read . 721.El 722.Sh FTS_CLOSE 723The 724.Fn fts_close 725function closes a file hierarchy stream 726.Fa ftsp 727and restores the current directory to the directory from which 728.Fn fts_open 729was called to open 730.Fa ftsp . 731The 732.Fn fts_close 733function 734returns 0 on success, and \-1 if an error occurs. 735.Sh ERRORS 736The function 737.Fn fts_open 738may fail and set 739.Va errno 740for any of the errors specified for the library functions 741.Xr open 2 742and 743.Xr malloc 3 . 744.Pp 745The function 746.Fn fts_close 747may fail and set 748.Va errno 749for any of the errors specified for the library functions 750.Xr chdir 2 751and 752.Xr close 2 . 753.Pp 754The functions 755.Fn fts_read 756and 757.Fn fts_children 758may fail and set 759.Va errno 760for any of the errors specified for the library functions 761.Xr chdir 2 , 762.Xr malloc 3 , 763.Xr opendir 3 , 764.Xr readdir 3 765and 766.Xr stat 2 . 767.Pp 768In addition, 769.Fn fts_children , 770.Fn fts_open 771and 772.Fn fts_set 773may fail and set 774.Va errno 775as follows: 776.Bl -tag -width Er 777.It Bq Er EINVAL 778The options were invalid, or the list were empty. 779.El 780.Sh SEE ALSO 781.Xr find 1 , 782.Xr chdir 2 , 783.Xr stat 2 , 784.Xr ftw 3 , 785.Xr qsort 3 786.Sh HISTORY 787The 788.Nm 789interface was first introduced in 790.Bx 4.4 . 791The 792.Fn fts_get_clientptr , 793.Fn fts_get_stream , 794and 795.Fn fts_set_clientptr 796functions were introduced in 797.Fx 5.0 , 798principally to provide for alternative interfaces to the 799.Nm 800functionality using different data structures. 801