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