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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd August 13, 2026 29.Dt FTS 3 30.Os 31.Sh NAME 32.Nm fts 33.Nd traverse a file hierarchy 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In fts.h 38.Ft FTS * 39.Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)" 40.Ft FTS * 41.Fn fts_openat "int dirfd" "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)" 42.Ft FTS * 43.Fn fts_open_b "char * const *path_argv" "int options" "int (^compar)(const FTSENT * const *, const FTSENT * const *)" 44.Ft FTSENT * 45.Fn fts_read "FTS *ftsp" 46.Ft FTSENT * 47.Fn fts_children "FTS *ftsp" "int options" 48.Ft int 49.Fn fts_set "FTS *ftsp" "FTSENT *f" "int instr" 50.Ft void 51.Fn fts_set_clientptr "FTS *ftsp" "void *clientdata" 52.Ft void * 53.Fn fts_get_clientptr "FTS *ftsp" 54.Ft FTS * 55.Fn fts_get_stream "FTSENT *f" 56.Ft int 57.Fn fts_close "FTS *ftsp" 58.Sh DESCRIPTION 59The 60.Nm 61functions are provided for traversing 62.Ux 63file hierarchies. 64A simple overview is that the 65.Fn fts_open 66and 67.Fn fts_open_b 68functions return a 69.Dq handle 70on a file hierarchy, which is then supplied to 71the other 72.Nm 73functions. 74The 75.Fn fts_read 76function returns a pointer to a structure describing one of the files 77in the file hierarchy. 78The 79.Fn fts_children 80function returns a pointer to a linked list of structures, each of 81which describes one of the files contained in a directory in the 82hierarchy. 83In general, directories are visited two distinguishable times; in pre-order 84(before any of their descendants are visited) and in post-order (after all 85of their descendants have been visited). 86Files are visited once. 87It is possible to walk the hierarchy 88.Dq logically 89(ignoring symbolic links) 90or physically (visiting symbolic links), order the walk of the hierarchy or 91prune and/or re-visit portions of the hierarchy. 92.Pp 93Two structures are defined (and typedef'd) in the include file 94.In fts.h . 95The first is 96.Vt FTS , 97the structure that represents the file hierarchy itself. 98The second is 99.Vt FTSENT , 100the structure that represents a file in the file 101hierarchy. 102Normally, an 103.Vt FTSENT 104structure is returned for every file in the file 105hierarchy. 106In this manual page, 107.Dq file 108and 109.Dq Vt FTSENT No structure 110are generally 111interchangeable. 112.Pp 113The 114.Vt FTS 115structure contains space for a single pointer, which may be used to 116store application data or per-hierarchy state. 117The 118.Fn fts_set_clientptr 119and 120.Fn fts_get_clientptr 121functions may be used to set and retrieve this pointer. 122This is likely to be useful only when accessed from the sort 123comparison function, which can determine the original 124.Vt FTS 125stream of its arguments using the 126.Fn fts_get_stream 127function. 128The two 129.Li get 130functions are also available as macros of the same name. 131.Pp 132The 133.Vt FTSENT 134structure contains at least the following fields, which are 135described in greater detail below: 136.Bd -literal 137typedef struct _ftsent { 138 int fts_info; /* status for FTSENT structure */ 139 char *fts_accpath; /* access path */ 140 char *fts_path; /* root path */ 141 size_t fts_pathlen; /* strlen(fts_path) */ 142 char *fts_name; /* file name */ 143 size_t fts_namelen; /* strlen(fts_name) */ 144 long fts_level; /* depth (\-1 to N) */ 145 int fts_errno; /* file errno */ 146 long long fts_number; /* local numeric value */ 147 void *fts_pointer; /* local address value */ 148 struct ftsent *fts_parent; /* parent directory */ 149 struct ftsent *fts_link; /* next file structure */ 150 struct ftsent *fts_cycle; /* cycle structure */ 151 struct stat *fts_statp; /* stat(2) information */ 152} FTSENT; 153.Ed 154.Pp 155These fields are defined as follows: 156.Bl -tag -width "fts_namelen" 157.It Fa fts_info 158One of the following values describing the returned 159.Vt FTSENT 160structure and 161the file it represents. 162With the exception of directories without errors 163.Pq Dv FTS_D , 164all of these 165entries are terminal, that is, they will not be revisited, nor will any 166of their descendants be visited. 167.Bl -tag -width FTS_DEFAULT 168.It Dv FTS_D 169A directory being visited in pre-order. 170.It Dv FTS_DC 171A directory that causes a cycle in the tree. 172(The 173.Fa fts_cycle 174field of the 175.Vt FTSENT 176structure will be filled in as well.) 177.It Dv FTS_DEFAULT 178Any 179.Vt FTSENT 180structure that represents a file type not explicitly described 181by one of the other 182.Fa fts_info 183values. 184.It Dv FTS_DNR 185A directory which cannot be read. 186This immediately follows 187.Dv FTS_D , 188in place of 189.Dv FTS_DP , 190when the directory could not be entered, or could be entered but not 191read. 192This is an error return, and the 193.Fa fts_errno 194field will be set to indicate what caused the error. 195.It Dv FTS_DOT 196A file named 197.Ql .\& 198or 199.Ql ..\& 200which was not specified as a file name to 201.Fn fts_open 202or 203.Fn fts_open_b 204(see 205.Dv FTS_SEEDOT ) . 206.It Dv FTS_DP 207A directory being visited in post-order. 208The contents of the 209.Vt FTSENT 210structure will be unchanged from when 211the directory was visited in pre-order, except for the 212.Fa fts_info 213field. 214.It Dv FTS_ERR 215This is an error return, and the 216.Fa fts_errno 217field will be set to indicate what caused the error. 218.It Dv FTS_F 219A regular file. 220.It Dv FTS_NS 221A file for which no 222.Xr stat 2 223information was available. 224The contents of the 225.Fa fts_statp 226field are undefined. 227This is an error return, and the 228.Fa fts_errno 229field will be set to indicate what caused the error. 230.It Dv FTS_NSOK 231A file for which no 232.Xr stat 2 233information was requested. 234The contents of the 235.Fa fts_statp 236field are undefined. 237.It Dv FTS_SL 238A symbolic link. 239.It Dv FTS_SLNONE 240A symbolic link with a non-existent target. 241The contents of the 242.Fa fts_statp 243field reference the file characteristic information for the symbolic link 244itself. 245.El 246.It Fa fts_accpath 247A path for accessing the file from the current directory. 248.It Fa fts_path 249The path for the file relative to the root of the traversal. 250This path contains the path specified to 251.Fn fts_open 252or 253.Fn fts_open_b 254as a prefix. 255.It Fa fts_pathlen 256The length of the string referenced by 257.Fa fts_path . 258.It Fa fts_name 259The name of the file. 260.It Fa fts_namelen 261The length of the string referenced by 262.Fa fts_name . 263.It Fa fts_level 264The depth of the traversal, numbered from \-1 to N, where this file 265was found. 266The 267.Vt FTSENT 268structure representing the parent of the starting point (or root) 269of the traversal is numbered 270.Dv FTS_ROOTPARENTLEVEL 271(\-1), and the 272.Vt FTSENT 273structure for the root 274itself is numbered 275.Dv FTS_ROOTLEVEL 276(0). 277.It Fa fts_errno 278Upon return of a 279.Vt FTSENT 280structure from the 281.Fn fts_children 282or 283.Fn fts_read 284functions, with its 285.Fa fts_info 286field set to 287.Dv FTS_DNR , 288.Dv FTS_ERR 289or 290.Dv FTS_NS , 291the 292.Fa fts_errno 293field contains the value of the external variable 294.Va errno 295specifying the cause of the error. 296Otherwise, the contents of the 297.Fa fts_errno 298field are undefined. 299.It Fa fts_number 300This field is provided for the use of the application program and is 301not modified by the 302.Nm 303functions. 304It is initialized to 0. 305.It Fa fts_pointer 306This field is provided for the use of the application program and is 307not modified by the 308.Nm 309functions. 310It is initialized to 311.Dv NULL . 312.It Fa fts_parent 313A pointer to the 314.Vt FTSENT 315structure referencing the file in the hierarchy 316immediately above the current file, i.e., the directory of which this 317file is a member. 318A parent structure for the initial entry point is provided as well, 319however, only the 320.Fa fts_level , 321.Fa fts_number , 322.Fa fts_pointer 323and 324.Fa fts_dirfd 325fields are guaranteed to be initialized. 326.It Fa fts_link 327Upon return from the 328.Fn fts_children 329function, the 330.Fa fts_link 331field points to the next structure in the NULL-terminated linked list of 332directory members. 333Otherwise, the contents of the 334.Fa fts_link 335field are undefined. 336.It Fa fts_cycle 337If a directory causes a cycle in the hierarchy (see 338.Dv FTS_DC ) , 339either because 340of a hard link between two directories, or a symbolic link pointing to a 341directory, the 342.Fa fts_cycle 343field of the structure will point to the 344.Vt FTSENT 345structure in the hierarchy that references the same file as the current 346.Vt FTSENT 347structure. 348Otherwise, the contents of the 349.Fa fts_cycle 350field are undefined. 351.It Fa fts_statp 352A pointer to 353.Xr stat 2 354information for the file. 355.It Fa fts_dirfd 356A file descriptor open on this directory entry. 357It is set only for directory entries 358.Pq Dv FTS_D 359and is \-1 for all other entry types. 360To access a file using fd-relative operations without relying 361on path-based syscalls, required in 362.Xr capsicum 4 363capability mode, use 364.Fa fts_parent->fts_dirfd 365with 366.Xr openat 2 367and 368.Fa fts_name . 369The descriptor is valid until the directory's post-order visit 370.Pq Dv FTS_DP 371and must not be closed by the caller. 372For root-level entries opened with 373.Fn fts_open , 374.Fa fts_dirfd 375is \-1. 376.El 377.Pp 378A single buffer is used for all of the paths of all of the files in the 379file hierarchy. 380Therefore, the 381.Fa fts_path 382and 383.Fa fts_accpath 384fields are guaranteed to be 385.Dv NUL Ns -terminated 386.Em only 387for the file most recently returned by 388.Fn fts_read . 389To use these fields to reference any files represented by other 390.Vt FTSENT 391structures will require that the path buffer be modified using the 392information contained in that 393.Vt FTSENT 394structure's 395.Fa fts_pathlen 396field. 397Any such modifications should be undone before further calls to 398.Fn fts_read 399are attempted. 400The 401.Fa fts_name 402field is always 403.Dv NUL Ns -terminated . 404.Ss Thread Safety 405The 406.Nm 407functions can safely be used in multi-threaded programs provided no 408two threads access the same 409.Vt FTS 410or 411.Vt FTSENT 412structure simultaneously. 413However, unless the 414.Dv FTS_NOCHDIR 415flag was passed to 416.Fn fts_open 417or 418.Fn fts_open_b , 419calls to 420.Fn fts_read 421and 422.Fn fts_children 423may change the current working directory, which will affect all 424threads. 425Conversely, changing the current working directory either during or 426between calls to 427.Fn fts_read 428or 429.Fn fts_children 430(even in a single-thread program) may cause 431.Nm 432to malfunction unless the 433.Dv FTS_NOCHDIR 434flag was passed to 435.Fn fts_open 436or 437.Fn fts_open_b 438and all paths in 439.Va path_argv 440were absolute. 441.Ss Fn fts_open 442The 443.Fn fts_open 444function takes a pointer to an array of character pointers naming one 445or more paths which make up a logical file hierarchy to be traversed. 446The array must be terminated by a 447.Dv NULL 448pointer. 449.Pp 450There are 451a number of options, at least one of which (either 452.Dv FTS_LOGICAL 453or 454.Dv FTS_PHYSICAL ) 455must be specified. 456The options are selected by 457.Em or Ns 'ing 458the following values: 459.Bl -tag -width "FTS_COMFOLLOWDIR" 460.It Dv FTS_COMFOLLOW 461This option causes any symbolic link specified as a root path to be 462followed immediately whether or not 463.Dv FTS_LOGICAL 464is also specified. 465.It Dv FTS_COMFOLLOWDIR 466This option is similar to 467.Dv FTS_COMFOLLOW , 468but only follows symbolic links to directories. 469.It Dv FTS_LOGICAL 470This option causes the 471.Nm 472routines to return 473.Vt FTSENT 474structures for the targets of symbolic links 475instead of the symbolic links themselves. 476If this option is set, the only symbolic links for which 477.Vt FTSENT 478structures 479are returned to the application are those referencing non-existent files. 480Either 481.Dv FTS_LOGICAL 482or 483.Dv FTS_PHYSICAL 484.Em must 485be provided to the 486.Fn fts_open 487function. 488.It Dv FTS_NOCHDIR 489To allow descending to arbitrary depths 490(independent of 491.Brq Dv PATH_MAX ) 492and improve performance, the 493.Nm 494functions change directories as they walk the file hierarchy. 495This has the side-effect that an application cannot rely on being 496in any particular directory during the traversal. 497The 498.Dv FTS_NOCHDIR 499option turns off this feature, and the 500.Nm 501functions will not change the current directory. 502Note that applications should not themselves change their current directory 503and try to access files unless 504.Dv FTS_NOCHDIR 505is specified and absolute 506pathnames were provided as arguments to 507.Fn fts_open . 508.It Dv FTS_NOSTAT 509By default, returned 510.Vt FTSENT 511structures reference file characteristic information (the 512.Fa statp 513field) for each file visited. 514This option relaxes that requirement as a performance optimization, 515allowing the 516.Nm 517functions to set the 518.Fa fts_info 519field to 520.Dv FTS_NSOK 521and leave the contents of the 522.Fa statp 523field undefined. 524The roots and any directories encountered during traversal 525.Po 526.Dv FTS_D , 527.Dv FTS_DC , 528.Dv FTS_DP 529.Pc 530are still fully populated. 531.It Dv FTS_NOSTAT_TYPE 532This option is similar to 533.Dv FTS_NOSTAT , 534but attempts to populate 535.Fa fts_info 536based on information from the 537.Fa d_type 538field of 539.Vt struct dirent . 540.It Dv FTS_PHYSICAL 541This option causes the 542.Nm 543routines to return 544.Vt FTSENT 545structures for symbolic links themselves instead 546of the target files they point to. 547If this option is set, 548.Vt FTSENT 549structures for all symbolic links in the 550hierarchy are returned to the application. 551Either 552.Dv FTS_LOGICAL 553or 554.Dv FTS_PHYSICAL 555.Em must 556be provided to the 557.Fn fts_open 558function. 559.It Dv FTS_SEEDOT 560By default, unless they are specified as path arguments to 561.Fn fts_open , 562any files named 563.Ql .\& 564or 565.Ql ..\& 566encountered in the file hierarchy are ignored. 567This option causes the 568.Nm 569routines to return 570.Vt FTSENT 571structures for them. 572.It Dv FTS_XDEV 573This option prevents 574.Nm 575from descending into directories that have a different device number 576than the file from which the descent began. 577.El 578.Pp 579The 580.Fa compar 581argument points to a user-defined function which may be used to order 582the traversal of the hierarchy. 583It 584takes two pointers to pointers to 585.Vt FTSENT 586structures as arguments and 587should return a negative value, zero, or a positive value to indicate 588if the file referenced by its first argument comes before, in any order 589with respect to, or after, the file referenced by its second argument. 590The 591.Fa fts_accpath , 592.Fa fts_path 593and 594.Fa fts_pathlen 595fields of the 596.Vt FTSENT 597structures may 598.Em never 599be used in this comparison. 600If the 601.Fa fts_info 602field is set to 603.Dv FTS_NS 604or 605.Dv FTS_NSOK , 606the 607.Fa fts_statp 608field may not either. 609If the 610.Fn compar 611argument is 612.Dv NULL , 613the directory traversal order is in the order listed in 614.Fa path_argv 615for the root paths, and in the order listed in the directory for 616everything else. 617.Ss Fn fts_open_b 618The 619.Fn fts_open_b 620function is identical to 621.Fn fts_open 622except that it takes a block pointer instead of a function pointer. 623The block is copied before 624.Fn fts_open_b 625returns, so the original can safely go out of scope or be released. 626.Ss Fn fts_openat 627The 628.Fn fts_openat 629function is identical to 630.Fn fts_open 631except that it accepts a file descriptor 632.Fa dirfd 633as its first argument. 634If 635.Fa dirfd 636is 637.Dv AT_FDCWD , 638the behaviour is identical to 639.Fn fts_open . 640Otherwise, 641.Fa dirfd 642must be an open file descriptor referring to a directory, 643and the traversal is rooted there. 644This allows 645.Fn fts_openat 646to be used inside Capsicum capability mode 647.Pq Xr capsicum 4 , 648where path-based operations are not permitted. 649The 650.Fn fts_openat 651function duplicates 652.Fa dirfd 653internally, so the caller may close it after 654.Fn fts_openat 655returns. 656.Ss Fn fts_read 657The 658.Fn fts_read 659function returns a pointer to an 660.Vt FTSENT 661structure describing a file in 662the hierarchy. 663Directories (that are readable and do not cause cycles) are visited at 664least twice, once in pre-order and once in post-order. 665All other files are visited at least once. 666(Hard links between directories that do not cause cycles or symbolic 667links to symbolic links may cause files to be visited more than once, 668or directories more than twice.) 669.Pp 670If all the members of the hierarchy have been returned, 671.Fn fts_read 672returns 673.Dv NULL 674and sets the external variable 675.Va errno 676to 0. 677If an error unrelated to a file in the hierarchy occurs, 678.Fn fts_read 679returns 680.Dv NULL 681and sets 682.Va errno 683appropriately. 684If an error related to a returned file occurs, a pointer to an 685.Vt FTSENT 686structure is returned, and 687.Va errno 688may or may not have been set (see 689.Fa fts_info ) . 690Note that 691.Fn fts_read 692will not set 693.Va errno 694to 0 if called again with the same 695.Fa ftsp 696argument after the 697.Dv FTS_STOP 698flag has been set or the end of the stream has been reached. 699.Pp 700The 701.Vt FTSENT 702structures returned by 703.Fn fts_read 704may be overwritten after a call to 705.Fn fts_close 706on the same file hierarchy stream, or, after a call to 707.Fn fts_read 708on the same file hierarchy stream unless they represent a file of type 709directory, in which case they will not be overwritten until after a call to 710.Fn fts_read 711after the 712.Vt FTSENT 713structure has been returned by the 714.Fn fts_read 715function in post-order. 716.Ss Fn fts_children 717The 718.Fn fts_children 719function returns a pointer to an 720.Vt FTSENT 721structure describing the first entry in a NULL-terminated linked list of 722the files in the directory represented by the 723.Vt FTSENT 724structure most recently returned by 725.Fn fts_read . 726The list is linked through the 727.Fa fts_link 728field of the 729.Vt FTSENT 730structure, and is ordered by the user-specified comparison function, if any. 731Repeated calls to 732.Fn fts_children 733will recreate this linked list. 734.Pp 735As a special case, if 736.Fn fts_read 737has not yet been called for a hierarchy, 738.Fn fts_children 739will return a pointer to the files in the logical directory specified to 740.Fn fts_open 741or 742.Fn fts_open_b , 743i.e., the arguments specified to 744.Fn fts_open 745or 746.Fn fts_open_b . 747Otherwise, if the 748.Vt FTSENT 749structure most recently returned by 750.Fn fts_read 751is not a directory being visited in pre-order, 752or the directory does not contain any files, 753.Fn fts_children 754returns 755.Dv NULL 756and sets 757.Va errno 758to zero. 759If an error occurs, 760.Fn fts_children 761returns 762.Dv NULL 763and sets 764.Va errno 765appropriately. 766.Pp 767The 768.Vt FTSENT 769structures returned by 770.Fn fts_children 771may be overwritten after a call to 772.Fn fts_children , 773.Fn fts_close 774or 775.Fn fts_read 776on the same file hierarchy stream. 777.Pp 778.Em Option 779may be set to the following value: 780.Bl -tag -width FTS_NAMEONLY 781.It Dv FTS_NAMEONLY 782Only the names of the files are needed. 783The contents of all the fields in the returned linked list of structures 784are undefined with the exception of the 785.Fa fts_name 786and 787.Fa fts_namelen 788fields. 789.El 790.Ss Fn fts_set 791The 792.Fn fts_set 793function allows the user application to determine further processing 794for the file 795.Fa f 796of the stream 797.Fa ftsp . 798The 799.Fn fts_set 800function 801returns 0 on success, and \-1 if an error occurs. 802Its 803.Fa instr 804argument must have one of the following values: 805.Bl -tag -width FTS_PHYSICAL 806.It Dv FTS_AGAIN 807Re-visit the file; any file type may be re-visited. 808The next call to 809.Fn fts_read 810will return the referenced file. 811The 812.Fa fts_stat 813and 814.Fa fts_info 815fields of the structure will be reinitialized at that time, 816but no other fields will have been changed. 817This option is meaningful only for the most recently returned 818file from 819.Fn fts_read . 820Normal use is for post-order directory visits, where it causes the 821directory to be re-visited (in both pre and post-order) as well as all 822of its descendants. 823.It Dv FTS_FOLLOW 824The referenced file must be a symbolic link. 825If the referenced file is the one most recently returned by 826.Fn fts_read , 827the next call to 828.Fn fts_read 829returns the file with the 830.Fa fts_info 831and 832.Fa fts_statp 833fields reinitialized to reflect the target of the symbolic link instead 834of the symbolic link itself. 835If the file is one of those most recently returned by 836.Fn fts_children , 837the 838.Fa fts_info 839and 840.Fa fts_statp 841fields of the structure, when returned by 842.Fn fts_read , 843will reflect the target of the symbolic link instead of the symbolic link 844itself. 845In either case, if the target of the symbolic link does not exist the 846fields of the returned structure will be unchanged and the 847.Fa fts_info 848field will be set to 849.Dv FTS_SLNONE . 850.Pp 851If the target of the link is a directory, the pre-order return, followed 852by the return of all of its descendants, followed by a post-order return, 853is done. 854.It Dv FTS_SKIP 855No descendants of this file are visited. 856The file may be one of those most recently returned by either 857.Fn fts_children 858or 859.Fn fts_read . 860.El 861.Ss Fn fts_set_clientptr , Fn fts_get_clientptr 862The 863.Fn fts_set_clientptr 864function sets the client data pointer for the stream 865.Fa ftsp 866to 867.Fa clientdata . 868The 869.Fn fts_get_clientptr 870function returns the client data pointer associated with 871.Fa ftsp . 872This can be used to pass per-stream data to the comparison function. 873.Pp 874For performance reasons, 875.Fn fts_get_clientptr 876may be shadowed by a preprocessor macro. 877.Ss Fn fts_get_stream 878The 879.Fn fts_get_stream 880function returns the 881.Nm 882stream associated with the file entry 883.Fa f . 884A typical use for this would be for a comparison function to first call 885.Fn fts_get_stream 886on one of its arguments, then call 887.Fn fts_get_clientptr 888to obtain the client data pointer, which in turn points to information 889necessary to correctly order the two entries. 890.Pp 891For performance reasons, 892.Fn fts_get_stream 893may be shadowed by a preprocessor macro. 894.Ss Fn fts_close 895The 896.Fn fts_close 897function closes a file hierarchy stream 898.Fa ftsp 899and restores the current directory to the directory from which 900.Fn fts_open 901or 902.Fn fts_open_b 903was called to open 904.Fa ftsp . 905.Sh RETURN VALUES 906The 907.Fn fts_open 908and 909.Fn fts_open_b 910functions return a pointer to the new 911.Nm 912stream on success and 913.Dv NULL 914on failure. 915.Pp 916The 917.Fn fts_read 918function returns a pointer to the next file entry on success, or if an 919error occurs that relates specifically to that file entry. 920On reaching the end of the file hierarchy, it returns 921.Dv NULL 922and sets the external variable 923.Va errno 924to 0. 925On failure, it returns 926.Dv NULL 927and sets 928.Va errno 929to an appropriate non-zero value. 930If called again after the 931.Dv FTS_STOP 932flag has been set or the end of the stream has been reached, 933.Fn fts_read 934returns 935.Dv NULL 936and leaves 937.Va errno 938untouched. 939.Pp 940The 941.Fn fts_children 942function returns a pointer to a linked list of file entries on 943success. 944On reaching the end of the file hierarchy, it returns 945.Dv NULL 946and sets the external variable 947.Va errno 948to 0. 949On failure, it returns 950.Dv NULL 951and sets 952.Va errno 953to an appropriate non-zero value. 954.Pp 955The 956.Fn fts_set 957function returns 0 on success and \-1 if its 958.Fa instr 959argument is invalid. 960.Pp 961The 962.Fn fts_get_clientptr 963function returns the client data pointer associated with its argument, 964or 965.Dv NULL 966if none has been set. 967.Pp 968The 969.Fn fts_get_stream 970function returns a pointer to the 971.Nm 972stream associated with its argument. 973.Pp 974The 975.Fn fts_close 976function 977returns 0 on success, and \-1 if an error occurs. 978.Sh ERRORS 979The 980.Fn fts_open 981and 982.Fn fts_open_b 983functions may fail and set 984.Va errno 985for any of the errors specified for the library functions 986.Xr open 2 987and 988.Xr malloc 3 . 989The 990.Fn fts_open_b 991function may also fail and set 992.Va errno 993to 994.Dv ENOSYS 995if the blocks runtime is missing. 996.Pp 997The 998.Fn fts_close 999function may fail and set 1000.Va errno 1001for any of the errors specified for the library functions 1002.Xr chdir 2 1003and 1004.Xr close 2 . 1005.Pp 1006The 1007.Fn fts_read 1008and 1009.Fn fts_children 1010functions may fail and set 1011.Va errno 1012for any of the errors specified for the library functions 1013.Xr chdir 2 , 1014.Xr malloc 3 , 1015.Xr opendir 3 , 1016.Xr readdir 3 1017and 1018.Xr stat 2 . 1019.Pp 1020In addition, the 1021.Fn fts_children , 1022.Fn fts_open , 1023and 1024.Fn fts_set 1025functions may fail and set 1026.Va errno 1027as follows: 1028.Bl -tag -width Er 1029.It Bq Er EINVAL 1030The options were invalid, or the list was empty. 1031.El 1032.Sh SEE ALSO 1033.Xr find 1 , 1034.Xr chdir 2 , 1035.Xr stat 2 , 1036.Xr ftw 3 , 1037.Xr qsort 3 1038.Sh HISTORY 1039The 1040.Nm 1041interface was first introduced in 1042.Bx 4.4 . 1043The 1044.Fn fts_get_clientptr , 1045.Fn fts_get_stream , 1046and 1047.Fn fts_set_clientptr 1048functions were introduced in 1049.Fx 5.0 , 1050principally to provide for alternative interfaces to the 1051.Nm 1052functionality using different data structures. 1053Blocks support and the 1054.Dv FTS_COMFOLLOWDIR 1055and 1056.Dv FTS_NOSTAT 1057options were added in 1058.Fx 15.0 1059based on similar functionality in macOS. 1060.Sh BUGS 1061The 1062.Fn fts_open 1063function will automatically set the 1064.Dv FTS_NOCHDIR 1065option if the 1066.Dv FTS_LOGICAL 1067option is provided, or if it cannot 1068.Xr open 2 1069the current directory. 1070