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