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