1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/ftw.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,198 @@
1.4 +/** @file ../include/ftw.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +/** @fn ftw(const char *path, int (*fn)(const char *, const struct stat *, int), int nfds)
1.9 +@param path
1.10 +@param fn
1.11 +@param nfds
1.12 +@return If the tree is exhausted, ftw() shall return 0.
1.13 +If the function pointed to by fn returns a non-zero value, ftw() shall stop its tree traversal and
1.14 +return whatever value was returned by the function pointed to by fn.
1.15 +If ftw() detects an error, it shall return -1 and set errno to indicate the error.
1.16 +
1.17 +The ftw() function shall recursively descend the directory hierarchy rooted in path.
1.18 +For each object in the hierarchy, ftw() shall call the function pointed to by fn,
1.19 +passing it a pointer to a null-terminated character string containing the name of the object,
1.20 +a pointer to a stat structure containing information about the object, and an integer.Possible values of the integer are:
1.21 +FTW_D
1.22 + For a directory.
1.23 +FTW_DNR
1.24 + For a directory that cannot be read.
1.25 +FTW_F
1.26 + For a file.
1.27 +FTW_SL
1.28 + For a symbolic link (but see also FTW_NS below).
1.29 +FTW_NS
1.30 + For an object other than a symbolic link on which stat() could not successfully be executed.
1.31 + If the object is a symbolic link and stat() failed,
1.32 + it is unspecified whether ftw() passes FTW_SL or FTW_NS to the user-supplied function.
1.33 +
1.34 +The argument nfds should be in the range [1, {OPEN_MAX}].
1.35 +
1.36 +Errors:
1.37 +[EACCES]
1.38 + Search permission is denied for any component of path or read permission is denied for path.
1.39 +[ELOOP]
1.40 + A loop exists in symbolic links encountered during resolution of the path argument.
1.41 +[ENAMETOOLONG]
1.42 + The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
1.43 +[ENOENT]
1.44 + A component of path does not name an existing file or path is an empty string.
1.45 +[ENOTDIR]
1.46 + A component of path is not a directory.
1.47 +[EOVERFLOW]
1.48 + A field in the stat structure cannot be represented correctly in the current programming environment
1.49 + for one or more files found in the file hierarchy.
1.50 +
1.51 +Examples:
1.52 +@code
1.53 +/* Detailed description: Sample usage of ftw system call
1.54 + * Preconditions: Function fn with the specified prototype should be defined and
1.55 + * should have atleast two objects in the current working directory.
1.56 + */
1.57 +#include <ftw.h>
1.58 +#include <stdlib.h>
1.59 +#include <stdio.h>
1.60 +
1.61 +if (ftw(".", fn, 2) != 0) {
1.62 + perror("ftw"); exit(2);
1.63 +}
1.64 +else
1.65 +{
1.66 + printf("ftw call succeded");
1.67 +}
1.68 +
1.69 +@endcode
1.70 + Output
1.71 +@code
1.72 +ftw call succeded
1.73 +
1.74 +@endcode
1.75 +@see stat()
1.76 +
1.77 +
1.78 +@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
1.79 +
1.80 +@publishedAll
1.81 +@externallyDefinedApi
1.82 +*/
1.83 +
1.84 +/** @fn ftw64(const char *path, int (*fn)(const char *, const struct stat64 *, int), int nfds)
1.85 +@param path
1.86 +@param fn
1.87 +@param nfds
1.88 +@return If the tree is exhausted, ftw64() shall return 0.
1.89 +If the function pointed to by fn returns a non-zero value, ftw64() shall stop its tree traversal and
1.90 +return whatever value was returned by the function pointed to by fn.
1.91 +If ftw64() detects an error, it shall return -1 and set errno to indicate the error.
1.92 +
1.93 +For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
1.94 +
1.95 +@see ftw()
1.96 +
1.97 +@publishedAll
1.98 +@externallyDefinedApi
1.99 +*/
1.100 +
1.101 +/** @def FTW_F
1.102 +
1.103 +Regular File. Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.104 +
1.105 +@publishedAll
1.106 +@externallyDefinedApi
1.107 +*/
1.108 +
1.109 +/** @def FTW_D
1.110 +
1.111 +Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.112 +Directory.
1.113 +
1.114 +@publishedAll
1.115 +@externallyDefinedApi
1.116 +*/
1.117 +
1.118 +/** @def FTW_DNR
1.119 +
1.120 +Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.121 +Directory without read permission.
1.122 +
1.123 +@publishedAll
1.124 +@externallyDefinedApi
1.125 +*/
1.126 +
1.127 +/** @def FTW_DP
1.128 +
1.129 +Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.130 +Directory with subdirectories visited. A file on which stat could not successfully be
1.131 +executed.
1.132 +
1.133 +
1.134 +@publishedAll
1.135 +@externallyDefinedApi
1.136 +*/
1.137 +
1.138 +/** @def FTW_NS
1.139 +
1.140 +Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.141 +A file on which stat could not successfully be executed.
1.142 +
1.143 +
1.144 +@publishedAll
1.145 +@externallyDefinedApi
1.146 +*/
1.147 +
1.148 +/** @def FTW_SL
1.149 +
1.150 +Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.151 +Symbolic link.
1.152 +
1.153 +@publishedAll
1.154 +@externallyDefinedApi
1.155 +*/
1.156 +
1.157 +/** @def FTW_SLN
1.158 +
1.159 +Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
1.160 +Sym link that names a nonexistent file.
1.161 +
1.162 +@publishedAll
1.163 +@externallyDefinedApi
1.164 +*/
1.165 +
1.166 +/** @def FTW_PHYS
1.167 +
1.168 +Flags for use as the 4th argument to nftw(3). These may be ORed together.
1.169 +Physical walk, don't follow sym links.
1.170 +
1.171 +@publishedAll
1.172 +@released
1.173 +*/
1.174 +
1.175 +/** @def FTW_MOUNT
1.176 +
1.177 +Flags for use as the 4th argument to nftw(3). These may be ORed together.
1.178 +The walk does not cross a mount point.
1.179 +
1.180 +@publishedAll
1.181 +@released
1.182 +*/
1.183 +
1.184 +/** @def FTW_DEPTH
1.185 +
1.186 +Flags for use as the 4th argument to nftw(3). These may be ORed together.
1.187 +Subdirs visited before the dir itself.
1.188 +
1.189 +@publishedAll
1.190 +@released
1.191 +*/
1.192 +
1.193 +/** @def FTW_CHDIR
1.194 +
1.195 +Flags for use as the 4th argument to nftw(3). These may be ORed together.
1.196 +Change to a directory before reading it.
1.197 +
1.198 +@publishedAll
1.199 +@released
1.200 +*/
1.201 +