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