14585130bSYuri Pankov.\" 24585130bSYuri Pankov.\" Copyright (c) 1989, 1991, 1993C, 1994 34585130bSYuri Pankov.\" The Regents of the University of California. All rights reserved. 44585130bSYuri Pankov.\" 54585130bSYuri Pankov.\" Redistribution and use in source and binary forms, with or without 64585130bSYuri Pankov.\" modification, are permitted provided that the following conditions 74585130bSYuri Pankov.\" are met: 84585130bSYuri Pankov.\" 1. Redistributions of source code must retain the above copyright 94585130bSYuri Pankov.\" notice, this list of conditions and the following disclaimer. 104585130bSYuri Pankov.\" 2. Redistributions in binary form must reproduce the above copyright 114585130bSYuri Pankov.\" notice, this list of conditions and the following disclaimer in the 124585130bSYuri Pankov.\" documentation and/or other materials provided with the distribution. 134585130bSYuri Pankov.\" 3C. Neither the name of the University nor the names of its contributors 144585130bSYuri Pankov.\" may be used to endorse or promote products derived from this software 154585130bSYuri Pankov.\" without specific prior written permission. 164585130bSYuri Pankov.\" 174585130bSYuri Pankov.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 184585130bSYuri Pankov.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 194585130bSYuri Pankov.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 204585130bSYuri Pankov.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 214585130bSYuri Pankov.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 224585130bSYuri Pankov.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 234585130bSYuri Pankov.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 244585130bSYuri Pankov.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 254585130bSYuri Pankov.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 264585130bSYuri Pankov.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 274585130bSYuri Pankov.\" SUCH DAMAGE. 284585130bSYuri Pankov.\" 294585130bSYuri Pankov.\" 304585130bSYuri Pankov.Dd March 28, 2017 314585130bSYuri Pankov.Dt FTS 3C 324585130bSYuri Pankov.Os 334585130bSYuri Pankov.Sh NAME 344585130bSYuri Pankov.Nm fts_open , 354585130bSYuri Pankov.Nm fts_read , 364585130bSYuri Pankov.Nm fts_children , 374585130bSYuri Pankov.Nm fts_set , 384585130bSYuri Pankov.Nm fts_close 394585130bSYuri Pankov.Nd traverse a file hierarchy 404585130bSYuri Pankov.Sh SYNOPSIS 414585130bSYuri Pankov.In sys/types.h 424585130bSYuri Pankov.In sys/stat.h 434585130bSYuri Pankov.In fts.h 444585130bSYuri Pankov.Ft FTS * 454585130bSYuri Pankov.Fo fts_open 464585130bSYuri Pankov.Fa "char * const *path_argv" 474585130bSYuri Pankov.Fa "int options" 484585130bSYuri Pankov.Fa "int (*compar)(const FTSENT **, const FTSENT **)" 494585130bSYuri Pankov.Fc 504585130bSYuri Pankov.Ft FTSENT * 514585130bSYuri Pankov.Fn fts_read "FTS *ftsp" 524585130bSYuri Pankov.Ft FTSENT * 534585130bSYuri Pankov.Fn fts_children "FTS *ftsp" "int options" 544585130bSYuri Pankov.Ft int 554585130bSYuri Pankov.Fn fts_set "FTS *ftsp" "FTSENT *f" "int option" 564585130bSYuri Pankov.Ft int 574585130bSYuri Pankov.Fn fts_close "FTS *ftsp" 584585130bSYuri Pankov.Sh DESCRIPTION 594585130bSYuri PankovThe 604585130bSYuri Pankov.Nm fts 614585130bSYuri Pankovfunctions are provided for traversing 624585130bSYuri Pankov.Ux 634585130bSYuri Pankovfile hierarchies. 644585130bSYuri PankovThe 654585130bSYuri Pankov.Fn fts_open 664585130bSYuri Pankovfunction returns a 674585130bSYuri Pankov.Dq handle 684585130bSYuri Pankovon a file hierarchy, which is then supplied to 694585130bSYuri Pankovthe other 704585130bSYuri Pankov.Nm fts 714585130bSYuri Pankovfunctions. 724585130bSYuri PankovThe function 734585130bSYuri Pankov.Fn fts_read 744585130bSYuri Pankovreturns a pointer to a structure describing one of the files in the file 754585130bSYuri Pankovhierarchy. 764585130bSYuri PankovThe function 774585130bSYuri Pankov.Fn fts_children 784585130bSYuri Pankovreturns a pointer to a linked list of structures, each of which describes 794585130bSYuri Pankovone of the files contained in a directory within the hierarchy. 804585130bSYuri Pankov.Pp 814585130bSYuri PankovIn general, directories are visited two distinguishable times; in pre-order 824585130bSYuri Pankov.Pq before any of their descendants are visited 834585130bSYuri Pankovand in post-order 844585130bSYuri Pankov.Pq after all of their descendants have been visited . 854585130bSYuri PankovFiles are visited once. 864585130bSYuri PankovIt is possible to walk the hierarchy 874585130bSYuri Pankov.Dq logically 884585130bSYuri Pankov.Pq following symbolic links 894585130bSYuri Pankovor 904585130bSYuri Pankov.Dq physically 914585130bSYuri Pankov.Pq not following symbolic links , 924585130bSYuri Pankovorder the walk of the hierarchy, or 934585130bSYuri Pankovprune and/or re-visit portions of the hierarchy. 944585130bSYuri Pankov.Pp 954585130bSYuri PankovTwo structures are defined 964585130bSYuri Pankov.Pq and typedef'd 974585130bSYuri Pankovin the include file 984585130bSYuri Pankov.In fts.h . 994585130bSYuri PankovThe first is 1004585130bSYuri Pankov.Dv FTS , 1014585130bSYuri Pankovthe structure that represents the file hierarchy itself. 1024585130bSYuri PankovThe second is 1034585130bSYuri Pankov.Li FTSENT , 1044585130bSYuri Pankovthe structure that represents a file in the file 1054585130bSYuri Pankovhierarchy. 1064585130bSYuri PankovNormally, an 1074585130bSYuri Pankov.Li FTSENT 1084585130bSYuri Pankovstructure is returned for every file in the file 1094585130bSYuri Pankovhierarchy. 1104585130bSYuri PankovIn this manual page, 1114585130bSYuri Pankov.Dq file 1124585130bSYuri Pankovand 1134585130bSYuri Pankov.Dq Li FTSENT No structure 1144585130bSYuri Pankovare generally 1154585130bSYuri Pankovinterchangeable. 1164585130bSYuri Pankov.Pp 1174585130bSYuri PankovThe 1184585130bSYuri Pankov.Li FTSENT 1194585130bSYuri Pankovstructure contains at least the following fields, which are 1204585130bSYuri Pankovdescribed in greater detail below: 1214585130bSYuri Pankov.Bd -literal 1224585130bSYuri Pankovtypedef struct _ftsent { 1234585130bSYuri Pankov unsigned short fts_info; /* flags for FTSENT structure */ 1244585130bSYuri Pankov char *fts_accpath; /* access path */ 1254585130bSYuri Pankov char *fts_path; /* root path */ 1264585130bSYuri Pankov size_t fts_pathlen; /* strlen(fts_path) */ 1274585130bSYuri Pankov char *fts_name; /* file name */ 1284585130bSYuri Pankov size_t fts_namelen; /* strlen(fts_name) */ 1294585130bSYuri Pankov int fts_level; /* depth (-1 to N) */ 1304585130bSYuri Pankov int fts_errno; /* file errno */ 1314585130bSYuri Pankov long fts_number; /* local numeric value */ 1324585130bSYuri Pankov void *fts_pointer; /* local address value */ 1334585130bSYuri Pankov struct _ftsent *fts_parent; /* parent directory */ 1344585130bSYuri Pankov struct _ftsent *fts_link; /* next file structure */ 1354585130bSYuri Pankov struct _ftsent *fts_cycle; /* cycle structure */ 1364585130bSYuri Pankov struct stat *fts_statp; /* stat(2) information */ 1374585130bSYuri Pankov} FTSENT; 1384585130bSYuri Pankov.Ed 1394585130bSYuri Pankov.Pp 1404585130bSYuri PankovThese fields are defined as follows: 1414585130bSYuri Pankov.Bl -tag -width "fts_namelen" 1424585130bSYuri Pankov.It Fa fts_info 1434585130bSYuri PankovOne of the following flags describing the returned 1444585130bSYuri Pankov.Li FTSENT 1454585130bSYuri Pankovstructure and 1464585130bSYuri Pankovthe file it represents. 1474585130bSYuri PankovWith the exception of directories without errors 1484585130bSYuri Pankov.Pq Dv FTS_D , 1494585130bSYuri Pankovall of these 1504585130bSYuri Pankoventries are terminal, that is, they will not be revisited, nor will any 1514585130bSYuri Pankovof their descendants be visited. 1524585130bSYuri Pankov.Bl -tag -width FTS_DEFAULT 1534585130bSYuri Pankov.It Dv FTS_D 1544585130bSYuri PankovA directory being visited in pre-order. 1554585130bSYuri Pankov.It Dv FTS_DC 1564585130bSYuri PankovA directory that causes a cycle in the tree. 1574585130bSYuri Pankov.Po The 1584585130bSYuri Pankov.Fa fts_cycle 1594585130bSYuri Pankovfield of the 1604585130bSYuri Pankov.Li FTSENT 1614585130bSYuri Pankovstructure will be filled in as well. 1624585130bSYuri Pankov.Pc 1634585130bSYuri Pankov.It Dv FTS_DEFAULT 1644585130bSYuri PankovAny 1654585130bSYuri Pankov.Li FTSENT 1664585130bSYuri Pankovstructure that represents a file type not explicitly described 1674585130bSYuri Pankovby one of the other 1684585130bSYuri Pankov.Fa fts_info 1694585130bSYuri Pankovvalues. 1704585130bSYuri Pankov.It Dv FTS_DNR 1714585130bSYuri PankovA directory which cannot be read. 1724585130bSYuri PankovThis is an error return, and the 1734585130bSYuri Pankov.Fa fts_errno 1744585130bSYuri Pankovfield will be set to indicate what caused the error. 1754585130bSYuri Pankov.It Dv FTS_DOT 1764585130bSYuri PankovA file named 1774585130bSYuri Pankov.Dq \&. 1784585130bSYuri Pankovor 1794585130bSYuri Pankov.Dq .. 1804585130bSYuri Pankovwhich was not specified as a file name to 1814585130bSYuri Pankov.Fn fts_open 1824585130bSYuri Pankov.Pq see Dv FTS_SEEDOT . 1834585130bSYuri Pankov.It Dv FTS_DP 1844585130bSYuri PankovA directory being visited in post-order. 1854585130bSYuri PankovThe contents of the 1864585130bSYuri Pankov.Li FTSENT 1874585130bSYuri Pankovstructure will be unchanged from when 1884585130bSYuri Pankovit was returned in pre-order, i.e., with the 1894585130bSYuri Pankov.Fa fts_info 1904585130bSYuri Pankovfield set to 1914585130bSYuri Pankov.Dv FTS_D . 1924585130bSYuri Pankov.It Dv FTS_ERR 1934585130bSYuri PankovThis is an error return, and the 1944585130bSYuri Pankov.Fa fts_errno 1954585130bSYuri Pankovfield will be set to indicate what caused the error. 1964585130bSYuri Pankov.It Dv FTS_F 1974585130bSYuri PankovA regular file. 1984585130bSYuri Pankov.It Dv FTS_NS 1994585130bSYuri PankovA file for which no 2004585130bSYuri Pankov.Xr stat 2 2014585130bSYuri Pankovinformation was available. 2024585130bSYuri PankovThe contents of the 2034585130bSYuri Pankov.Fa fts_statp 2044585130bSYuri Pankovfield are undefined. 2054585130bSYuri PankovThis is an error return, and the 2064585130bSYuri Pankov.Fa fts_errno 2074585130bSYuri Pankovfield will be set to indicate what caused the error. 2084585130bSYuri Pankov.It Dv FTS_NSOK 2094585130bSYuri PankovA file for which no 2104585130bSYuri Pankov.Xr stat 2 2114585130bSYuri Pankovinformation was requested. 2124585130bSYuri PankovThe contents of the 2134585130bSYuri Pankov.Fa fts_statp 2144585130bSYuri Pankovfield are undefined. 2154585130bSYuri Pankov.It Dv FTS_SL 2164585130bSYuri PankovA symbolic link. 2174585130bSYuri Pankov.It Dv FTS_SLNONE 2184585130bSYuri PankovA symbolic link with a non-existent target. 2194585130bSYuri PankovThe contents of the 2204585130bSYuri Pankov.Fa fts_statp 2214585130bSYuri Pankovfield reference the file characteristic information for the symbolic link 2224585130bSYuri Pankovitself. 2234585130bSYuri Pankov.El 2244585130bSYuri Pankov.It Fa fts_accpath 2254585130bSYuri PankovA path for accessing the file from the current directory. 2264585130bSYuri Pankov.It Fa fts_path 2274585130bSYuri PankovThe path for the file relative to the root of the traversal. 2284585130bSYuri PankovThis path contains the path specified to 2294585130bSYuri Pankov.Fn fts_open 2304585130bSYuri Pankovas a prefix. 2314585130bSYuri Pankov.It Fa fts_pathlen 2324585130bSYuri PankovThe length of the string referenced by 2334585130bSYuri Pankov.Fa fts_path . 2344585130bSYuri Pankov.It Fa fts_name 2354585130bSYuri PankovThe name of the file. 2364585130bSYuri Pankov.It Fa fts_namelen 2374585130bSYuri PankovThe length of the string referenced by 2384585130bSYuri Pankov.Fa fts_name . 2394585130bSYuri Pankov.It Fa fts_level 2404585130bSYuri PankovThe depth of the traversal, numbered from \-1 to N, where this file 2414585130bSYuri Pankovwas found. 2424585130bSYuri PankovThe 2434585130bSYuri Pankov.Li FTSENT 2444585130bSYuri Pankovstructure representing the parent of the starting point 2454585130bSYuri Pankov.Pq or root 2464585130bSYuri Pankovof the traversal is numbered 2474585130bSYuri Pankov.Dv FTS_ROOTPARENTLEVEL 2484585130bSYuri Pankov.Pq \-1 , 2494585130bSYuri Pankovand the 2504585130bSYuri Pankov.Li FTSENT 2514585130bSYuri Pankovstructure for the root 2524585130bSYuri Pankovitself is numbered 2534585130bSYuri Pankov.Dv FTS_ROOTLEVEL 2544585130bSYuri Pankov.Pq 0 . 2554585130bSYuri PankovNote that while 2564585130bSYuri Pankov.Fa fts_level 2574585130bSYuri Pankovcannot hold a number of levels greater than 2584585130bSYuri Pankov.Dv FTS_MAXLEVEL , 2594585130bSYuri Pankovthe 2604585130bSYuri Pankov.Nm fts 2614585130bSYuri Pankovfunctions themselves are not limited to a fixed number 2624585130bSYuri Pankovof levels. 2634585130bSYuri PankovApplication code that inspects 2644585130bSYuri Pankov.Fa fts_level 2654585130bSYuri Pankovshould be written with this in mind. 2664585130bSYuri Pankov.It Fa fts_errno 2674585130bSYuri PankovUpon return of an 2684585130bSYuri Pankov.Li FTSENT 2694585130bSYuri Pankovstructure from the 2704585130bSYuri Pankov.Fn fts_children 2714585130bSYuri Pankovor 2724585130bSYuri Pankov.Fn fts_read 2734585130bSYuri Pankovfunctions, with its 2744585130bSYuri Pankov.Fa fts_info 2754585130bSYuri Pankovfield set to 2764585130bSYuri Pankov.Dv FTS_DNR , 2774585130bSYuri Pankov.Dv FTS_ERR 2784585130bSYuri Pankovor 2794585130bSYuri Pankov.Dv FTS_NS , 2804585130bSYuri Pankovthe 2814585130bSYuri Pankov.Fa fts_errno 2824585130bSYuri Pankovfield contains the value of the external variable 2834585130bSYuri Pankov.Va errno 2844585130bSYuri Pankovspecifying the cause of the error. 2854585130bSYuri PankovOtherwise, the contents of the 2864585130bSYuri Pankov.Fa fts_errno 2874585130bSYuri Pankovfield are undefined. 2884585130bSYuri Pankov.It Fa fts_number 2894585130bSYuri PankovThis field is provided for the use of the application program and is 2904585130bSYuri Pankovnot modified by the 2914585130bSYuri Pankov.Nm fts 2924585130bSYuri Pankovfunctions. 2934585130bSYuri PankovIt is initialized to 0. 2944585130bSYuri Pankov.It Fa fts_pointer 2954585130bSYuri PankovThis field is provided for the use of the application program and is 2964585130bSYuri Pankovnot modified by the 2974585130bSYuri Pankov.Nm fts 2984585130bSYuri Pankovfunctions. 2994585130bSYuri PankovIt is initialized to 3004585130bSYuri Pankov.Dv NULL . 3014585130bSYuri Pankov.It Fa fts_parent 3024585130bSYuri PankovA pointer to the 3034585130bSYuri Pankov.Li FTSENT 3044585130bSYuri Pankovstructure referencing the file in the hierarchy 3054585130bSYuri Pankovimmediately above the current file, i.e., the directory of which this 3064585130bSYuri Pankovfile is a member. 3074585130bSYuri PankovA parent structure for the initial entry point is provided as well, 3084585130bSYuri Pankovhowever, only the 3094585130bSYuri Pankov.Fa fts_level , 3104585130bSYuri Pankov.Fa fts_number 3114585130bSYuri Pankovand 3124585130bSYuri Pankov.Fa fts_pointer 3134585130bSYuri Pankovfields are guaranteed to be initialized. 3144585130bSYuri Pankov.It Fa fts_link 3154585130bSYuri PankovUpon return from the 3164585130bSYuri Pankov.Fn fts_children 3174585130bSYuri Pankovfunction, the 3184585130bSYuri Pankov.Fa fts_link 3194585130bSYuri Pankovfield points to the next structure in the null-terminated 3204585130bSYuri Pankovlinked list of directory members. 3214585130bSYuri PankovOtherwise, the contents of the 3224585130bSYuri Pankov.Fa fts_link 3234585130bSYuri Pankovfield are undefined. 3244585130bSYuri Pankov.It Fa fts_cycle 3254585130bSYuri PankovIf a directory causes a cycle in the hierarchy 3264585130bSYuri Pankov.Pq see Dv FTS_DC , 3274585130bSYuri Pankoveither because of a hard link between two directories, or a symbolic link 3284585130bSYuri Pankovpointing to a directory, the 3294585130bSYuri Pankov.Fa fts_cycle 3304585130bSYuri Pankovfield of the structure will point to the 3314585130bSYuri Pankov.Li FTSENT 3324585130bSYuri Pankovstructure in the hierarchy that references the same file as the current 3334585130bSYuri Pankov.Li FTSENT 3344585130bSYuri Pankovstructure. 3354585130bSYuri PankovOtherwise, the contents of the 3364585130bSYuri Pankov.Fa fts_cycle 3374585130bSYuri Pankovfield are undefined. 3384585130bSYuri Pankov.It Fa fts_statp 3394585130bSYuri PankovA pointer to 3404585130bSYuri Pankov.Xr stat 2 3414585130bSYuri Pankovinformation for the file. 3424585130bSYuri Pankov.El 3434585130bSYuri Pankov.Pp 3444585130bSYuri PankovA single buffer is used for all of the paths of all of the files in the 3454585130bSYuri Pankovfile hierarchy. 3464585130bSYuri PankovTherefore, the 3474585130bSYuri Pankov.Fa fts_path 3484585130bSYuri Pankovand 3494585130bSYuri Pankov.Fa fts_accpath 3504585130bSYuri Pankovfields are guaranteed to be NUL terminated 3514585130bSYuri Pankov.Em only 3524585130bSYuri Pankovfor the file most recently returned by 3534585130bSYuri Pankov.Fn fts_read . 3544585130bSYuri PankovTo use these fields to reference any files represented by other 3554585130bSYuri Pankov.Li FTSENT 3564585130bSYuri Pankovstructures will require that the path buffer be modified using the 3574585130bSYuri Pankovinformation contained in that 3584585130bSYuri Pankov.Li FTSENT 3594585130bSYuri Pankovstructure's 3604585130bSYuri Pankov.Fa fts_pathlen 3614585130bSYuri Pankovfield. 3624585130bSYuri PankovAny such modifications should be undone before further calls to 3634585130bSYuri Pankov.Fn fts_read 3644585130bSYuri Pankovare attempted. 3654585130bSYuri PankovThe 3664585130bSYuri Pankov.Fa fts_name 3674585130bSYuri Pankovfield is always NUL terminated. 3684585130bSYuri Pankov.Ss FTS_OPEN 3694585130bSYuri PankovThe 3704585130bSYuri Pankov.Fn fts_open 3714585130bSYuri Pankovfunction takes a pointer to an array of character pointers naming one 3724585130bSYuri Pankovor more paths which make up a logical file hierarchy to be traversed. 3734585130bSYuri PankovThe array must be terminated by a null pointer. 3744585130bSYuri Pankov.Pp 3754585130bSYuri PankovThere are 3764585130bSYuri Pankova number of options, at least one of which 3774585130bSYuri Pankov.Po either 3784585130bSYuri Pankov.Dv FTS_LOGICAL 3794585130bSYuri Pankovor 3804585130bSYuri Pankov.Dv FTS_PHYSICAL 3814585130bSYuri Pankov.Pc 3824585130bSYuri Pankovmust be specified. 3834585130bSYuri PankovThe 3844585130bSYuri Pankov.Fa options 3854585130bSYuri Pankovare selected by 3864585130bSYuri Pankov.Tn OR Ns 'ing 3874585130bSYuri Pankovthe following values: 3884585130bSYuri Pankov.Bl -tag -width "FTS_COMFOLLOW" 3894585130bSYuri Pankov.It Dv FTS_COMFOLLOW 3904585130bSYuri PankovThis option causes any symbolic link specified as a root path to be 3914585130bSYuri Pankovfollowed immediately whether or not 3924585130bSYuri Pankov.Dv FTS_LOGICAL 3934585130bSYuri Pankovis also specified. 3944585130bSYuri Pankov.It Dv FTS_LOGICAL 3954585130bSYuri PankovThis option causes the 3964585130bSYuri Pankov.Nm fts 3974585130bSYuri Pankovroutines to return 3984585130bSYuri Pankov.Li FTSENT 3994585130bSYuri Pankovstructures for the targets of symbolic links 4004585130bSYuri Pankovinstead of the symbolic links themselves. 4014585130bSYuri PankovIf this option is set, the only symbolic links for which 4024585130bSYuri Pankov.Li FTSENT 4034585130bSYuri Pankovstructures 4044585130bSYuri Pankovare returned to the application are those referencing non-existent files. 4054585130bSYuri PankovEither 4064585130bSYuri Pankov.Dv FTS_LOGICAL 4074585130bSYuri Pankovor 4084585130bSYuri Pankov.Dv FTS_PHYSICAL 4094585130bSYuri Pankov.Em must 4104585130bSYuri Pankovbe provided to the 4114585130bSYuri Pankov.Fn fts_open 4124585130bSYuri Pankovfunction. 4134585130bSYuri Pankov.It Dv FTS_NOCHDIR 4144585130bSYuri PankovAs a performance optimization, the 4154585130bSYuri Pankov.Nm fts 4164585130bSYuri Pankovfunctions change directories as they walk the file hierarchy. 4174585130bSYuri PankovThis has the side-effect that an application cannot rely on being 4184585130bSYuri Pankovin any particular directory during the traversal. 4194585130bSYuri PankovThe 4204585130bSYuri Pankov.Dv FTS_NOCHDIR 4214585130bSYuri Pankovoption turns off this optimization, and the 4224585130bSYuri Pankov.Nm fts 4234585130bSYuri Pankovfunctions will not change the current directory. 4244585130bSYuri PankovNote that applications should not themselves change their current directory 4254585130bSYuri Pankovand try to access files unless 4264585130bSYuri Pankov.Dv FTS_NOCHDIR 4274585130bSYuri Pankovis specified and absolute 4284585130bSYuri Pankovpathnames were provided as arguments to 4294585130bSYuri Pankov.Fn fts_open . 4304585130bSYuri Pankov.It Dv FTS_NOSTAT 4314585130bSYuri PankovBy default, returned 4324585130bSYuri Pankov.Li FTSENT 4334585130bSYuri Pankovstructures reference file characteristic information 4344585130bSYuri Pankov.Po the 4354585130bSYuri Pankov.Fa statp 4364585130bSYuri Pankovfield 4374585130bSYuri Pankov.Pc 4384585130bSYuri Pankovfor each file visited. 4394585130bSYuri PankovThis option relaxes that requirement as a performance optimization, 4404585130bSYuri Pankovallowing the 4414585130bSYuri Pankov.Nm fts 4424585130bSYuri Pankovfunctions to set the 4434585130bSYuri Pankov.Fa fts_info 4444585130bSYuri Pankovfield to 4454585130bSYuri Pankov.Dv FTS_NSOK 4464585130bSYuri Pankovand leave the contents of the 4474585130bSYuri Pankov.Fa statp 4484585130bSYuri Pankovfield undefined. 4494585130bSYuri Pankov.It Dv FTS_PHYSICAL 4504585130bSYuri PankovThis option causes the 4514585130bSYuri Pankov.Nm fts 4524585130bSYuri Pankovroutines to return 4534585130bSYuri Pankov.Li FTSENT 4544585130bSYuri Pankovstructures for symbolic links themselves instead 4554585130bSYuri Pankovof the target files they point to. 4564585130bSYuri PankovIf this option is set, 4574585130bSYuri Pankov.Li FTSENT 4584585130bSYuri Pankovstructures for all symbolic links in the 4594585130bSYuri Pankovhierarchy are returned to the application. 4604585130bSYuri PankovEither 4614585130bSYuri Pankov.Dv FTS_LOGICAL 4624585130bSYuri Pankovor 4634585130bSYuri Pankov.Dv FTS_PHYSICAL 4644585130bSYuri Pankov.Em must 4654585130bSYuri Pankovbe provided to the 4664585130bSYuri Pankov.Fn fts_open 4674585130bSYuri Pankovfunction. 4684585130bSYuri Pankov.It Dv FTS_SEEDOT 4694585130bSYuri PankovBy default, unless they are specified as path arguments to 4704585130bSYuri Pankov.Fn fts_open , 4714585130bSYuri Pankovany files named 4724585130bSYuri Pankov.Dq \&. 4734585130bSYuri Pankovor 4744585130bSYuri Pankov.Dq .. 4754585130bSYuri Pankovencountered in the file hierarchy are ignored. 4764585130bSYuri PankovThis option causes the 4774585130bSYuri Pankov.Nm fts 4784585130bSYuri Pankovroutines to return 4794585130bSYuri Pankov.Li FTSENT 4804585130bSYuri Pankovstructures for them. 4814585130bSYuri Pankov.It Dv FTS_XDEV 4824585130bSYuri PankovThis option prevents 4834585130bSYuri Pankov.Nm fts 4844585130bSYuri Pankovfrom descending into directories that have a different device number 4854585130bSYuri Pankovthan the file from which the descent began. 4864585130bSYuri Pankov.El 4874585130bSYuri Pankov.Pp 4884585130bSYuri PankovThe 4894585130bSYuri Pankov.Fa compar 4904585130bSYuri Pankovargument 4914585130bSYuri Pankovspecifies a user-defined function which may be used to order the traversal 4924585130bSYuri Pankovof the hierarchy. 4934585130bSYuri PankovIt 4944585130bSYuri Pankovtakes two pointers to pointers to 4954585130bSYuri Pankov.Li FTSENT 4964585130bSYuri Pankovstructures as arguments and 4974585130bSYuri Pankovshould return a negative value, zero, or a positive value to indicate 4984585130bSYuri Pankovif the file referenced by its first argument comes before, in any order 4994585130bSYuri Pankovwith respect to, or after, the file referenced by its second argument. 5004585130bSYuri PankovThe 5014585130bSYuri Pankov.Fa fts_accpath , 5024585130bSYuri Pankov.Fa fts_path 5034585130bSYuri Pankovand 5044585130bSYuri Pankov.Fa fts_pathlen 5054585130bSYuri Pankovfields of the 5064585130bSYuri Pankov.Li FTSENT 5074585130bSYuri Pankovstructures may 5084585130bSYuri Pankov.Em never 5094585130bSYuri Pankovbe used in this comparison. 5104585130bSYuri PankovIf the 5114585130bSYuri Pankov.Fa fts_info 5124585130bSYuri Pankovfield is set to 5134585130bSYuri Pankov.Dv FTS_NS 5144585130bSYuri Pankovor 5154585130bSYuri Pankov.Dv FTS_NSOK , 5164585130bSYuri Pankovthe 5174585130bSYuri Pankov.Fa fts_statp 5184585130bSYuri Pankovfield may not either. 5194585130bSYuri PankovIf the 5204585130bSYuri Pankov.Fa compar 5214585130bSYuri Pankovargument is 5224585130bSYuri Pankov.Dv NULL , 5234585130bSYuri Pankovthe directory traversal order is in the order listed in 5244585130bSYuri Pankov.Fa path_argv 5254585130bSYuri Pankovfor the root paths, and in the order listed in the directory for 5264585130bSYuri Pankoveverything else. 5274585130bSYuri Pankov.Pp 5284585130bSYuri PankovIf an error occurs, 5294585130bSYuri Pankov.Fn fts_open 5304585130bSYuri Pankovreturns 5314585130bSYuri Pankov.Dv NULL 5324585130bSYuri Pankovand sets 5334585130bSYuri Pankov.Va errno 5344585130bSYuri Pankovappropriately. 5354585130bSYuri Pankov.Ss FTS_READ 5364585130bSYuri PankovThe 5374585130bSYuri Pankov.Fn fts_read 5384585130bSYuri Pankovfunction returns a pointer to an 5394585130bSYuri Pankov.Li FTSENT 5404585130bSYuri Pankovstructure describing a file in 5414585130bSYuri Pankovthe hierarchy. 5424585130bSYuri PankovDirectories 5434585130bSYuri Pankov.Pq that are readable and do not cause cycles 5444585130bSYuri Pankovare visited at least twice, once in pre-order and once in post-order. 5454585130bSYuri PankovAll other files are visited at least once. 5464585130bSYuri Pankov.Po Hard links between directories that do not cause cycles or symbolic 5474585130bSYuri Pankovlinks to symbolic links may cause files to be visited more than once, 5484585130bSYuri Pankovor directories more than twice. 5494585130bSYuri Pankov.Pc 5504585130bSYuri Pankov.Pp 5514585130bSYuri PankovIf all the members of the hierarchy have been returned, 5524585130bSYuri Pankov.Fn fts_read 5534585130bSYuri Pankovreturns 5544585130bSYuri Pankov.Dv NULL 5554585130bSYuri Pankovand sets the external variable 5564585130bSYuri Pankov.Va errno 5574585130bSYuri Pankovto 0. 5584585130bSYuri PankovIf an error unrelated to a file in the hierarchy occurs, 5594585130bSYuri Pankov.Fn fts_read 5604585130bSYuri Pankovreturns 5614585130bSYuri Pankov.Dv NULL 5624585130bSYuri Pankovand sets 5634585130bSYuri Pankov.Va errno 5644585130bSYuri Pankovappropriately. 5654585130bSYuri PankovIf an error related to a returned file occurs, a pointer to an 5664585130bSYuri Pankov.Li FTSENT 5674585130bSYuri Pankovstructure is returned, and 5684585130bSYuri Pankov.Va errno 5694585130bSYuri Pankovmay or may not have been set 5704585130bSYuri Pankov.Pq see Fa fts_info . 5714585130bSYuri Pankov.Pp 5724585130bSYuri PankovThe 5734585130bSYuri Pankov.Li FTSENT 5744585130bSYuri Pankovstructures returned by 5754585130bSYuri Pankov.Fn fts_read 5764585130bSYuri Pankovmay be overwritten after a call to 5774585130bSYuri Pankov.Fn fts_close 5784585130bSYuri Pankovon the same file hierarchy stream or, after a call to 5794585130bSYuri Pankov.Fn fts_read , 5804585130bSYuri Pankovon the same file hierarchy stream unless they represent a file of type 5814585130bSYuri Pankovdirectory, in which case they will not be overwritten until after a call to 5824585130bSYuri Pankov.Fn fts_read 5834585130bSYuri Pankovafter the 5844585130bSYuri Pankov.Li FTSENT 5854585130bSYuri Pankovstructure has been returned by the function 5864585130bSYuri Pankov.Fn fts_read 5874585130bSYuri Pankovin post-order. 5884585130bSYuri Pankov.Ss FTS_CHILDREN 5894585130bSYuri PankovThe 5904585130bSYuri Pankov.Fn fts_children 5914585130bSYuri Pankovfunction returns a pointer to an 5924585130bSYuri Pankov.Li FTSENT 5934585130bSYuri Pankovstructure describing the first entry in a null-terminated 5944585130bSYuri Pankovlinked list of 5954585130bSYuri Pankovthe files in the directory represented by the 5964585130bSYuri Pankov.Li FTSENT 5974585130bSYuri Pankovstructure most recently returned by 5984585130bSYuri Pankov.Fn fts_read . 5994585130bSYuri PankovThe list is linked through the 6004585130bSYuri Pankov.Fa fts_link 6014585130bSYuri Pankovfield of the 6024585130bSYuri Pankov.Li FTSENT 6034585130bSYuri Pankovstructure, and is ordered by the user-specified comparison function, if any. 6044585130bSYuri PankovRepeated calls to 6054585130bSYuri Pankov.Fn fts_children 6064585130bSYuri Pankovwill recreate this linked list. 6074585130bSYuri Pankov.Pp 6084585130bSYuri PankovAs a special case, if 6094585130bSYuri Pankov.Fn fts_read 6104585130bSYuri Pankovhas not yet been called for a hierarchy, 6114585130bSYuri Pankov.Fn fts_children 6124585130bSYuri Pankovwill return a pointer to the files in the logical directory specified to 6134585130bSYuri Pankov.Fn fts_open , 6144585130bSYuri Pankovi.e., the arguments specified to 6154585130bSYuri Pankov.Fn fts_open . 6164585130bSYuri PankovOtherwise, if the 6174585130bSYuri Pankov.Li FTSENT 6184585130bSYuri Pankovstructure most recently returned by 6194585130bSYuri Pankov.Fn fts_read 6204585130bSYuri Pankovis not a directory being visited in pre-order, 6214585130bSYuri Pankovor the directory does not contain any files, 6224585130bSYuri Pankov.Fn fts_children 6234585130bSYuri Pankovreturns 6244585130bSYuri Pankov.Dv NULL 6254585130bSYuri Pankovand sets 6264585130bSYuri Pankov.Va errno 6274585130bSYuri Pankovto 0. 6284585130bSYuri PankovIf an error occurs, 6294585130bSYuri Pankov.Fn fts_children 6304585130bSYuri Pankovreturns 6314585130bSYuri Pankov.Dv NULL 6324585130bSYuri Pankovand sets 6334585130bSYuri Pankov.Va errno 6344585130bSYuri Pankovappropriately. 6354585130bSYuri Pankov.Pp 6364585130bSYuri PankovThe 6374585130bSYuri Pankov.Li FTSENT 6384585130bSYuri Pankovstructures returned by 6394585130bSYuri Pankov.Fn fts_children 6404585130bSYuri Pankovmay be overwritten after a call to 6414585130bSYuri Pankov.Fn fts_children , 6424585130bSYuri Pankov.Fn fts_close 6434585130bSYuri Pankovor 6444585130bSYuri Pankov.Fn fts_read 6454585130bSYuri Pankovon the same file hierarchy stream. 6464585130bSYuri Pankov.Pp 6474585130bSYuri Pankov.Fa options 6484585130bSYuri Pankovmay be set to the following value: 6494585130bSYuri Pankov.Bl -tag -width FTS_NAMEONLY 6504585130bSYuri Pankov.It Dv FTS_NAMEONLY 6514585130bSYuri PankovOnly the names of the files are needed. 6524585130bSYuri PankovThe contents of all the fields in the returned linked list of structures 6534585130bSYuri Pankovare undefined with the exception of the 6544585130bSYuri Pankov.Fa fts_name 6554585130bSYuri Pankovand 6564585130bSYuri Pankov.Fa fts_namelen 6574585130bSYuri Pankovfields. 6584585130bSYuri Pankov.El 6594585130bSYuri Pankov.Ss FTS_SET 6604585130bSYuri PankovThe function 6614585130bSYuri Pankov.Fn fts_set 6624585130bSYuri Pankovallows the user application to determine further processing for the file 6634585130bSYuri Pankov.Fa f 6644585130bSYuri Pankovof the stream 6654585130bSYuri Pankov.Fa ftsp . 6664585130bSYuri PankovThe 6674585130bSYuri Pankov.Fn fts_set 6684585130bSYuri Pankovfunction returns 0 on success or \-1 if an error occurred. 6694585130bSYuri Pankov.Fa option 6704585130bSYuri Pankovmust be set to one of the following values: 6714585130bSYuri Pankov.Bl -tag -width FTS_PHYSICAL 6724585130bSYuri Pankov.It Dv FTS_AGAIN 6734585130bSYuri PankovRe-visit the file; any file type may be re-visited. 6744585130bSYuri PankovThe next call to 6754585130bSYuri Pankov.Fn fts_read 6764585130bSYuri Pankovwill return the referenced file. 6774585130bSYuri PankovThe 6784585130bSYuri Pankov.Fa fts_stat 6794585130bSYuri Pankovand 6804585130bSYuri Pankov.Fa fts_info 6814585130bSYuri Pankovfields of the structure will be reinitialized at that time, 6824585130bSYuri Pankovbut no other fields will have been changed. 6834585130bSYuri PankovThis option is meaningful only for the most recently returned 6844585130bSYuri Pankovfile from 6854585130bSYuri Pankov.Fn fts_read . 6864585130bSYuri PankovNormal use is for post-order directory visits, where it causes the 6874585130bSYuri Pankovdirectory to be re-visited 6884585130bSYuri Pankov.Pq in both pre and post-order 6894585130bSYuri Pankovas well as all of its descendants. 6904585130bSYuri Pankov.It Dv FTS_FOLLOW 6914585130bSYuri PankovThe referenced file must be a symbolic link. 6924585130bSYuri PankovIf the referenced file is the one most recently returned by 6934585130bSYuri Pankov.Fn fts_read , 6944585130bSYuri Pankovthe next call to 6954585130bSYuri Pankov.Fn fts_read 6964585130bSYuri Pankovreturns the file with the 6974585130bSYuri Pankov.Fa fts_info 6984585130bSYuri Pankovand 6994585130bSYuri Pankov.Fa fts_statp 7004585130bSYuri Pankovfields reinitialized to reflect the target of the symbolic link instead 7014585130bSYuri Pankovof the symbolic link itself. 7024585130bSYuri PankovIf the file is one of those most recently returned by 7034585130bSYuri Pankov.Fn fts_children , 7044585130bSYuri Pankovthe 7054585130bSYuri Pankov.Fa fts_info 7064585130bSYuri Pankovand 7074585130bSYuri Pankov.Fa fts_statp 7084585130bSYuri Pankovfields of the structure, when returned by 7094585130bSYuri Pankov.Fn fts_read , 7104585130bSYuri Pankovwill reflect the target of the symbolic link instead of the symbolic link 7114585130bSYuri Pankovitself. 7124585130bSYuri PankovIn either case if the target of the symbolic link does not exist, the 7134585130bSYuri Pankovfields of the returned structure will be unchanged and the 7144585130bSYuri Pankov.Fa fts_info 7154585130bSYuri Pankovfield will be set to 7164585130bSYuri Pankov.Dv FTS_SLNONE . 7174585130bSYuri Pankov.Pp 7184585130bSYuri PankovIf the target of the link is a directory, the pre-order return, followed 7194585130bSYuri Pankovby the return of all of its descendants, followed by a post-order return, 7204585130bSYuri Pankovis done. 7214585130bSYuri Pankov.It Dv FTS_SKIP 7224585130bSYuri PankovNo descendants of this file are visited. 7234585130bSYuri PankovThe file may be one of those most recently returned by either 7244585130bSYuri Pankov.Fn fts_children 7254585130bSYuri Pankovor 7264585130bSYuri Pankov.Fn fts_read . 7274585130bSYuri Pankov.El 7284585130bSYuri Pankov.Ss FTS_CLOSE 7294585130bSYuri PankovThe 7304585130bSYuri Pankov.Fn fts_close 7314585130bSYuri Pankovfunction closes a file hierarchy stream 7324585130bSYuri Pankov.Fa ftsp 7334585130bSYuri Pankovand restores the current directory to the directory from which 7344585130bSYuri Pankov.Fn fts_open 7354585130bSYuri Pankovwas called to open 7364585130bSYuri Pankov.Fa ftsp . 7374585130bSYuri Pankov.Rv -std fts_close 7384585130bSYuri Pankov.Ss Locking 7394585130bSYuri PankovThe fts routines provide no locking. 7404585130bSYuri PankovWhile the 7414585130bSYuri Pankov.Fn fts_open 7424585130bSYuri Pankovfunction is 7434585130bSYuri Pankov.Sy Safe 7444585130bSYuri Pankovand can be called from multiple threads simultaneously, the individual 7454585130bSYuri Pankovhandles returned from the 7464585130bSYuri Pankov.Fn fts_open 7474585130bSYuri Pankovfunction are not thread-safe. 7484585130bSYuri PankovIf callers need to operate on a single 7494585130bSYuri Pankov.Vt FTS 7504585130bSYuri Pankovstructure, then it is their responsibility to ensure that none of the 7514585130bSYuri Pankovother functions are called from multiple threads simultaneously. 7524585130bSYuri PankovThis implies that the 7534585130bSYuri Pankov.Fn fts_read , 7544585130bSYuri Pankov.Fn fts_children , 7554585130bSYuri Pankov.Fn fts_set , 7564585130bSYuri Pankovand 7574585130bSYuri Pankov.Fn fts_close 7584585130bSYuri Pankovfunctions are 7594585130bSYuri Pankov.Sy Unsafe . 7604585130bSYuri Pankov.Pp 7614585130bSYuri PankovThese routines are not 7624585130bSYuri Pankov.Sy Async-Signal-Safe 7634585130bSYuri Pankovand callers should not assume that the implementation of these functions 7644585130bSYuri Pankovwill be 7654585130bSYuri Pankov.Sy Fork-Safe . 7664585130bSYuri PankovIf callers implement their own locking structures around the use of 7674585130bSYuri Pankovthese routines, they must ensure that those locks are accounted for when 7684585130bSYuri Pankovforking by the use of routines such as 7694585130bSYuri Pankov.Xr pthread_atfork 3C . 7704585130bSYuri Pankov.Sh ERRORS 7714585130bSYuri PankovThe function 7724585130bSYuri Pankov.Fn fts_open 7734585130bSYuri Pankovmay fail and set 7744585130bSYuri Pankov.Va errno 7754585130bSYuri Pankovfor any of the errors specified for the library functions 7764585130bSYuri Pankov.Xr open 2 7774585130bSYuri Pankovand 7784585130bSYuri Pankov.Xr malloc 3C . 7794585130bSYuri Pankov.Pp 7804585130bSYuri PankovThe function 7814585130bSYuri Pankov.Fn fts_close 7824585130bSYuri Pankovmay fail and set 7834585130bSYuri Pankov.Va errno 7844585130bSYuri Pankovfor any of the errors specified for the library function 7854585130bSYuri Pankov.Xr fchdir 2 . 7864585130bSYuri Pankov.Pp 7874585130bSYuri PankovThe functions 7884585130bSYuri Pankov.Fn fts_read 7894585130bSYuri Pankovand 7904585130bSYuri Pankov.Fn fts_children 7914585130bSYuri Pankovmay fail and set 7924585130bSYuri Pankov.Va errno 7934585130bSYuri Pankovfor any of the errors specified for the library functions 7944585130bSYuri Pankov.Xr chdir 2 , 7954585130bSYuri Pankov.Xr malloc 3C , 7964585130bSYuri Pankov.Xr opendir 3C , 7974585130bSYuri Pankov.Xr readdir 3C 7984585130bSYuri Pankovand 7994585130bSYuri Pankov.Xr stat 2 . 8004585130bSYuri Pankov.Pp 8014585130bSYuri PankovIn addition, 8024585130bSYuri Pankov.Fn fts_children , 8034585130bSYuri Pankov.Fn fts_open 8044585130bSYuri Pankovand 8054585130bSYuri Pankov.Fn fts_set 8064585130bSYuri Pankovmay fail and set 8074585130bSYuri Pankov.Va errno 8084585130bSYuri Pankovas follows: 8094585130bSYuri Pankov.Bl -tag -width Er 8104585130bSYuri Pankov.It Er EINVAL 8114585130bSYuri PankovA specified option is invalid or 8124585130bSYuri Pankov.Fa path_argv 8134585130bSYuri Pankovis empty. 8144585130bSYuri Pankov.El 8154585130bSYuri Pankov.Sh INTERFACE STABILITY 8164585130bSYuri Pankov.Sy Committed . 8174585130bSYuri Pankov.Sh MT-LEVEL 8184585130bSYuri PankovSee 8194585130bSYuri Pankov.Sx Locking . 8204585130bSYuri Pankov.Sh SEE ALSO 8214585130bSYuri Pankov.Xr find 1 , 8224585130bSYuri Pankov.Xr chdir 2 , 8234585130bSYuri Pankov.Xr stat 2 , 8244585130bSYuri Pankov.Xr qsort 3C , 825*bbf21555SRichard Lowe.Xr attributes 7 826