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