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