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