lib/libc/gen/fts.3

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