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