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