share/man/man3c/ftw.3c

   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   base;
 253 int   level;
 254 .fi
 255 .in -2
 256
 257 The \fBbase\fR member is the offset of the object's filename in the pathname
 258 passed as the first argument to \fIfn\fR(). The value of \fBlevel\fR indicates
 259 the depth relative to the root of the walk, where the root level is 0.
 260 .sp
 261 The results are unspecified if the application-supplied \fIfn\fR() function
 262 does not preserve the current working directory.
 263 .RE
 264 .sp
 265 .LP
 266 Both \fBftw()\fR and \fBnftw()\fR use one file descriptor for each level in the
 267 tree. The \fIdepth\fR argument limits the number of file descriptors used. If
 268 \fIdepth\fR is zero or negative, the effect is the same as if it were 1. It
 269 must not be greater than the number of file descriptors currently available for
 270 use.  The \fBftw()\fR function runs faster if \fIdepth\fR is at least as large
 271 as the number of levels in the tree. Both \fBftw()\fR and \fBnftw()\fR are able
 272 to descend to arbitrary depths in a file hierarchy and do not fail due to path
 273 length limitations unless either the length of the path name pointed to by the
 274 \fIpath\fR argument exceeds {\fBPATH_MAX\fR} requirements, or for \fBftw()\fR,
 275 the specified depth is less than 2, or for \fBnftw()\fR, the specified depth is
 276 less than 2 and \fBFTW_CHDIR\fR is not set. When \fBftw()\fR and \fBnftw()\fR
 277 return, they close any file descriptors they have opened; they do not close any
 278 file descriptors that might have been opened by \fIfn\fR.
 279 .SH RETURN VALUES
 280 .sp
 281 .LP
 282 If the tree is exhausted, \fBftw()\fR and \fBnftw()\fR return \fB0\fR. If the
 283 function pointed to by \fIfn\fR returns a non-zero value, \fBftw()\fR and
 284 \fBnftw()\fR stop their tree traversal and return whatever value was returned
 285 by the function pointed to by \fIfn\fR. If \fBftw()\fR and \fBnftw()\fR detect
 286 an error,  they return \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
 287 .sp
 288 .LP
 289 If \fBftw()\fR and \fBnftw()\fR encounter an error other than \fBEACCES\fR (see
 290 \fBFTW_DNR\fR and \fBFTW_NS\fR above),  they return \fB\(mi1\fR and set
 291 \fBerrno\fR to indicate the error. The external variable \fBerrno\fR can
 292 contain any error value that is possible when a directory is opened or when one
 293 of the \fBstat\fR functions is executed on a directory or file.
 294 .SH ERRORS
 295 .sp
 296 .LP
 297 The \fBftw()\fR and \fBnftw()\fR functions will fail if:
 298 .sp
 299 .ne 2
 300 .na
 301 \fB\fBELOOP\fR\fR
 302 .ad
 303 .RS 16n
 304 A loop exists in symbolic links encountered during resolution of the \fIpath\fR
 305 argument
 306 .RE
 307
 308 .sp
 309 .ne 2
 310 .na
 311 \fB\fBENAMETOOLONG\fR\fR
 312 .ad
 313 .RS 16n
 314 The length of the path name pointed to by the \fIpath\fR argument exceeds
 315 {\fBPATH_MAX\fR}, or a path name component is longer than {\fBNAME_MAX\fR}.
 316 .RE
 317
 318 .sp
 319 .ne 2
 320 .na
 321 \fB\fBENOENT\fR\fR
 322 .ad
 323 .RS 16n
 324 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
 325 empty string.
 326 .RE
 327
 328 .sp
 329 .ne 2
 330 .na
 331 \fB\fBENOTDIR\fR\fR
 332 .ad
 333 .RS 16n
 334 A component of \fIpath\fR is not a directory.
 335 .RE
 336
 337 .sp
 338 .ne 2
 339 .na
 340 \fB\fBEOVERFLOW\fR\fR
 341 .ad
 342 .RS 16n
 343 A field in the \fBstat\fR structure cannot be represented correctly in the
 344 current programming environment for one or more files found in the file
 345 hierarchy.
 346 .RE
 347
 348 .sp
 349 .LP
 350 The \fBftw()\fR function will fail if:
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fBEACCES\fR\fR
 355 .ad
 356 .RS 16n
 357 Search permission is denied for any component of \fIpath\fR or read permission
 358 is denied for \fIpath\fR.
 359 .RE
 360
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fBENAMETOOLONG\fR\fR
 365 .ad
 366 .RS 16n
 367 The \fBftw()\fR function has descended to a path that exceeds {\fBPATH_MAX\fR}
 368 and the depth argument specified by the application is less than 2 and
 369 \fBFTW_CHDIR\fR is not set.
 370 .RE
 371
 372 .sp
 373 .LP
 374 The \fBnftw()\fR function will fail if:
 375 .sp
 376 .ne 2
 377 .na
 378 \fB\fBEACCES\fR\fR
 379 .ad
 380 .RS 10n
 381 Search permission is denied for any component of \fIpath\fR or read permission
 382 is denied for \fIpath\fR, or \fIfn\fR() returns \(mi1 and does not reset
 383 \fBerrno\fR.
 384 .RE
 385
 386 .sp
 387 .LP
 388 The \fBnftw()\fR and \fBftw()\fR functions may fail if:
 389 .sp
 390 .ne 2
 391 .na
 392 \fB\fBELOOP\fR\fR
 393 .ad
 394 .RS 16n
 395 Too many symbolic links were encountered during resolution of the \fIpath\fR
 396 argument.
 397 .RE
 398
 399 .sp
 400 .ne 2
 401 .na
 402 \fB\fBENAMETOOLONG\fR\fR
 403 .ad
 404 .RS 16n
 405 Pathname resolution of a symbolic link in the path name pointed to by the
 406 \fIpath\fR argument produced an intermediate result whose length exceeds
 407 {\fBPATH_MAX\fR}.
 408 .RE
 409
 410 .sp
 411 .LP
 412 The \fBftw()\fR function may fail if:
 413 .sp
 414 .ne 2
 415 .na
 416 \fB\fBEINVAL\fR\fR
 417 .ad
 418 .RS 10n
 419 The value of the \fIdepth\fR argument is invalid.
 420 .RE
 421
 422 .sp
 423 .LP
 424 The \fBnftw()\fR function may fail if:
 425 .sp
 426 .ne 2
 427 .na
 428 \fB\fBEMFILE\fR\fR
 429 .ad
 430 .RS 10n
 431 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
 432 process.
 433 .RE
 434
 435 .sp
 436 .ne 2
 437 .na
 438 \fB\fBENFILE\fR\fR
 439 .ad
 440 .RS 10n
 441 Too many files are currently open in the system.
 442 .RE
 443
 444 .sp
 445 .LP
 446 If the function pointed to by \fIfn\fR encounters system errors, \fBerrno\fR
 447 may be set accordingly.
 448 .SH EXAMPLES
 449 .LP
 450 \fBExample 1 \fRWalk a directory structure using \fBftw()\fR.
 451 .sp
 452 .LP
 453 The following example walks the current directory structure, calling the
 454 \fIfn\fR() function for every directory entry, using at most 10 file
 455 descriptors:
 456
 457 .sp
 458 .in +2
 459 .nf
 460 #include <ftw.h>
 461 \&...
 462 if (ftw(".", fn, 10) != 0) {
 463        perror("ftw"); exit(2);
 464 }
 465 .fi
 466 .in -2
 467
 468 .LP
 469 \fBExample 2 \fRWalk a directory structure using \fBnftw()\fR.
 470 .sp
 471 .LP
 472 The following example walks the \fB/tmp\fR directory and its subdirectories,
 473 calling the \fBnftw()\fR function for every directory entry, to a maximum of 5
 474 levels deep.
 475
 476 .sp
 477 .in +2
 478 .nf
 479 #include <ftw.h>
 480 \&...
 481 int nftwfunc(const char *, const struct stat *, int, struct FTW *);
 482 int nftwfunc(const char *filename, const struct stat *statptr,
 483       int fileflags, struct FTW *pfwt)
 484 {
 485       return 0;
 486 }
 487 \&...
 488 char *startpath = "/tmp";
 489 int depth = 5;
 490 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT;
 491 int ret;
 492 ret = nftw(startpath, nftwfunc, depth, flags);
 493 .fi
 494 .in -2
 495
 496 .SH USAGE
 497 .sp
 498 .LP
 499 Because \fBftw()\fR and \fBnftw()\fR are recursive, they can terminate with a
 500 memory fault when applied by a thread with a small stack to very deep file
 501 structures.
 502 .sp
 503 .LP
 504 The \fBftw()\fR and \fBnftw()\fR functions allocate resources (memory, file
 505 descriptors) during their operation. If \fBftw()\fR they are forcibly
 506 terminated, such as by \fBlongjmp\fR(3C) being executed by \fIfn\fR or an
 507 interrupt routine, they will not have a chance to free those resources, so they
 508 remain permanently allocated. A safe way to handle interrupts is to store the
 509 fact that an interrupt has occurred and arrange to have \fIfn\fR return a
 510 non-zero value at its next invocation.
 511 .sp
 512 .LP
 513 The \fBftw()\fR and \fBnftw()\fR functions have transitional interfaces for
 514 64-bit file offsets.  See \fBlf64\fR(5).
 515 .sp
 516 .LP
 517 The \fBftw()\fR function is safe in multithreaded applications. The
 518 \fBnftw()\fR function is safe in multithreaded applications when the
 519 \fBFTW_CHDIR\fR flag is not set.
 520 .SH ATTRIBUTES
 521 .sp
 522 .LP
 523 See \fBattributes\fR(5) for descriptions of the following attributes:
 524 .sp
 525
 526 .sp
 527 .TS
 528 box;
 529 c | c
 530 l | l .
 531 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 532 _
 533 Interface Stability     Standard
 534 _
 535 MT-Level        MT-Safe with exceptions
 536 .TE
 537
 538 .SH SEE ALSO
 539 .sp
 540 .LP
 541 \fBstat\fR(2), \fBlongjmp\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5),
 542 \fBstandards\fR(5)