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