1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH FTW 3C "Jan 30, 2007"
  13 .SH NAME
  14 ftw, nftw \- walk a file tree
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <ftw.h>
  19 
  20 \fBint\fR \fBftw\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR (*\fIfn\fR) (\fBconst char *\fR,
  21      \fBconst struct stat *\fR, \fBint\fR), \fBint\fR \fIdepth\fR);
  22 .fi
  23 
  24 .LP
  25 .nf
  26 \fBint\fR \fBnftw\fR(\fBconst char *\fR\fIpath\fR, \fBint (*\fR\fIfn\fR) (\fBconst char *\fR,
  27      \fBconst struct stat *\fR, \fBint\fR, \fBstruct FTW *\fR), \fBint\fR \fIdepth\fR,
  28      \fBint\fR \fIflags\fR);
  29 .fi
  30 
  31 .SH DESCRIPTION
  32 .sp
  33 .LP
  34 The \fBftw()\fR function recursively descends the directory hierarchy rooted in
  35 \fIpath\fR. For each object in the hierarchy, \fBftw()\fR calls the
  36 user-defined function \fIfn\fR, passing it a pointer to a null-terminated
  37 character string containing the name of the object, a pointer to a \fBstat\fR
  38 structure (see \fBstat\fR(2)) containing information about the object, and an
  39 integer. Possible values of the integer, defined in the <\fBftw.h\fR> header,
  40 are:
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBFTW_F\fR\fR
  45 .ad
  46 .RS 11n
  47 The object is a file.
  48 .RE
  49 
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBFTW_D\fR\fR
  54 .ad
  55 .RS 11n
  56 The object is a directory.
  57 .RE
  58 
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBFTW_DNR\fR\fR
  63 .ad
  64 .RS 11n
  65 The object is a directory that cannot be read. Descendants of the directory are
  66 not processed.
  67 .RE
  68 
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBFTW_NS\fR\fR
  73 .ad
  74 .RS 11n
  75 The \fBstat()\fR function failed on the object because of lack of appropriate
  76 permission or the object is a symbolic link that points to a non-existent file.
  77 The \fBstat\fR buffer passed to \fIfn\fR is undefined.
  78 .RE
  79 
  80 .sp
  81 .LP
  82 The \fBftw()\fR function visits a directory before visiting any of its
  83 descendants.
  84 .sp
  85 .LP
  86 The tree traversal continues until the tree is exhausted, an invocation of
  87 \fIfn\fR returns a non-zero value, or some error is detected within \fBftw()\fR
  88 (such as an I/O error). If the tree is exhausted, \fBftw()\fR returns \fB0\fR.
  89 If \fIfn\fR returns a non-zero value, \fBftw()\fR stops its tree traversal and
  90 returns whatever value was returned by \fIfn\fR.
  91 .sp
  92 .LP
  93 The  \fBnftw()\fR function is similar to \fBftw()\fR except that it takes the
  94 additional argument \fIflags\fR, which is a bitwise-inclusive OR of zero or
  95 more of the following flags:
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBFTW_CHDIR\fR\fR
 100 .ad
 101 .RS 13n
 102 If set, \fBnftw()\fR changes the current working directory to each directory as
 103 it reports files in that directory. If clear, \fBnftw()\fR does not change the
 104 current working directory.
 105 .RE
 106 
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBFTW_DEPTH\fR\fR
 111 .ad
 112 .RS 13n
 113 If set, \fBnftw()\fR reports all files in a directory before reporting the
 114 directory itself. If clear, \fBnftw()\fR reports any directory before reporting
 115 the files in that directory.
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBFTW_MOUNT\fR\fR
 122 .ad
 123 .RS 13n
 124 If set, \fBnftw()\fR reports only files in the same file system as path. If
 125 clear, \fBnftw()\fR reports all files encountered during the walk.
 126 .RE
 127 
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBFTW_PHYS\fR\fR
 132 .ad
 133 .RS 13n
 134 If set, \fBnftw()\fR performs a physical walk and does not follow symbolic
 135 links.
 136 .RE
 137 
 138 .sp
 139 .LP
 140 If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is set, \fBnftw()\fR follows
 141 links instead of reporting them, but does not report any directory that would
 142 be a descendant of itself. If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is
 143 clear, \fBnftw()\fR follows links instead of reporting them, but does not
 144 report the contents of any directory that would be a descendant of itself.
 145 .sp
 146 .LP
 147 At each file it encounters, \fBnftw()\fR calls the user-supplied function
 148 \fIfn\fR with four arguments:
 149 .RS +4
 150 .TP
 151 .ie t \(bu
 152 .el o
 153 The first argument is the pathname of the object.
 154 .RE
 155 .RS +4
 156 .TP
 157 .ie t \(bu
 158 .el o
 159 The second argument is a pointer to the \fBstat\fR buffer containing
 160 information on the object.
 161 .RE
 162 .RS +4
 163 .TP
 164 .ie t \(bu
 165 .el o
 166 The third argument is an integer giving additional information. Its value is
 167 one of the following:
 168 .RS
 169 
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBFTW_F\fR\fR
 174 .ad
 175 .RS 11n
 176 The object is a file.
 177 .RE
 178 
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBFTW_D\fR\fR
 183 .ad
 184 .RS 11n
 185 The object is a directory.
 186 .RE
 187 
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBFTW_DP\fR\fR
 192 .ad
 193 .RS 11n
 194 The object is a directory and subdirectories have been visited. (This condition
 195 only occurs if the FTW_DEPTH flag is included in flags.)
 196 .RE
 197 
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBFTW_SL\fR\fR
 202 .ad
 203 .RS 11n
 204 The object is a symbolic link. (This condition only occurs if the FTW_PHYS flag
 205 is included in flags.)
 206 .RE
 207 
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBFTW_SLN\fR\fR
 212 .ad
 213 .RS 11n
 214 The object is a symbolic link that points to a non-existent file. (This
 215 condition only occurs if the FTW_PHYS flag is not included in flags.)
 216 .RE
 217 
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBFTW_DNR\fR\fR
 222 .ad
 223 .RS 11n
 224 The object is a directory that cannot be read.  The user-defined function
 225 \fIfn\fR will not be called for any of its descendants.
 226 .RE
 227 
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fBFTW_NS\fR\fR
 232 .ad
 233 .RS 11n
 234 The \fBstat()\fR function failed on the object because of lack of appropriate
 235 permission. The stat buffer passed to \fIfn\fR is undefined.  Failure of
 236 \fBstat()\fR for any other reason is considered an error and \fBnftw()\fR
 237 returns \(mi1.
 238 .RE
 239 
 240 .RE
 241 
 242 .RE
 243 .RS +4
 244 .TP
 245 .ie t \(bu
 246 .el o
 247 The fourth argument is a pointer to an \fBFTW\fR structure that contains the
 248 following members:
 249 .sp
 250 .in +2
 251 .nf
 252 int   quit;
 253 int   base;
 254 int   level;
 255 .fi
 256 .in -2
 257 
 258 The \fBquit\fR member has a default value of \fI0\fR, but can be set to the
 259 following values:
 260 .RS
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBFTW_SKIP\fR\fR or \fB\fBFTW_PRUNE\fR\fR
 266 .ad
 267 .RS 11n
 268 This object and its descendants are pruned from the search.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBFTW_FOLLOW\fR\fR
 275 .ad
 276 .RS 11n
 277 If this object is a symbolic link, follow the link to its physical counterpart.
 278 .RE
 279 
 280 .sp
 281 The \fBbase\fR member is the offset of the object's filename in the pathname
 282 passed as the first argument to \fIfn\fR(). The value of \fBlevel\fR indicates
 283 the depth relative to the root of the walk, where the root level is 0.
 284 .sp
 285 The results are unspecified if the application-supplied \fIfn\fR() function
 286 does not preserve the current working directory.
 287 .RE
 288 .sp
 289 .LP
 290 Both \fBftw()\fR and \fBnftw()\fR use one file descriptor for each level in the
 291 tree. The \fIdepth\fR argument limits the number of file descriptors used. If
 292 \fIdepth\fR is zero or negative, the effect is the same as if it were 1. It
 293 must not be greater than the number of file descriptors currently available for
 294 use.  The \fBftw()\fR function runs faster if \fIdepth\fR is at least as large
 295 as the number of levels in the tree. Both \fBftw()\fR and \fBnftw()\fR are able
 296 to descend to arbitrary depths in a file hierarchy and do not fail due to path
 297 length limitations unless either the length of the path name pointed to by the
 298 \fIpath\fR argument exceeds {\fBPATH_MAX\fR} requirements, or for \fBftw()\fR,
 299 the specified depth is less than 2, or for \fBnftw()\fR, the specified depth is
 300 less than 2 and \fBFTW_CHDIR\fR is not set. When \fBftw()\fR and \fBnftw()\fR
 301 return, they close any file descriptors they have opened; they do not close any
 302 file descriptors that might have been opened by \fIfn\fR.
 303 .SH RETURN VALUES
 304 .sp
 305 .LP
 306 If the tree is exhausted, \fBftw()\fR and \fBnftw()\fR return \fB0\fR. If the
 307 function pointed to by \fIfn\fR returns a non-zero value, \fBftw()\fR and
 308 \fBnftw()\fR stop their tree traversal and return whatever value was returned
 309 by the function pointed to by \fIfn\fR. If \fBftw()\fR and \fBnftw()\fR detect
 310 an error,  they return \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
 311 .sp
 312 .LP
 313 If \fBftw()\fR and \fBnftw()\fR encounter an error other than \fBEACCES\fR (see
 314 \fBFTW_DNR\fR and \fBFTW_NS\fR above),  they return \fB\(mi1\fR and set
 315 \fBerrno\fR to indicate the error. The external variable \fBerrno\fR can
 316 contain any error value that is possible when a directory is opened or when one
 317 of the \fBstat\fR functions is executed on a directory or file.
 318 .SH ERRORS
 319 .sp
 320 .LP
 321 The \fBftw()\fR and \fBnftw()\fR functions will fail if:
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fBELOOP\fR\fR
 326 .ad
 327 .RS 16n
 328 A loop exists in symbolic links encountered during resolution of the \fIpath\fR
 329 argument
 330 .RE
 331 
 332 .sp
 333 .ne 2
 334 .na
 335 \fB\fBENAMETOOLONG\fR\fR
 336 .ad
 337 .RS 16n
 338 The length of the path name pointed to by the \fIpath\fR argument exceeds
 339 {\fBPATH_MAX\fR}, or a path name component is longer than {\fBNAME_MAX\fR}.
 340 .RE
 341 
 342 .sp
 343 .ne 2
 344 .na
 345 \fB\fBENOENT\fR\fR
 346 .ad
 347 .RS 16n
 348 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
 349 empty string.
 350 .RE
 351 
 352 .sp
 353 .ne 2
 354 .na
 355 \fB\fBENOTDIR\fR\fR
 356 .ad
 357 .RS 16n
 358 A component of \fIpath\fR is not a directory.
 359 .RE
 360 
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fBEOVERFLOW\fR\fR
 365 .ad
 366 .RS 16n
 367 A field in the \fBstat\fR structure cannot be represented correctly in the
 368 current programming environment for one or more files found in the file
 369 hierarchy.
 370 .RE
 371 
 372 .sp
 373 .LP
 374 The \fBftw()\fR function will fail if:
 375 .sp
 376 .ne 2
 377 .na
 378 \fB\fBEACCES\fR\fR
 379 .ad
 380 .RS 16n
 381 Search permission is denied for any component of \fIpath\fR or read permission
 382 is denied for \fIpath\fR.
 383 .RE
 384 
 385 .sp
 386 .ne 2
 387 .na
 388 \fB\fBENAMETOOLONG\fR\fR
 389 .ad
 390 .RS 16n
 391 The \fBftw()\fR function has descended to a path that exceeds {\fBPATH_MAX\fR}
 392 and the depth argument specified by the application is less than 2 and
 393 \fBFTW_CHDIR\fR is not set.
 394 .RE
 395 
 396 .sp
 397 .LP
 398 The \fBnftw()\fR function will fail if:
 399 .sp
 400 .ne 2
 401 .na
 402 \fB\fBEACCES\fR\fR
 403 .ad
 404 .RS 10n
 405 Search permission is denied for any component of \fIpath\fR or read permission
 406 is denied for \fIpath\fR, or \fIfn\fR() returns \(mi1 and does not reset
 407 \fBerrno\fR.
 408 .RE
 409 
 410 .sp
 411 .LP
 412 The \fBnftw()\fR and \fBftw()\fR functions may fail if:
 413 .sp
 414 .ne 2
 415 .na
 416 \fB\fBELOOP\fR\fR
 417 .ad
 418 .RS 16n
 419 Too many symbolic links were encountered during resolution of the \fIpath\fR
 420 argument.
 421 .RE
 422 
 423 .sp
 424 .ne 2
 425 .na
 426 \fB\fBENAMETOOLONG\fR\fR
 427 .ad
 428 .RS 16n
 429 Pathname resolution of a symbolic link in the path name pointed to by the
 430 \fIpath\fR argument produced an intermediate result whose length exceeds
 431 {\fBPATH_MAX\fR}.
 432 .RE
 433 
 434 .sp
 435 .LP
 436 The \fBftw()\fR function may fail if:
 437 .sp
 438 .ne 2
 439 .na
 440 \fB\fBEINVAL\fR\fR
 441 .ad
 442 .RS 10n
 443 The value of the \fIdepth\fR argument is invalid.
 444 .RE
 445 
 446 .sp
 447 .LP
 448 The \fBnftw()\fR function may fail if:
 449 .sp
 450 .ne 2
 451 .na
 452 \fB\fBEMFILE\fR\fR
 453 .ad
 454 .RS 10n
 455 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
 456 process.
 457 .RE
 458 
 459 .sp
 460 .ne 2
 461 .na
 462 \fB\fBENFILE\fR\fR
 463 .ad
 464 .RS 10n
 465 Too many files are currently open in the system.
 466 .RE
 467 
 468 .sp
 469 .LP
 470 If the function pointed to by \fIfn\fR encounters system errors, \fBerrno\fR
 471 may be set accordingly.
 472 .SH EXAMPLES
 473 .LP
 474 \fBExample 1 \fRWalk a directory structure using \fBftw()\fR.
 475 .sp
 476 .LP
 477 The following example walks the current directory structure, calling the
 478 \fIfn\fR() function for every directory entry, using at most 10 file
 479 descriptors:
 480 
 481 .sp
 482 .in +2
 483 .nf
 484 #include <ftw.h>
 485 \&...
 486 if (ftw(".", fn, 10) != 0) {
 487        perror("ftw"); exit(2);
 488 }
 489 .fi
 490 .in -2
 491 
 492 .LP
 493 \fBExample 2 \fRWalk a directory structure using \fBnftw()\fR.
 494 .sp
 495 .LP
 496 The following example walks the \fB/tmp\fR directory and its subdirectories,
 497 calling the \fBnftw()\fR function for every directory entry, to a maximum of 5
 498 levels deep.
 499 
 500 .sp
 501 .in +2
 502 .nf
 503 #include <ftw.h>
 504 \&...
 505 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
 506 int nftwfunc(const char *filename, const struct stat *statptr,
 507       int fileflags, struct FTW *pfwt)
 508 {
 509       return 0;
 510 }
 511 \&...
 512 char *startpath = "/tmp";
 513 int depth = 5;
 514 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
 515 int ret;
 516 ret = nftw(startpath, nftwfunc, depth, flags);
 517 .fi
 518 .in -2
 519 
 520 .SH USAGE
 521 .sp
 522 .LP
 523 Because \fBftw()\fR and \fBnftw()\fR are recursive, they can terminate with a
 524 memory fault when applied by a thread with a small stack to very deep file
 525 structures.
 526 .sp
 527 .LP
 528 The \fBftw()\fR and \fBnftw()\fR functions allocate resources (memory, file
 529 descriptors) during their operation. If \fBftw()\fR they are forcibly
 530 terminated, such as by \fBlongjmp\fR(3C) being executed by \fIfn\fR or an
 531 interrupt routine, they will not have a chance to free those resources, so they
 532 remain permanently allocated. A safe way to handle interrupts is to store the
 533 fact that an interrupt has occurred and arrange to have \fIfn\fR return a
 534 non-zero value at its next invocation.
 535 .sp
 536 .LP
 537 The \fBftw()\fR and \fBnftw()\fR functions have transitional interfaces for
 538 64-bit file offsets.  See \fBlf64\fR(5).
 539 .sp
 540 .LP
 541 The \fBftw()\fR function is safe in multithreaded applications. The
 542 \fBnftw()\fR function is safe in multithreaded applications when the
 543 \fBFTW_CHDIR\fR flag is not set.
 544 .SH ATTRIBUTES
 545 .sp
 546 .LP
 547 See \fBattributes\fR(5) for descriptions of the following attributes:
 548 .sp
 549 
 550 .sp
 551 .TS
 552 box;
 553 c | c
 554 l | l .
 555 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 556 _
 557 Interface Stability     Standard
 558 _
 559 MT-Level        MT-Safe with exceptions
 560 .TE
 561 
 562 .SH SEE ALSO
 563 .sp
 564 .LP
 565 \fBstat\fR(2), \fBlongjmp\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5),
 566 \fBstandards\fR(5)