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