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