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