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.\" 31.Dd January 26, 2008 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 ".Fa 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 ".Dv 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 201it was returned in pre-order, i.e., with the 202.Fa fts_info 203field set to 204.Dv FTS_D . 205.It Dv FTS_ERR 206This is an error return, and the 207.Fa fts_errno 208field will be set to indicate what caused the error. 209.It Dv FTS_F 210A regular file. 211.It Dv FTS_NS 212A file for which no 213.Xr stat 2 214information was available. 215The contents of the 216.Fa fts_statp 217field are undefined. 218This is an error return, and the 219.Fa fts_errno 220field will be set to indicate what caused the error. 221.It Dv FTS_NSOK 222A file for which no 223.Xr stat 2 224information was requested. 225The contents of the 226.Fa fts_statp 227field are undefined. 228.It Dv FTS_SL 229A symbolic link. 230.It Dv FTS_SLNONE 231A symbolic link with a non-existent target. 232The contents of the 233.Fa fts_statp 234field reference the file characteristic information for the symbolic link 235itself. 236.El 237.It Fa fts_accpath 238A path for accessing the file from the current directory. 239.It Fa fts_path 240The path for the file relative to the root of the traversal. 241This path contains the path specified to 242.Fn fts_open 243as a prefix. 244.It Fa fts_pathlen 245The length of the string referenced by 246.Fa fts_path . 247.It Fa fts_name 248The name of the file. 249.It Fa fts_namelen 250The length of the string referenced by 251.Fa fts_name . 252.It Fa fts_level 253The depth of the traversal, numbered from \-1 to N, where this file 254was found. 255The 256.Vt FTSENT 257structure representing the parent of the starting point (or root) 258of the traversal is numbered 259.Dv FTS_ROOTPARENTLEVEL 260(\-1), and the 261.Vt FTSENT 262structure for the root 263itself is numbered 264.Dv FTS_ROOTLEVEL 265(0). 266.It Fa fts_errno 267Upon return of a 268.Vt FTSENT 269structure from the 270.Fn fts_children 271or 272.Fn fts_read 273functions, with its 274.Fa fts_info 275field set to 276.Dv FTS_DNR , 277.Dv FTS_ERR 278or 279.Dv FTS_NS , 280the 281.Fa fts_errno 282field contains the value of the external variable 283.Va errno 284specifying the cause of the error. 285Otherwise, the contents of the 286.Fa fts_errno 287field are undefined. 288.It Fa fts_number 289This field is provided for the use of the application program and is 290not modified by the 291.Nm 292functions. 293It is initialized to 0. 294.It Fa fts_pointer 295This field is provided for the use of the application program and is 296not modified by the 297.Nm 298functions. 299It is initialized to 300.Dv NULL . 301.It Fa fts_parent 302A pointer to the 303.Vt FTSENT 304structure referencing the file in the hierarchy 305immediately above the current file, i.e., the directory of which this 306file is a member. 307A parent structure for the initial entry point is provided as well, 308however, only the 309.Fa fts_level , 310.Fa fts_bignum , 311.Fa fts_number 312and 313.Fa fts_pointer 314fields are guaranteed to be initialized. 315.It Fa fts_link 316Upon return from the 317.Fn fts_children 318function, the 319.Fa fts_link 320field points to the next structure in the NULL-terminated linked list of 321directory members. 322Otherwise, the contents of the 323.Fa fts_link 324field are undefined. 325.It Fa fts_cycle 326If a directory causes a cycle in the hierarchy (see 327.Dv FTS_DC ) , 328either because 329of a hard link between two directories, or a symbolic link pointing to a 330directory, the 331.Fa fts_cycle 332field of the structure will point to the 333.Vt FTSENT 334structure in the hierarchy that references the same file as the current 335.Vt FTSENT 336structure. 337Otherwise, the contents of the 338.Fa fts_cycle 339field are undefined. 340.It Fa fts_statp 341A pointer to 342.Xr stat 2 343information for the file. 344.El 345.Pp 346A single buffer is used for all of the paths of all of the files in the 347file hierarchy. 348Therefore, the 349.Fa fts_path 350and 351.Fa fts_accpath 352fields are guaranteed to be 353.Dv NUL Ns -terminated 354.Em only 355for the file most recently returned by 356.Fn fts_read . 357To use these fields to reference any files represented by other 358.Vt FTSENT 359structures will require that the path buffer be modified using the 360information contained in that 361.Vt FTSENT 362structure's 363.Fa fts_pathlen 364field. 365Any such modifications should be undone before further calls to 366.Fn fts_read 367are attempted. 368The 369.Fa fts_name 370field is always 371.Dv NUL Ns -terminated . 372.Pp 373Note that the use of 374.Fa fts_bignum 375is mutually exclusive with the use of 376.Fa fts_number 377or 378.Fa fts_pointer . 379.Sh FTS_OPEN 380The 381.Fn fts_open 382function takes a pointer to an array of character pointers naming one 383or more paths which make up a logical file hierarchy to be traversed. 384The array must be terminated by a 385.Dv NULL 386pointer. 387.Pp 388There are 389a number of options, at least one of which (either 390.Dv FTS_LOGICAL 391or 392.Dv FTS_PHYSICAL ) 393must be specified. 394The options are selected by 395.Em or Ns 'ing 396the following values: 397.Bl -tag -width ".Dv FTS_PHYSICAL" 398.It Dv FTS_COMFOLLOW 399This option causes any symbolic link specified as a root path to be 400followed immediately whether or not 401.Dv FTS_LOGICAL 402is also specified. 403.It Dv FTS_LOGICAL 404This option causes the 405.Nm 406routines to return 407.Vt FTSENT 408structures for the targets of symbolic links 409instead of the symbolic links themselves. 410If this option is set, the only symbolic links for which 411.Vt FTSENT 412structures 413are returned to the application are those referencing non-existent files. 414Either 415.Dv FTS_LOGICAL 416or 417.Dv FTS_PHYSICAL 418.Em must 419be provided to the 420.Fn fts_open 421function. 422.It Dv FTS_NOCHDIR 423As a performance optimization, 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 optimization, 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 ".Dv 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 ".Dv 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. 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