| 1 | .\" Copyright (c) 1989 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms are permitted |
| 5 | .\" provided that the above copyright notice and this paragraph are |
| 6 | .\" duplicated in all such forms and that any documentation, |
| 7 | .\" advertising materials, and other materials related to such |
| 8 | .\" distribution and use acknowledge that the software was developed |
| 9 | .\" by the University of California, Berkeley. The name of the |
| 10 | .\" University may not be used to endorse or promote products derived |
| 11 | .\" from this software without specific prior written permission. |
| 12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR |
| 13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
| 14 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 15 | .\" |
| 16 | .\" @(#)fts.3 5.1 (Berkeley) %G% |
| 17 | .\" |
| 18 | .TH FTS 3 "" |
| 19 | .UC 7 |
| 20 | .SH NAME |
| 21 | fts \- traverse a file hierarchy |
| 22 | .SH SYNOPSIS |
| 23 | .nf |
| 24 | .ft B |
| 25 | #include <sys/types.h> |
| 26 | #include <sys/stat.h> |
| 27 | #include <fts.h> |
| 28 | |
| 29 | FTS * |
| 30 | ftsopen(path, options, compar) |
| 31 | char *path; |
| 32 | int options, (*compar)(); |
| 33 | |
| 34 | FTS * |
| 35 | ftsopen(path_argv, options | FTS_MULTIPLE, compar) |
| 36 | char *path_argv[]; |
| 37 | int options, (*compar)(); |
| 38 | |
| 39 | FTSENT * |
| 40 | ftsread(ftsp); |
| 41 | FTS *ftsp; |
| 42 | |
| 43 | FTSENT * |
| 44 | ftschildren(ftsp) |
| 45 | FTS *ftsp; |
| 46 | |
| 47 | ftsset(ftsp, f, options) |
| 48 | FTS *ftsp; |
| 49 | FTSENT *f; |
| 50 | int options; |
| 51 | |
| 52 | ftsclose(ftsp) |
| 53 | FTS *ftsp; |
| 54 | .ft R |
| 55 | .fi |
| 56 | .SH DESCRIPTION |
| 57 | The |
| 58 | .IR fts (3) |
| 59 | utilities are provided for traversing UNIX file hierarchies. |
| 60 | Two structures are defined (and typedef'd) in the include file <\fIfts.h\fP>. |
| 61 | The first is FTS, the structure that defines the file hierarchy stream. |
| 62 | The second is FTSENT, the structure that defines a file in the file |
| 63 | hierarchy. |
| 64 | .PP |
| 65 | The |
| 66 | .I ftsopen |
| 67 | routine returns a pointer to a file hierarchy rooted at |
| 68 | .IR path . |
| 69 | The |
| 70 | .I options |
| 71 | specified are formed by |
| 72 | .IR or 'ing |
| 73 | one or more of the following values: |
| 74 | .TP |
| 75 | FTS_LOGICAL |
| 76 | This option causes |
| 77 | .I ftsread |
| 78 | to use the function |
| 79 | .IR stat (2), |
| 80 | by default, to determine the status of each file. |
| 81 | If this option is set, the only symbolic links returned to the application |
| 82 | are those referencing non-existent files. |
| 83 | Either FTS_LOGICAL or FTS_PHYSICAL |
| 84 | .B must |
| 85 | be provided to the |
| 86 | .I ftsopen |
| 87 | routine. |
| 88 | .TP |
| 89 | FTS_MULTIPLE |
| 90 | .I Ftsopen |
| 91 | takes a single file name as a path argument by default. |
| 92 | If the FTS_MULTIPLE option is specified, the path argument is a pointer |
| 93 | to an array of character pointers (``argv'') to the paths to be traversed. |
| 94 | The array must be terminated by a pointer to a NULL string. |
| 95 | In this case the ``logical'' hierarchy is traversed, i.e. it's as if |
| 96 | there's a virtual directory that contains the list of paths supplied, |
| 97 | and the hierarchy is rooted in that directory. |
| 98 | .TP |
| 99 | FTS_NOCHDIR |
| 100 | As a performance optimization, |
| 101 | .I ftsread |
| 102 | changes directories as it descends the hierarchy. |
| 103 | This has the side-effect that applications cannot rely on being |
| 104 | in any particular directory. |
| 105 | The FTS_NOCHDIR option turns off this optimization. |
| 106 | Note that applications should not change the current directory |
| 107 | (even if FTS_NOCHDIR is specified) unless absolute pathnames were |
| 108 | provided as arguments to |
| 109 | .IR ftsopen . |
| 110 | .TP |
| 111 | FTS_NOSTAT |
| 112 | By default, |
| 113 | .I ftsread |
| 114 | and |
| 115 | .I ftschildren |
| 116 | provide file characteristic information (the |
| 117 | .I statb |
| 118 | field) for each file they return. |
| 119 | This option relaxes that requirement; the contents of the |
| 120 | .I statb |
| 121 | field may be undefined, and the |
| 122 | .I info |
| 123 | field may be set to FTS_NS. |
| 124 | .TP |
| 125 | FTS_PHYSICAL |
| 126 | This option causes |
| 127 | .I ftsread |
| 128 | to use the function |
| 129 | .IR lstat (2), |
| 130 | by default, to determine the status of each file. |
| 131 | If this option is set, all symbolic links are returned to the application |
| 132 | program. |
| 133 | Either FTS_LOGICAL or FTS_PHYSICAL |
| 134 | .B must |
| 135 | be provided to the |
| 136 | .I ftsopen |
| 137 | routine. |
| 138 | .TP |
| 139 | FTS_SEEDOT |
| 140 | This option causes the routine |
| 141 | .I ftsread |
| 142 | to return structures for the directory entries ``.'' and ``..''. |
| 143 | By default they are ignored unless specified as an argument to |
| 144 | .IR ftsopen . |
| 145 | .PP |
| 146 | The argument |
| 147 | .I compar |
| 148 | specifies a user-defined routine which is used to order the traversal |
| 149 | of directories. |
| 150 | .I Compar |
| 151 | takes two pointers to pointers to FTSENT structures as arguments and |
| 152 | should return a negative value, zero, or a positive value to indicate |
| 153 | if the file referenced by its first argument comes before, in any order |
| 154 | with respect to, or after, the file referenced by its second argument. |
| 155 | Note, the |
| 156 | .I accpath |
| 157 | and |
| 158 | .I path |
| 159 | fields of the FTSENT structures may not be used in this comparison. |
| 160 | .PP |
| 161 | If both FTS_MULTIPLE and the user comparison routine are specified, |
| 162 | the root paths are processed in sorted order. |
| 163 | Otherwise, the root paths are processed in the order specified by |
| 164 | the user. |
| 165 | .PP |
| 166 | The |
| 167 | .I ftsclose |
| 168 | routine closes a file hierarchy stream and changes the current |
| 169 | directory to the directory |
| 170 | .I ftsopen |
| 171 | was called from. |
| 172 | .I Ftsclose |
| 173 | returns 0 on success, and -1 if an error occurs. |
| 174 | .PP |
| 175 | Each call to the |
| 176 | .I ftsread |
| 177 | routine returns a pointer to an FTSENT structure describing a file in |
| 178 | the hierarchy. |
| 179 | Directories (that are readable, searchable and do not cause cycles) |
| 180 | are visited at least twice, before any of their descendants have been |
| 181 | visited (pre-order) and after all their descendants have been visited |
| 182 | (post-order). |
| 183 | All other files are visited at least once. |
| 184 | .PP |
| 185 | The FTSENT structure contains at least the following fields: |
| 186 | .sp |
| 187 | .RS |
| 188 | .nf |
| 189 | .ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u |
| 190 | typedef struct ftsent { |
| 191 | struct ftsent *parent; /* parent structure */ |
| 192 | struct ftsent *link; /* cycle or file structure */ |
| 193 | union { |
| 194 | long number; /* local numeric value */ |
| 195 | void *pointer; /* local address value */ |
| 196 | } local; |
| 197 | char *accpath; /* path from current directory */ |
| 198 | char *path; /* path from starting directory */ |
| 199 | char *name; /* file name */ |
| 200 | short pathlen; /* strlen(path) */ |
| 201 | short namelen; /* strlen(name) */ |
| 202 | short level; /* depth (\-1 to N) */ |
| 203 | unsigned short info; /* flags for entry */ |
| 204 | struct stat statb; /* stat(2) information */ |
| 205 | } FTSENT; |
| 206 | .fi |
| 207 | .RE |
| 208 | .PP |
| 209 | The fields are as follows: |
| 210 | .TP |
| 211 | parent |
| 212 | A pointer to a structure referencing the file in the hierarchy |
| 213 | immediately above the current file/structure. |
| 214 | A parent structure for the initial entry point is provided as well, |
| 215 | however, only the |
| 216 | .I local |
| 217 | and |
| 218 | .I level |
| 219 | fields are guaranteed to be initialized. |
| 220 | .TP |
| 221 | link |
| 222 | If a directory causes a cycle in the hierarchy, either because of a |
| 223 | hard link between two directories, or a symbolic link pointing to a |
| 224 | directory, the |
| 225 | .I link |
| 226 | field of the structure will point to the structure in the hierarchy |
| 227 | that references the same file as the current structure. |
| 228 | Upon return from the |
| 229 | .I ftschildren |
| 230 | routine, the |
| 231 | .I link |
| 232 | field points to the next structure in the linked list of entries |
| 233 | from the directory. |
| 234 | Otherwise, the contents of the link field are undefined. |
| 235 | .TP |
| 236 | local |
| 237 | This field is provided for the use of the application program. |
| 238 | It can be used to store either a long value or an address. |
| 239 | .TP |
| 240 | accpath |
| 241 | A path that can be used to access the file. |
| 242 | .TP |
| 243 | path |
| 244 | The path for the file relative to the root of the traversal. |
| 245 | .TP |
| 246 | name |
| 247 | The basename of the file. |
| 248 | .TP |
| 249 | pathlen |
| 250 | The length of the string referenced by |
| 251 | .IR path . |
| 252 | .TP |
| 253 | namelen |
| 254 | The length of the string referenced by |
| 255 | .IR name . |
| 256 | .TP |
| 257 | level |
| 258 | The depth of the traversal, numbered from \-1 to N. |
| 259 | The parent structure of the root of the traversal is numbered \-1, and |
| 260 | the structure for the root of the traversal is numbered 0. |
| 261 | .TP |
| 262 | info |
| 263 | Information describing the file. |
| 264 | With the exception of directories (FTS_D), all of these entries are |
| 265 | terminal, i.e. they will not be revisited, nor will their descendants |
| 266 | be visited (if they have not been visited already). |
| 267 | .RS |
| 268 | .TP |
| 269 | FTS_D |
| 270 | A directory being visited in pre-order. |
| 271 | .TP |
| 272 | FTS_DC |
| 273 | A directory that causes a cycle. |
| 274 | The |
| 275 | .I link |
| 276 | field of the structure will be filled in as well. |
| 277 | .TP |
| 278 | FTS_DEFAULT |
| 279 | Anything that's not one of the others. |
| 280 | .TP |
| 281 | FTS_DNR |
| 282 | A directory that cannot be read. |
| 283 | .TP |
| 284 | FTS_DNX |
| 285 | A directory that cannot be searched. |
| 286 | .TP |
| 287 | FTS_DOT |
| 288 | A file named ``.'' or ``..'' with a |
| 289 | .I level |
| 290 | field not equal to zero, i.e. one not specified as an argument to |
| 291 | .IR ftsopen . |
| 292 | (See FTS_SEEDOT.) |
| 293 | .TP |
| 294 | FTS_DP |
| 295 | A directory that is being visited in post-order. |
| 296 | The contents of the structure will be unchanged from when the |
| 297 | directory was visited in pre-order. |
| 298 | .TP |
| 299 | FTS_ERR |
| 300 | An error indicator; the external variable |
| 301 | .I errno |
| 302 | contains an error number indicating the reason for the error. |
| 303 | .TP |
| 304 | FTS_F |
| 305 | A regular file. |
| 306 | .TP |
| 307 | FTS_NS |
| 308 | No |
| 309 | .IR stat (2) |
| 310 | information is available at this time (see FTS_NOSTAT); the |
| 311 | contents of the |
| 312 | .I statb |
| 313 | field are undefined. |
| 314 | .TP |
| 315 | FTS_SL |
| 316 | A symbolic link. |
| 317 | .TP |
| 318 | FTS_SLNONE |
| 319 | A symbolic link with a non-existent target. |
| 320 | .RE |
| 321 | .TP |
| 322 | statb |
| 323 | .IR Stat (2) |
| 324 | information for the file. |
| 325 | .PP |
| 326 | The |
| 327 | .IR accpath |
| 328 | and |
| 329 | .I path |
| 330 | fields are guaranteed to be NULL-terminated |
| 331 | .B only |
| 332 | for the file most recently returned by |
| 333 | .IR ftsread . |
| 334 | The |
| 335 | .I name |
| 336 | field is always NULL-terminated. |
| 337 | To use these fields to reference any other active files may require |
| 338 | that they be modified using the information contained in the |
| 339 | .I pathlen |
| 340 | field. |
| 341 | Any such modifications should be undone before further calls to |
| 342 | .I ftsread |
| 343 | are attempted. |
| 344 | .PP |
| 345 | If all the members of the hierarchy have been returned, |
| 346 | .I ftsread |
| 347 | returns NULL and sets the external variable |
| 348 | .I errno |
| 349 | to 0. |
| 350 | If an error unrelated to a file in the hierarchy occurs, |
| 351 | .I ftsread |
| 352 | returns NULL and sets errno appropriately. |
| 353 | Otherwise, a pointer to an FTSENT structure is returned, and an |
| 354 | error may or may not have occurred; see FTS_ERR above. |
| 355 | .PP |
| 356 | When the most recently returned file from |
| 357 | .I ftsread |
| 358 | is a directory being visited in pre-order, |
| 359 | .I ftschildren |
| 360 | returns a pointer to the first entry in a linked list (sorted by |
| 361 | the comparison routine, if provided) of the directory entries |
| 362 | it contains. |
| 363 | The linked list is linked through the |
| 364 | .I link |
| 365 | field of the FTSENT structure. |
| 366 | Each call to |
| 367 | .I ftschildren |
| 368 | recreates the list. |
| 369 | Note, cycles are not detected until a directory is actually visited, |
| 370 | therefore |
| 371 | .I ftschildren |
| 372 | will never return a structure with an |
| 373 | .I info |
| 374 | field set to FTS_DC. |
| 375 | If the current file is not a directory being visited in pre-order, |
| 376 | or if an error occurs, or the file does not contain any entries |
| 377 | .I ftschildren |
| 378 | returns NULL. |
| 379 | If an error occurs, |
| 380 | .I ftschildren |
| 381 | sets errno appropriately, otherwise it sets errno to zero. |
| 382 | .PP |
| 383 | The pointers returned by |
| 384 | .I ftsread |
| 385 | and |
| 386 | .I ftschildren |
| 387 | point to structures which may be overwritten. |
| 388 | Structures returned by |
| 389 | .I ftschildren |
| 390 | and |
| 391 | .I ftsread |
| 392 | may be overwritten after a call to |
| 393 | .I ftsclose |
| 394 | on the same file hierarchy. |
| 395 | Otherwise, structures returned by |
| 396 | .I ftschildren |
| 397 | will not be overwritten until a subsequent call to either |
| 398 | .I ftschildren |
| 399 | or |
| 400 | .I ftsread |
| 401 | on the same file hierarchy. |
| 402 | Structures returned by |
| 403 | .I ftsread |
| 404 | will not not be overwritten until a subsequent call to |
| 405 | .I ftsread |
| 406 | on the same file hierarchy stream, unless it represents a file of type |
| 407 | directory, in which case it will not be overwritten until after a |
| 408 | subsequent call to |
| 409 | .I ftsread |
| 410 | after it has been returned by the function |
| 411 | .I ftsread |
| 412 | in post-order. |
| 413 | .PP |
| 414 | The routine |
| 415 | .I ftsset |
| 416 | allows the user application to determine further processing for the |
| 417 | file |
| 418 | .I f |
| 419 | of the stream |
| 420 | .IR ftsp . |
| 421 | .I Ftsset |
| 422 | returns 0 on success, and -1 if an error occurs. |
| 423 | .I Option |
| 424 | may be set to any one of the following values. |
| 425 | .TP |
| 426 | FTS_AGAIN |
| 427 | Re-visit the file; any file type may be re-visited. |
| 428 | The next call to |
| 429 | .I ftsread |
| 430 | will return the referenced file. |
| 431 | The |
| 432 | .I stat |
| 433 | and |
| 434 | .I info |
| 435 | fields of the structure will be reinitialized at that time, |
| 436 | but no other fields will have been modified. |
| 437 | This option is meaningful only for the most recently returned |
| 438 | file from |
| 439 | .IR ftsread . |
| 440 | Normal use is for post-order directory visits, where it causes the |
| 441 | directory to be re-visited (in both pre and post-order) as well as all |
| 442 | of its descendants. |
| 443 | .TP |
| 444 | FTS_FOLLOW |
| 445 | The referenced file must be a symbolic link. |
| 446 | If the referenced file is the one most recently returned by |
| 447 | .IR ftsread , |
| 448 | the next call to |
| 449 | .I ftsread |
| 450 | returns the file with the |
| 451 | .I info |
| 452 | and |
| 453 | .I statb |
| 454 | fields reinitialized to reflect the target of the symbolic link instead |
| 455 | of the symbolic link itself. |
| 456 | If the file is one of those most recently returned by |
| 457 | .IR ftschildren , |
| 458 | the |
| 459 | .I info |
| 460 | and |
| 461 | .I statb |
| 462 | fields of the structure, when returned by |
| 463 | .IR ftsread , |
| 464 | will reflect the target of the symbolic link instead of the symbolic link |
| 465 | itself. |
| 466 | In either case, if the target of the link is a directory, the pre-order |
| 467 | return, followed by the return of all of its descendants, followed by a |
| 468 | post-order return, is done. |
| 469 | .TP |
| 470 | FTS_SKIP |
| 471 | No descendants of this file are visited. |
| 472 | .PP |
| 473 | Hard links between directories that do not cause cycles or symbolic |
| 474 | links to symbolic links may cause files to be visited more than once, |
| 475 | or directories more than twice. |
| 476 | .SH ERRORS |
| 477 | .I Ftsopen |
| 478 | may fail and set errno for any of the errors specified for the library |
| 479 | routine |
| 480 | .IR malloc (3). |
| 481 | .PP |
| 482 | .I Ftsclose |
| 483 | may fail and set errno for any of the errors specified for the library |
| 484 | routine |
| 485 | .IR chdir (2). |
| 486 | .PP |
| 487 | .I Ftsread |
| 488 | and |
| 489 | .I ftschildren |
| 490 | may fail and set errno for any of the errors specified for the library |
| 491 | routines |
| 492 | .IR chdir (2), |
| 493 | .IR getgroups (2), |
| 494 | .IR malloc (3), |
| 495 | .IR opendir (3), |
| 496 | .IR readdir (3) |
| 497 | and |
| 498 | .IR stat (2). |
| 499 | .SH SEE ALSO |
| 500 | find(1), chdir(2), stat(2), qsort(3) |
| 501 | .SH STANDARDS |
| 502 | The |
| 503 | .I fts |
| 504 | utility is expected to be POSIX 1003.1 compliant. |