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