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