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 May 21, 2013 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_bignum , 308.Fa fts_number 309and 310.Fa fts_pointer 311fields are guaranteed to be initialized. 312.It Fa fts_link 313Upon return from the 314.Fn fts_children 315function, the 316.Fa fts_link 317field points to the next structure in the NULL-terminated linked list of 318directory members. 319Otherwise, the contents of the 320.Fa fts_link 321field are undefined. 322.It Fa fts_cycle 323If a directory causes a cycle in the hierarchy (see 324.Dv FTS_DC ) , 325either because 326of a hard link between two directories, or a symbolic link pointing to a 327directory, the 328.Fa fts_cycle 329field of the structure will point to the 330.Vt FTSENT 331structure in the hierarchy that references the same file as the current 332.Vt FTSENT 333structure. 334Otherwise, the contents of the 335.Fa fts_cycle 336field are undefined. 337.It Fa fts_statp 338A pointer to 339.Xr stat 2 340information for the file. 341.El 342.Pp 343A single buffer is used for all of the paths of all of the files in the 344file hierarchy. 345Therefore, the 346.Fa fts_path 347and 348.Fa fts_accpath 349fields are guaranteed to be 350.Dv NUL Ns -terminated 351.Em only 352for the file most recently returned by 353.Fn fts_read . 354To use these fields to reference any files represented by other 355.Vt FTSENT 356structures will require that the path buffer be modified using the 357information contained in that 358.Vt FTSENT 359structure's 360.Fa fts_pathlen 361field. 362Any such modifications should be undone before further calls to 363.Fn fts_read 364are attempted. 365The 366.Fa fts_name 367field is always 368.Dv NUL Ns -terminated . 369.Pp 370Note that the use of 371.Fa fts_bignum 372is mutually exclusive with the use of 373.Fa fts_number 374or 375.Fa fts_pointer . 376.Sh FTS_OPEN 377The 378.Fn fts_open 379function takes a pointer to an array of character pointers naming one 380or more paths which make up a logical file hierarchy to be traversed. 381The array must be terminated by a 382.Dv NULL 383pointer. 384.Pp 385There are 386a number of options, at least one of which (either 387.Dv FTS_LOGICAL 388or 389.Dv FTS_PHYSICAL ) 390must be specified. 391The options are selected by 392.Em or Ns 'ing 393the following values: 394.Bl -tag -width "FTS_PHYSICAL" 395.It Dv FTS_COMFOLLOW 396This option causes any symbolic link specified as a root path to be 397followed immediately whether or not 398.Dv FTS_LOGICAL 399is also specified. 400.It Dv FTS_LOGICAL 401This option causes the 402.Nm 403routines to return 404.Vt FTSENT 405structures for the targets of symbolic links 406instead of the symbolic links themselves. 407If this option is set, the only symbolic links for which 408.Vt FTSENT 409structures 410are returned to the application are those referencing non-existent files. 411Either 412.Dv FTS_LOGICAL 413or 414.Dv FTS_PHYSICAL 415.Em must 416be provided to the 417.Fn fts_open 418function. 419.It Dv FTS_NOCHDIR 420To allow descending to arbitrary depths 421(independent of 422.Brq Dv PATH_MAX ) 423and improve performance, the 424.Nm 425functions change directories as they walk the file hierarchy. 426This has the side-effect that an application cannot rely on being 427in any particular directory during the traversal. 428The 429.Dv FTS_NOCHDIR 430option turns off this feature, and the 431.Nm 432functions will not change the current directory. 433Note that applications should not themselves change their current directory 434and try to access files unless 435.Dv FTS_NOCHDIR 436is specified and absolute 437pathnames were provided as arguments to 438.Fn fts_open . 439.It Dv FTS_NOSTAT 440By default, returned 441.Vt FTSENT 442structures reference file characteristic information (the 443.Fa statp 444field) for each file visited. 445This option relaxes that requirement as a performance optimization, 446allowing the 447.Nm 448functions to set the 449.Fa fts_info 450field to 451.Dv FTS_NSOK 452and leave the contents of the 453.Fa statp 454field undefined. 455.It Dv FTS_PHYSICAL 456This option causes the 457.Nm 458routines to return 459.Vt FTSENT 460structures for symbolic links themselves instead 461of the target files they point to. 462If this option is set, 463.Vt FTSENT 464structures for all symbolic links in the 465hierarchy are returned to the application. 466Either 467.Dv FTS_LOGICAL 468or 469.Dv FTS_PHYSICAL 470.Em must 471be provided to the 472.Fn fts_open 473function. 474.It Dv FTS_SEEDOT 475By default, unless they are specified as path arguments to 476.Fn fts_open , 477any files named 478.Ql .\& 479or 480.Ql ..\& 481encountered in the file hierarchy are ignored. 482This option causes the 483.Nm 484routines to return 485.Vt FTSENT 486structures for them. 487.It Dv FTS_XDEV 488This option prevents 489.Nm 490from descending into directories that have a different device number 491than the file from which the descent began. 492.El 493.Pp 494The argument 495.Fn compar 496specifies a user-defined function which may be used to order the traversal 497of the hierarchy. 498It 499takes two pointers to pointers to 500.Vt FTSENT 501structures as arguments and 502should return a negative value, zero, or a positive value to indicate 503if the file referenced by its first argument comes before, in any order 504with respect to, or after, the file referenced by its second argument. 505The 506.Fa fts_accpath , 507.Fa fts_path 508and 509.Fa fts_pathlen 510fields of the 511.Vt FTSENT 512structures may 513.Em never 514be used in this comparison. 515If the 516.Fa fts_info 517field is set to 518.Dv FTS_NS 519or 520.Dv FTS_NSOK , 521the 522.Fa fts_statp 523field may not either. 524If the 525.Fn compar 526argument is 527.Dv NULL , 528the directory traversal order is in the order listed in 529.Fa path_argv 530for the root paths, and in the order listed in the directory for 531everything else. 532.Sh FTS_READ 533The 534.Fn fts_read 535function returns a pointer to an 536.Vt FTSENT 537structure describing a file in 538the hierarchy. 539Directories (that are readable and do not cause cycles) are visited at 540least twice, once in pre-order and once in post-order. 541All other files are visited at least once. 542(Hard links between directories that do not cause cycles or symbolic 543links to symbolic links may cause files to be visited more than once, 544or directories more than twice.) 545.Pp 546If all the members of the hierarchy have been returned, 547.Fn fts_read 548returns 549.Dv NULL 550and sets the external variable 551.Va errno 552to 0. 553If an error unrelated to a file in the hierarchy occurs, 554.Fn fts_read 555returns 556.Dv NULL 557and sets 558.Va errno 559appropriately. 560If an error related to a returned file occurs, a pointer to an 561.Vt FTSENT 562structure is returned, and 563.Va errno 564may or may not have been set (see 565.Fa fts_info ) . 566.Pp 567The 568.Vt FTSENT 569structures returned by 570.Fn fts_read 571may be overwritten after a call to 572.Fn fts_close 573on the same file hierarchy stream, or, after a call to 574.Fn fts_read 575on the same file hierarchy stream unless they represent a file of type 576directory, in which case they will not be overwritten until after a call to 577.Fn fts_read 578after the 579.Vt FTSENT 580structure has been returned by the function 581.Fn fts_read 582in post-order. 583.Sh FTS_CHILDREN 584The 585.Fn fts_children 586function returns a pointer to an 587.Vt FTSENT 588structure describing the first entry in a NULL-terminated linked list of 589the files in the directory represented by the 590.Vt FTSENT 591structure most recently returned by 592.Fn fts_read . 593The list is linked through the 594.Fa fts_link 595field of the 596.Vt FTSENT 597structure, and is ordered by the user-specified comparison function, if any. 598Repeated calls to 599.Fn fts_children 600will recreate this linked list. 601.Pp 602As a special case, if 603.Fn fts_read 604has not yet been called for a hierarchy, 605.Fn fts_children 606will return a pointer to the files in the logical directory specified to 607.Fn fts_open , 608i.e., the arguments specified to 609.Fn fts_open . 610Otherwise, if the 611.Vt FTSENT 612structure most recently returned by 613.Fn fts_read 614is not a directory being visited in pre-order, 615or the directory does not contain any files, 616.Fn fts_children 617returns 618.Dv NULL 619and sets 620.Va errno 621to zero. 622If an error occurs, 623.Fn fts_children 624returns 625.Dv NULL 626and sets 627.Va errno 628appropriately. 629.Pp 630The 631.Vt FTSENT 632structures returned by 633.Fn fts_children 634may be overwritten after a call to 635.Fn fts_children , 636.Fn fts_close 637or 638.Fn fts_read 639on the same file hierarchy stream. 640.Pp 641.Em Option 642may be set to the following value: 643.Bl -tag -width FTS_NAMEONLY 644.It Dv FTS_NAMEONLY 645Only the names of the files are needed. 646The contents of all the fields in the returned linked list of structures 647are undefined with the exception of the 648.Fa fts_name 649and 650.Fa fts_namelen 651fields. 652.El 653.Sh FTS_SET 654The function 655.Fn fts_set 656allows the user application to determine further processing for the 657file 658.Fa f 659of the stream 660.Fa ftsp . 661The 662.Fn fts_set 663function 664returns 0 on success, and \-1 if an error occurs. 665.Em Option 666must be set to one of the following values: 667.Bl -tag -width FTS_PHYSICAL 668.It Dv FTS_AGAIN 669Re-visit the file; any file type may be re-visited. 670The next call to 671.Fn fts_read 672will return the referenced file. 673The 674.Fa fts_stat 675and 676.Fa fts_info 677fields of the structure will be reinitialized at that time, 678but no other fields will have been changed. 679This option is meaningful only for the most recently returned 680file from 681.Fn fts_read . 682Normal use is for post-order directory visits, where it causes the 683directory to be re-visited (in both pre and post-order) as well as all 684of its descendants. 685.It Dv FTS_FOLLOW 686The referenced file must be a symbolic link. 687If the referenced file is the one most recently returned by 688.Fn fts_read , 689the next call to 690.Fn fts_read 691returns the file with the 692.Fa fts_info 693and 694.Fa fts_statp 695fields reinitialized to reflect the target of the symbolic link instead 696of the symbolic link itself. 697If the file is one of those most recently returned by 698.Fn fts_children , 699the 700.Fa fts_info 701and 702.Fa fts_statp 703fields of the structure, when returned by 704.Fn fts_read , 705will reflect the target of the symbolic link instead of the symbolic link 706itself. 707In either case, if the target of the symbolic link does not exist the 708fields of the returned structure will be unchanged and the 709.Fa fts_info 710field will be set to 711.Dv FTS_SLNONE . 712.Pp 713If the target of the link is a directory, the pre-order return, followed 714by the return of all of its descendants, followed by a post-order return, 715is done. 716.It Dv FTS_SKIP 717No descendants of this file are visited. 718The file may be one of those most recently returned by either 719.Fn fts_children 720or 721.Fn fts_read . 722.El 723.Sh FTS_CLOSE 724The 725.Fn fts_close 726function closes a file hierarchy stream 727.Fa ftsp 728and restores the current directory to the directory from which 729.Fn fts_open 730was called to open 731.Fa ftsp . 732The 733.Fn fts_close 734function 735returns 0 on success, and \-1 if an error occurs. 736.Sh ERRORS 737The function 738.Fn fts_open 739may fail and set 740.Va errno 741for any of the errors specified for the library functions 742.Xr open 2 743and 744.Xr malloc 3 . 745.Pp 746The function 747.Fn fts_close 748may fail and set 749.Va errno 750for any of the errors specified for the library functions 751.Xr chdir 2 752and 753.Xr close 2 . 754.Pp 755The functions 756.Fn fts_read 757and 758.Fn fts_children 759may fail and set 760.Va errno 761for any of the errors specified for the library functions 762.Xr chdir 2 , 763.Xr malloc 3 , 764.Xr opendir 3 , 765.Xr readdir 3 766and 767.Xr stat 2 . 768.Pp 769In addition, 770.Fn fts_children , 771.Fn fts_open 772and 773.Fn fts_set 774may fail and set 775.Va errno 776as follows: 777.Bl -tag -width Er 778.It Bq Er EINVAL 779The options were invalid, or the list were empty. 780.El 781.Sh SEE ALSO 782.Xr find 1 , 783.Xr chdir 2 , 784.Xr stat 2 , 785.Xr ftw 3 , 786.Xr qsort 3 787.Sh HISTORY 788The 789.Nm 790interface was first introduced in 791.Bx 4.4 . 792The 793.Fn fts_get_clientptr , 794.Fn fts_get_stream , 795and 796.Fn fts_set_clientptr 797functions were introduced in 798.Fx 5.0 , 799principally to provide for alternative interfaces to the 800.Nm 801functionality using different data structures. 802.Sh BUGS 803The 804.Fn fts_open 805function will automatically set the 806.Dv FTS_NOCHDIR 807option if the 808.Dv FTS_LOGICAL 809option is provided, or if it cannot 810.Xr open 2 811the current directory. 812