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