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