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