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