os/ossrv/genericopenlibs/openenvcore/include/ftw.dosc
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
sl@0
     1
/** @file  ../include/ftw.h
sl@0
     2
@internalComponent
sl@0
     3
*/
sl@0
     4
sl@0
     5
/** @fn  ftw(const char *path, int (*fn)(const char *, const struct stat *, int), int nfds)
sl@0
     6
@param path
sl@0
     7
@param fn
sl@0
     8
@param nfds
sl@0
     9
@return   If the tree is exhausted, ftw() shall return 0.
sl@0
    10
If the function pointed to by fn returns a non-zero value, ftw() shall stop its tree traversal and 
sl@0
    11
return whatever value was returned by the function pointed to by fn. 
sl@0
    12
If ftw() detects an error, it shall return -1 and set errno to indicate the error.
sl@0
    13
sl@0
    14
The ftw() function shall recursively descend the directory hierarchy rooted in path.
sl@0
    15
For each object in the hierarchy, ftw() shall call the function pointed to by fn,
sl@0
    16
passing it a pointer to a null-terminated character string containing the name of the object,
sl@0
    17
a pointer to a stat structure containing information about the object, and an integer.Possible values of the integer are:
sl@0
    18
FTW_D
sl@0
    19
    For a directory.
sl@0
    20
FTW_DNR
sl@0
    21
    For a directory that cannot be read.
sl@0
    22
FTW_F
sl@0
    23
    For a file.
sl@0
    24
FTW_SL
sl@0
    25
    For a symbolic link (but see also FTW_NS below).
sl@0
    26
FTW_NS
sl@0
    27
    For an object other than a symbolic link on which stat() could not successfully be executed.
sl@0
    28
    If the object is a symbolic link and stat() failed,
sl@0
    29
    it is unspecified whether ftw() passes FTW_SL or FTW_NS to the user-supplied function. 
sl@0
    30
    
sl@0
    31
The argument nfds should be in the range [1, {OPEN_MAX}].
sl@0
    32
sl@0
    33
Errors:
sl@0
    34
[EACCES]
sl@0
    35
    Search permission is denied for any component of path or read permission is denied for path.
sl@0
    36
[ELOOP]
sl@0
    37
    A loop exists in symbolic links encountered during resolution of the path argument.
sl@0
    38
[ENAMETOOLONG]
sl@0
    39
    The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
sl@0
    40
[ENOENT]
sl@0
    41
    A component of path does not name an existing file or path is an empty string.
sl@0
    42
[ENOTDIR]
sl@0
    43
    A component of path is not a directory.
sl@0
    44
[EOVERFLOW]
sl@0
    45
    A field in the stat structure cannot be represented correctly in the current programming environment
sl@0
    46
    for one or more files found in the file hierarchy. 
sl@0
    47
    
sl@0
    48
Examples:
sl@0
    49
@code
sl@0
    50
/*  Detailed description:  Sample usage of ftw system call
sl@0
    51
 *  Preconditions:  Function fn with the specified prototype should be defined and
sl@0
    52
 *  should have atleast two objects in the current working directory. 
sl@0
    53
 */
sl@0
    54
#include <ftw.h>
sl@0
    55
#include <stdlib.h>
sl@0
    56
#include <stdio.h>
sl@0
    57
sl@0
    58
if (ftw(".", fn, 2) != 0) {
sl@0
    59
    perror("ftw"); exit(2);
sl@0
    60
}
sl@0
    61
else
sl@0
    62
{
sl@0
    63
	printf("ftw call succeded");
sl@0
    64
}
sl@0
    65
sl@0
    66
@endcode
sl@0
    67
 Output
sl@0
    68
@code
sl@0
    69
ftw call succeded
sl@0
    70
sl@0
    71
@endcode
sl@0
    72
@see stat()
sl@0
    73
sl@0
    74
sl@0
    75
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0
    76
sl@0
    77
@publishedAll
sl@0
    78
@externallyDefinedApi
sl@0
    79
*/
sl@0
    80
sl@0
    81
/** @fn  ftw64(const char *path, int (*fn)(const char *, const struct stat64 *, int), int nfds)
sl@0
    82
@param path
sl@0
    83
@param fn
sl@0
    84
@param nfds
sl@0
    85
@return   If the tree is exhausted, ftw64() shall return 0.
sl@0
    86
If the function pointed to by fn returns a non-zero value, ftw64() shall stop its tree traversal and 
sl@0
    87
return whatever value was returned by the function pointed to by fn. 
sl@0
    88
If ftw64() detects an error, it shall return -1 and set errno to indicate the error.
sl@0
    89
sl@0
    90
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0
    91
sl@0
    92
@see ftw()
sl@0
    93
sl@0
    94
@publishedAll
sl@0
    95
@externallyDefinedApi
sl@0
    96
*/
sl@0
    97
sl@0
    98
/** @def FTW_F
sl@0
    99
sl@0
   100
Regular File. Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   101
sl@0
   102
@publishedAll
sl@0
   103
@externallyDefinedApi
sl@0
   104
*/
sl@0
   105
sl@0
   106
/** @def FTW_D
sl@0
   107
sl@0
   108
Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   109
Directory.
sl@0
   110
sl@0
   111
@publishedAll
sl@0
   112
@externallyDefinedApi
sl@0
   113
*/
sl@0
   114
sl@0
   115
/** @def FTW_DNR
sl@0
   116
sl@0
   117
Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   118
Directory without read permission.
sl@0
   119
sl@0
   120
@publishedAll
sl@0
   121
@externallyDefinedApi
sl@0
   122
*/
sl@0
   123
sl@0
   124
/** @def FTW_DP
sl@0
   125
sl@0
   126
Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   127
Directory with subdirectories visited. A file on which stat could not successfully be
sl@0
   128
executed.
sl@0
   129
sl@0
   130
sl@0
   131
@publishedAll
sl@0
   132
@externallyDefinedApi
sl@0
   133
*/
sl@0
   134
sl@0
   135
/** @def FTW_NS
sl@0
   136
sl@0
   137
Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   138
A file on which stat could not successfully be executed.
sl@0
   139
sl@0
   140
sl@0
   141
@publishedAll
sl@0
   142
@externallyDefinedApi
sl@0
   143
*/
sl@0
   144
sl@0
   145
/** @def FTW_SL
sl@0
   146
sl@0
   147
Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   148
Symbolic link.
sl@0
   149
sl@0
   150
@publishedAll
sl@0
   151
@externallyDefinedApi
sl@0
   152
*/
sl@0
   153
sl@0
   154
/** @def FTW_SLN
sl@0
   155
sl@0
   156
Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0
   157
Sym link that names a nonexistent file. 
sl@0
   158
sl@0
   159
@publishedAll
sl@0
   160
@externallyDefinedApi
sl@0
   161
*/
sl@0
   162
sl@0
   163
/** @def FTW_PHYS	
sl@0
   164
sl@0
   165
Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0
   166
Physical walk, don't follow sym links.
sl@0
   167
		
sl@0
   168
@publishedAll
sl@0
   169
@released
sl@0
   170
*/
sl@0
   171
sl@0
   172
/** @def FTW_MOUNT			
sl@0
   173
sl@0
   174
Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0
   175
The walk does not cross a mount point.
sl@0
   176
sl@0
   177
@publishedAll
sl@0
   178
@released
sl@0
   179
*/
sl@0
   180
sl@0
   181
/** @def FTW_DEPTH			
sl@0
   182
sl@0
   183
Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0
   184
Subdirs visited before the dir itself. 
sl@0
   185
sl@0
   186
@publishedAll
sl@0
   187
@released
sl@0
   188
*/
sl@0
   189
sl@0
   190
/** @def FTW_CHDIR			
sl@0
   191
sl@0
   192
Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0
   193
Change to a directory before reading it.
sl@0
   194
sl@0
   195
@publishedAll
sl@0
   196
@released
sl@0
   197
*/
sl@0
   198