man3/fts.3

   1 .\"     $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   7 .\"
   8 .\"     @(#)fts.3       8.5 (Berkeley) 4/16/94
   9 .\"
  10 .\" 2007-12-08, mtk, Converted from mdoc to man macros
  11 .\"
  12 .TH FTS 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  13 .SH NAME
  14 fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \
  15 traverse a file hierarchy
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/types.h>
  22 .B #include <sys/stat.h>
  23 .B #include <fts.h>
  24 .PP
  25 .BI "FTS *fts_open(char * const *" path_argv ", int " options ,
  26 .BI "              int (*" compar ")(const FTSENT **, const FTSENT **));"
  27 .PP
  28 .BI "FTSENT *fts_read(FTS *" ftsp );
  29 .PP
  30 .BI "FTSENT *fts_children(FTS *" ftsp ", int " instr );
  31 .PP
  32 .BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr );
  33 .PP
  34 .BI "int fts_close(FTS *" ftsp );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 fts functions are provided for traversing
  39 file hierarchies.
  40 A simple overview is that the
  41 .BR fts_open ()
  42 function returns a "handle" (of type
  43 .IR "FTS\ *" )
  44 that refers to a file hierarchy "stream".
  45 This handle is then supplied to the other
  46 fts functions.
  47 The function
  48 .BR fts_read ()
  49 returns a pointer to a structure describing one of the files in the file
  50 hierarchy.
  51 The function
  52 .BR fts_children ()
  53 returns a pointer to a linked list of structures, each of which describes
  54 one of the files contained in a directory in the hierarchy.
  55 .PP
  56 In general, directories are visited two distinguishable times; in preorder
  57 (before any of their descendants are visited) and in postorder (after all
  58 of their descendants have been visited).
  59 Files are visited once.
  60 It is possible to walk the hierarchy "logically" (visiting the files that
  61 symbolic links point to)
  62 or physically (visiting the symbolic links themselves),
  63 order the walk of the hierarchy or
  64 prune and/or revisit portions of the hierarchy.
  65 .PP
  66 Two structures (and associated types) are defined in the include file
  67 .IR <fts.h> .
  68 The first type is
  69 .IR FTS ,
  70 the structure that represents the file hierarchy itself.
  71 The second type is
  72 .IR FTSENT ,
  73 the structure that represents a file in the file
  74 hierarchy.
  75 Normally, an
  76 .I FTSENT
  77 structure is returned for every file in the file
  78 hierarchy.
  79 In this manual page, "file" and
  80 "FTSENT structure"
  81 are generally interchangeable.
  82 .PP
  83 The
  84 .I FTSENT
  85 structure contains fields describing a file.
  86 The structure contains at least the following fields
  87 (there are additional fields that
  88 should be considered private to the implementation):
  89 .PP
  90 .in +4n
  91 .EX
  92 typedef struct _ftsent {
  93     unsigned short  fts_info;     /* flags for FTSENT structure */
  94     char           *fts_accpath;  /* access path */
  95     char           *fts_path;     /* root path */
  96     short           fts_pathlen;  /* strlen(fts_path) +
  97                                      strlen(fts_name) */
  98     char           *fts_name;     /* filename */
  99     short           fts_namelen;  /* strlen(fts_name) */
 100     short           fts_level;    /* depth (\-1 to N) */
 101     int             fts_errno;    /* file errno */
 102     long            fts_number;   /* local numeric value */
 103     void           *fts_pointer;  /* local address value */
 104     struct _ftsent *fts_parent;   /* parent directory */
 105     struct _ftsent *fts_link;     /* next file structure */
 106     struct _ftsent *fts_cycle;    /* cycle structure */
 107     struct stat    *fts_statp;    /* [l]stat(2) information */
 108 .\" Also:
 109 .\"     ino_t fts_ino;                  /* inode (only for directories)*/
 110 .\"     dev_t fts_dev;                  /* device (only for directories)*/
 111 .\"     nlink_t fts_nlink;              /* link count (only for directories)*/
 112 .\"     u_short fts_flags;              /* private flags for FTSENT structure */
 113 .\"     u_short fts_instr;              /* fts_set() instructions */
 114 } FTSENT;
 115 .EE
 116 .in
 117 .PP
 118 These fields are defined as follows:
 119 .\" .Bl -tag -width "fts_namelen"
 120 .TP
 121 .I fts_info
 122 One of the following values describing the returned
 123 .I FTSENT
 124 structure and
 125 the file it represents.
 126 With the exception of directories without errors
 127 .RB ( FTS_D ),
 128 all of these
 129 entries are terminal, that is, they will not be revisited, nor will any
 130 of their descendants be visited.
 131 .\" .Bl  -tag -width FTS_DEFAULT
 132 .RS
 133 .TP
 134 .B FTS_D
 135 A directory being visited in preorder.
 136 .TP
 137 .B FTS_DC
 138 A directory that causes a cycle in the tree.
 139 (The
 140 .I fts_cycle
 141 field of the
 142 .I FTSENT
 143 structure will be filled in as well.)
 144 .TP
 145 .B FTS_DEFAULT
 146 Any
 147 .I FTSENT
 148 structure that represents a file type not explicitly described
 149 by one of the other
 150 .I fts_info
 151 values.
 152 .TP
 153 .B FTS_DNR
 154 A directory which cannot be read.
 155 This is an error return, and the
 156 .I fts_errno
 157 field will be set to indicate what caused the error.
 158 .TP
 159 .B FTS_DOT
 160 A file named
 161 "."
 162 or
 163 ".."
 164 which was not specified as a filename to
 165 .BR fts_open ()
 166 (see
 167 .BR FTS_SEEDOT ).
 168 .TP
 169 .B FTS_DP
 170 A directory being visited in postorder.
 171 The contents of the
 172 .I FTSENT
 173 structure will be unchanged from when
 174 it was returned in preorder, that is, with the
 175 .I fts_info
 176 field set to
 177 .BR FTS_D .
 178 .TP
 179 .B FTS_ERR
 180 This is an error return, and the
 181 .I fts_errno
 182 field will be set to indicate what caused the error.
 183 .TP
 184 .B FTS_F
 185 A regular file.
 186 .TP
 187 .B FTS_NS
 188 A file for which no
 189 .RB [ l ] stat (2)
 190 information was available.
 191 The contents of the
 192 .I fts_statp
 193 field are undefined.
 194 This is an error return, and the
 195 .I fts_errno
 196 field will be set to indicate what caused the error.
 197 .TP
 198 .B FTS_NSOK
 199 A file for which no
 200 .RB [ l ] stat (2)
 201 information was requested.
 202 The contents of the
 203 .I fts_statp
 204 field are undefined.
 205 .TP
 206 .B FTS_SL
 207 A symbolic link.
 208 .TP
 209 .B FTS_SLNONE
 210 A symbolic link with a nonexistent target.
 211 The contents of the
 212 .I fts_statp
 213 field reference the file characteristic information for the symbolic link
 214 itself.
 215 .\" .El
 216 .RE
 217 .TP
 218 .I fts_accpath
 219 A path for accessing the file from the current directory.
 220 .TP
 221 .I fts_path
 222 The path for the file relative to the root of the traversal.
 223 This path contains the path specified to
 224 .BR fts_open ()
 225 as a prefix.
 226 .TP
 227 .I fts_pathlen
 228 The sum of the lengths of the strings referenced by
 229 .I fts_path
 230 and
 231 .IR fts_name .
 232 .TP
 233 .I fts_name
 234 The name of the file.
 235 .TP
 236 .I fts_namelen
 237 The length of the string referenced by
 238 .IR fts_name .
 239 .TP
 240 .I fts_level
 241 The depth of the traversal, numbered from \-1 to N, where this file
 242 was found.
 243 The
 244 .I FTSENT
 245 structure representing the parent of the starting point (or root)
 246 of the traversal is numbered \-1, and the
 247 .I FTSENT
 248 structure for the root
 249 itself is numbered 0.
 250 .TP
 251 .I fts_errno
 252 If
 253 .BR fts_children ()
 254 or
 255 .BR fts_read ()
 256 returns an
 257 .I FTSENT
 258 structure whose
 259 .I fts_info
 260 field is set to
 261 .BR FTS_DNR ,
 262 .BR FTS_ERR ,
 263 or
 264 .BR FTS_NS ,
 265 the
 266 .I fts_errno
 267 field contains the error number (i.e., the
 268 .I errno
 269 value)
 270 specifying the cause of the error.
 271 Otherwise, the contents of the
 272 .I fts_errno
 273 field are undefined.
 274 .TP
 275 .I fts_number
 276 This field is provided for the use of the application program and is
 277 not modified by the
 278 fts functions.
 279 It is initialized to 0.
 280 .TP
 281 .I fts_pointer
 282 This field is provided for the use of the application program and is
 283 not modified by the
 284 fts functions.
 285 It is initialized to
 286 NULL.
 287 .TP
 288 .I fts_parent
 289 A pointer to the
 290 .I FTSENT
 291 structure referencing the file in the hierarchy
 292 immediately above the current file, that is, the directory of which this
 293 file is a member.
 294 A parent structure for the initial entry point is provided as well,
 295 however, only the
 296 .IR fts_level ,
 297 .IR fts_number ,
 298 and
 299 .I fts_pointer
 300 fields are guaranteed to be initialized.
 301 .TP
 302 .I fts_link
 303 Upon return from the
 304 .BR fts_children ()
 305 function, the
 306 .I fts_link
 307 field points to the next structure in the NULL-terminated linked list of
 308 directory members.
 309 Otherwise, the contents of the
 310 .I fts_link
 311 field are undefined.
 312 .TP
 313 .I fts_cycle
 314 If a directory causes a cycle in the hierarchy (see
 315 .BR FTS_DC ),
 316 either because
 317 of a hard link between two directories, or a symbolic link pointing to a
 318 directory, the
 319 .I fts_cycle
 320 field of the structure will point to the
 321 .I FTSENT
 322 structure in the hierarchy that references the same file as the current
 323 .I FTSENT
 324 structure.
 325 Otherwise, the contents of the
 326 .I fts_cycle
 327 field are undefined.
 328 .TP
 329 .I fts_statp
 330 A pointer to
 331 .RB [ l ] stat (2)
 332 information for the file.
 333 .\" .El
 334 .PP
 335 A single buffer is used for all of the paths of all of the files in the
 336 file hierarchy.
 337 Therefore, the
 338 .I fts_path
 339 and
 340 .I fts_accpath
 341 fields are guaranteed to be
 342 null-terminated
 343 .I only
 344 for the file most recently returned by
 345 .BR fts_read ().
 346 To use these fields to reference any files represented by other
 347 .I FTSENT
 348 structures will require that the path buffer be modified using the
 349 information contained in that
 350 .I FTSENT
 351 structure's
 352 .I fts_pathlen
 353 field.
 354 Any such modifications should be undone before further calls to
 355 .BR fts_read ()
 356 are attempted.
 357 The
 358 .I fts_name
 359 field is always
 360 null-terminated.
 361 .SS fts_open()
 362 The
 363 .BR fts_open ()
 364 function takes a pointer to an array of character pointers naming one
 365 or more paths which make up a logical file hierarchy to be traversed.
 366 The array must be terminated by a
 367 null pointer.
 368 .PP
 369 There are
 370 a number of options, at least one of which (either
 371 .B FTS_LOGICAL
 372 or
 373 .BR FTS_PHYSICAL )
 374 must be specified.
 375 The options are selected by ORing
 376 the following values:
 377 .\" .Bl -tag -width "FTS_PHYSICAL"
 378 .TP
 379 .B FTS_LOGICAL
 380 This option causes the
 381 fts routines to return
 382 .I FTSENT
 383 structures for the targets of symbolic links
 384 instead of the symbolic links themselves.
 385 If this option is set, the only symbolic links for which
 386 .I FTSENT
 387 structures
 388 are returned to the application are those referencing nonexistent files:
 389 the
 390 .I fts_statp
 391 field is obtained via
 392 .BR stat (2)
 393 with a fallback to
 394 .BR lstat (2).
 395 .TP
 396 .B FTS_PHYSICAL
 397 This option causes the
 398 fts routines to return
 399 .I FTSENT
 400 structures for symbolic links themselves instead
 401 of the target files they point to.
 402 If this option is set,
 403 .I FTSENT
 404 structures for all symbolic links in the
 405 hierarchy are returned to the application:
 406 the
 407 .I fts_statp
 408 field is obtained via
 409 .BR lstat (2).
 410 .TP
 411 .B FTS_COMFOLLOW
 412 This option causes any symbolic link specified as a root path to be
 413 followed immediately, as if via
 414 .BR FTS_LOGICAL ,
 415 regardless of the primary mode.
 416 .TP
 417 .B FTS_NOCHDIR
 418 As a performance optimization, the
 419 fts functions change directories as they walk the file hierarchy.
 420 This has the side-effect that an application cannot rely on being
 421 in any particular directory during the traversal.
 422 This
 423 option turns off this optimization, and the
 424 fts functions will not change the current directory.
 425 Note that applications should not themselves change their current directory
 426 and try to access files unless
 427 .B FTS_NOCHDIR
 428 is specified and absolute
 429 pathnames were provided as arguments to
 430 .BR fts_open ().
 431 .TP
 432 .B FTS_NOSTAT
 433 By default, returned
 434 .I FTSENT
 435 structures reference file characteristic information (the
 436 .I fts_statp
 437 field) for each file visited.
 438 This option relaxes that requirement as a performance optimization,
 439 allowing the
 440 fts functions to set the
 441 .I fts_info
 442 field to
 443 .B FTS_NSOK
 444 and leave the contents of the
 445 .I fts_statp
 446 field undefined.
 447 .TP
 448 .B FTS_SEEDOT
 449 By default, unless they are specified as path arguments to
 450 .BR fts_open (),
 451 any files named
 452 "."
 453 or
 454 ".."
 455 encountered in the file hierarchy are ignored.
 456 This option causes the
 457 fts routines to return
 458 .I FTSENT
 459 structures for them.
 460 .TP
 461 .B FTS_XDEV
 462 This option prevents
 463 fts from descending into directories that have a different device number
 464 than the file from which the descent began.
 465 .\" .El
 466 .PP
 467 The argument
 468 .BR compar ()
 469 specifies a user-defined function which may be used to order the traversal
 470 of the hierarchy.
 471 It
 472 takes two pointers to pointers to
 473 .I FTSENT
 474 structures as arguments and
 475 should return a negative value, zero, or a positive value to indicate
 476 if the file referenced by its first argument comes before, in any order
 477 with respect to, or after, the file referenced by its second argument.
 478 The
 479 .IR fts_accpath ,
 480 .IR fts_path ,
 481 and
 482 .I fts_pathlen
 483 fields of the
 484 .I FTSENT
 485 structures may
 486 .I never
 487 be used in this comparison.
 488 If the
 489 .I fts_info
 490 field is set to
 491 .B FTS_NS
 492 or
 493 .BR FTS_NSOK ,
 494 the
 495 .I fts_statp
 496 field may not either.
 497 If the
 498 .BR compar ()
 499 argument is
 500 NULL,
 501 the directory traversal order is in the order listed in
 502 .I path_argv
 503 for the root paths, and in the order listed in the directory for
 504 everything else.
 505 .SS fts_read()
 506 The
 507 .BR fts_read ()
 508 function returns a pointer to an
 509 .I FTSENT
 510 structure describing a file in
 511 the hierarchy.
 512 Directories (that are readable and do not cause cycles) are visited at
 513 least twice, once in preorder and once in postorder.
 514 All other files are visited at least once.
 515 (Hard links between directories that do not cause cycles or symbolic
 516 links to symbolic links may cause files to be visited more than once,
 517 or directories more than twice.)
 518 .PP
 519 If all the members of the hierarchy have been returned,
 520 .BR fts_read ()
 521 returns NULL and sets
 522 .I errno
 523 to 0.
 524 If an error unrelated to a file in the hierarchy occurs,
 525 .BR fts_read ()
 526 returns
 527 NULL
 528 and sets
 529 .I errno
 530 to indicate the error.
 531 If an error related to a returned file occurs, a pointer to an
 532 .I FTSENT
 533 structure is returned, and
 534 .I errno
 535 may or may not have been set (see
 536 .IR fts_info ).
 537 .PP
 538 The
 539 .I FTSENT
 540 structures returned by
 541 .BR fts_read ()
 542 may be overwritten after a call to
 543 .BR fts_close ()
 544 on the same file hierarchy stream, or, after a call to
 545 .BR 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 .BR fts_read ()
 549 after the
 550 .I FTSENT
 551 structure has been returned by the function
 552 .BR fts_read ()
 553 in postorder.
 554 .SS fts_children()
 555 The
 556 .BR fts_children ()
 557 function returns a pointer to an
 558 .I FTSENT
 559 structure describing the first entry in a NULL-terminated linked list of
 560 the files in the directory represented by the
 561 .I FTSENT
 562 structure most recently returned by
 563 .BR fts_read ().
 564 The list is linked through the
 565 .I fts_link
 566 field of the
 567 .I FTSENT
 568 structure, and is ordered by the user-specified comparison function, if any.
 569 Repeated calls to
 570 .BR fts_children ()
 571 will re-create this linked list.
 572 .PP
 573 As a special case, if
 574 .BR fts_read ()
 575 has not yet been called for a hierarchy,
 576 .BR fts_children ()
 577 will return a pointer to the files in the logical directory specified to
 578 .BR fts_open (),
 579 that is, the arguments specified to
 580 .BR fts_open ().
 581 Otherwise, if the
 582 .I FTSENT
 583 structure most recently returned by
 584 .BR fts_read ()
 585 is not a directory being visited in preorder,
 586 or the directory does not contain any files,
 587 .BR fts_children ()
 588 returns
 589 NULL
 590 and sets
 591 .I errno
 592 to zero.
 593 If an error occurs,
 594 .BR fts_children ()
 595 returns
 596 NULL
 597 and sets
 598 .I errno
 599 to indicate the error.
 600 .PP
 601 The
 602 .I FTSENT
 603 structures returned by
 604 .BR fts_children ()
 605 may be overwritten after a call to
 606 .BR fts_children (),
 607 .BR fts_close (),
 608 or
 609 .BR fts_read ()
 610 on the same file hierarchy stream.
 611 .PP
 612 The
 613 .I instr
 614 argument is either zero or the following value:
 615 .\" .Bl -tag -width FTS_NAMEONLY
 616 .TP
 617 .B FTS_NAMEONLY
 618 Only the names of the files are needed.
 619 The contents of all the fields in the returned linked list of structures
 620 are undefined with the exception of the
 621 .I fts_name
 622 and
 623 .I fts_namelen
 624 fields.
 625 .\" .El
 626 .SS fts_set()
 627 The function
 628 .BR fts_set ()
 629 allows the user application to determine further processing for the
 630 file
 631 .I f
 632 of the stream
 633 .IR ftsp .
 634 The
 635 .BR fts_set ()
 636 function
 637 returns 0 on success, and \-1 if an error occurs.
 638 .PP
 639 The
 640 .I instr
 641 argument is either 0 (meaning "do nothing") or one of the following values:
 642 .\" .Bl -tag -width FTS_PHYSICAL
 643 .TP
 644 .B FTS_AGAIN
 645 Revisit the file; any file type may be revisited.
 646 The next call to
 647 .BR fts_read ()
 648 will return the referenced file.
 649 The
 650 .I fts_stat
 651 and
 652 .I fts_info
 653 fields of the structure will be reinitialized at that time,
 654 but no other fields will have been changed.
 655 This option is meaningful only for the most recently returned
 656 file from
 657 .BR fts_read ().
 658 Normal use is for postorder directory visits, where it causes the
 659 directory to be revisited (in both preorder and postorder) as well as all
 660 of its descendants.
 661 .TP
 662 .B FTS_FOLLOW
 663 The referenced file must be a symbolic link.
 664 If the referenced file is the one most recently returned by
 665 .BR fts_read (),
 666 the next call to
 667 .BR fts_read ()
 668 returns the file with the
 669 .I fts_info
 670 and
 671 .I fts_statp
 672 fields reinitialized to reflect the target of the symbolic link instead
 673 of the symbolic link itself.
 674 If the file is one of those most recently returned by
 675 .BR fts_children (),
 676 the
 677 .I fts_info
 678 and
 679 .I fts_statp
 680 fields of the structure, when returned by
 681 .BR fts_read (),
 682 will reflect the target of the symbolic link instead of the symbolic link
 683 itself.
 684 In either case, if the target of the symbolic link does not exist, the
 685 fields of the returned structure will be unchanged and the
 686 .I fts_info
 687 field will be set to
 688 .BR FTS_SLNONE .
 689 .IP
 690 If the target of the link is a directory, the preorder return, followed
 691 by the return of all of its descendants, followed by a postorder return,
 692 is done.
 693 .TP
 694 .B FTS_SKIP
 695 No descendants of this file are visited.
 696 The file may be one of those most recently returned by either
 697 .BR fts_children ()
 698 or
 699 .BR fts_read ().
 700 .\" .El
 701 .SS fts_close()
 702 The
 703 .BR fts_close ()
 704 function closes the file hierarchy stream referred to by
 705 .I ftsp
 706 and restores the current directory to the directory from which
 707 .BR fts_open ()
 708 was called to open
 709 .IR ftsp .
 710 The
 711 .BR fts_close ()
 712 function
 713 returns 0 on success, and \-1 if an error occurs.
 714 .SH ERRORS
 715 The function
 716 .BR fts_open ()
 717 may fail and set
 718 .I errno
 719 for any of the errors specified for
 720 .BR open (2)
 721 and
 722 .BR malloc (3).
 723 .PP
 724 The function
 725 .BR fts_close ()
 726 may fail and set
 727 .I errno
 728 for any of the errors specified for
 729 .BR chdir (2)
 730 and
 731 .BR close (2).
 732 .PP
 733 The functions
 734 .BR fts_read ()
 735 and
 736 .BR fts_children ()
 737 may fail and set
 738 .I errno
 739 for any of the errors specified for
 740 .BR chdir (2),
 741 .BR malloc (3),
 742 .BR opendir (3),
 743 .BR readdir (3),
 744 and
 745 .RB [ l ] stat (2).
 746 .PP
 747 In addition,
 748 .BR fts_children (),
 749 .BR fts_open (),
 750 and
 751 .BR fts_set ()
 752 may fail and set
 753 .I errno
 754 as follows:
 755 .TP
 756 .B EINVAL
 757 .I options
 758 or
 759 .I instr
 760 was invalid.
 761 .SH VERSIONS
 762 These functions are available in Linux since glibc2.
 763 .SH ATTRIBUTES
 764 For an explanation of the terms used in this section, see
 765 .BR attributes (7).
 766 .ad l
 767 .nh
 768 .TS
 769 allbox;
 770 lbx lb lb
 771 l l l.
 772 Interface       Attribute       Value
 773 T{
 774 .BR fts_open (),
 775 .BR fts_set (),
 776 .BR fts_close ()
 777 T}      Thread safety   MT-Safe
 778 T{
 779 .BR fts_read (),
 780 .BR fts_children ()
 781 T}      Thread safety   MT-Unsafe
 782 .TE
 783 .hy
 784 .ad
 785 .sp 1
 786 .SH STANDARDS
 787 4.4BSD.
 788 .SH BUGS
 789 In versions of glibc before 2.23,
 790 .\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5
 791 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838
 792 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460
 793 all of the APIs described in this man page are not safe when compiling
 794 a program using the LFS APIs (e.g., when compiling with
 795 .IR \-D_FILE_OFFSET_BITS=64 ).
 796 .\"
 797 .\" The following statement is years old, and seems no closer to
 798 .\" being true -- mtk
 799 .\" The
 800 .\" .I fts
 801 .\" utility is expected to be included in a future
 802 .\" POSIX.1
 803 .\" revision.
 804 .SH SEE ALSO
 805 .BR find (1),
 806 .BR chdir (2),
 807 .BR lstat (2),
 808 .BR stat (2),
 809 .BR ftw (3),
 810 .BR qsort (3)