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