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