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