sl@0: /** @file  ../include/ftw.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @fn  ftw(const char *path, int (*fn)(const char *, const struct stat *, int), int nfds)
sl@0: @param path
sl@0: @param fn
sl@0: @param nfds
sl@0: @return   If the tree is exhausted, ftw() shall return 0.
sl@0: If the function pointed to by fn returns a non-zero value, ftw() shall stop its tree traversal and 
sl@0: return whatever value was returned by the function pointed to by fn. 
sl@0: If ftw() detects an error, it shall return -1 and set errno to indicate the error.
sl@0: 
sl@0: The ftw() function shall recursively descend the directory hierarchy rooted in path.
sl@0: For each object in the hierarchy, ftw() shall call the function pointed to by fn,
sl@0: passing it a pointer to a null-terminated character string containing the name of the object,
sl@0: a pointer to a stat structure containing information about the object, and an integer.Possible values of the integer are:
sl@0: FTW_D
sl@0:     For a directory.
sl@0: FTW_DNR
sl@0:     For a directory that cannot be read.
sl@0: FTW_F
sl@0:     For a file.
sl@0: FTW_SL
sl@0:     For a symbolic link (but see also FTW_NS below).
sl@0: FTW_NS
sl@0:     For an object other than a symbolic link on which stat() could not successfully be executed.
sl@0:     If the object is a symbolic link and stat() failed,
sl@0:     it is unspecified whether ftw() passes FTW_SL or FTW_NS to the user-supplied function. 
sl@0:     
sl@0: The argument nfds should be in the range [1, {OPEN_MAX}].
sl@0: 
sl@0: Errors:
sl@0: [EACCES]
sl@0:     Search permission is denied for any component of path or read permission is denied for path.
sl@0: [ELOOP]
sl@0:     A loop exists in symbolic links encountered during resolution of the path argument.
sl@0: [ENAMETOOLONG]
sl@0:     The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
sl@0: [ENOENT]
sl@0:     A component of path does not name an existing file or path is an empty string.
sl@0: [ENOTDIR]
sl@0:     A component of path is not a directory.
sl@0: [EOVERFLOW]
sl@0:     A field in the stat structure cannot be represented correctly in the current programming environment
sl@0:     for one or more files found in the file hierarchy. 
sl@0:     
sl@0: Examples:
sl@0: @code
sl@0: /*  Detailed description:  Sample usage of ftw system call
sl@0:  *  Preconditions:  Function fn with the specified prototype should be defined and
sl@0:  *  should have atleast two objects in the current working directory. 
sl@0:  */
sl@0: #include <ftw.h>
sl@0: #include <stdlib.h>
sl@0: #include <stdio.h>
sl@0: 
sl@0: if (ftw(".", fn, 2) != 0) {
sl@0:     perror("ftw"); exit(2);
sl@0: }
sl@0: else
sl@0: {
sl@0: 	printf("ftw call succeded");
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: ftw call succeded
sl@0: 
sl@0: @endcode
sl@0: @see stat()
sl@0: 
sl@0: 
sl@0: @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  ftw64(const char *path, int (*fn)(const char *, const struct stat64 *, int), int nfds)
sl@0: @param path
sl@0: @param fn
sl@0: @param nfds
sl@0: @return   If the tree is exhausted, ftw64() shall return 0.
sl@0: If the function pointed to by fn returns a non-zero value, ftw64() shall stop its tree traversal and 
sl@0: return whatever value was returned by the function pointed to by fn. 
sl@0: If ftw64() detects an error, it shall return -1 and set errno to indicate the error.
sl@0: 
sl@0: For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
sl@0: 
sl@0: @see ftw()
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_F
sl@0: 
sl@0: 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: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_D
sl@0: 
sl@0: Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0: Directory.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_DNR
sl@0: 
sl@0: Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0: Directory without read permission.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_DP
sl@0: 
sl@0: Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0: Directory with subdirectories visited. A file on which stat could not successfully be
sl@0: executed.
sl@0: 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_NS
sl@0: 
sl@0: Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0: A file on which stat could not successfully be executed.
sl@0: 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_SL
sl@0: 
sl@0: Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0: Symbolic link.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_SLN
sl@0: 
sl@0: Valid flags for the 3rd argument to the function that is passed as the second argument to ftw(3) and nftw(3).
sl@0: Sym link that names a nonexistent file. 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def FTW_PHYS	
sl@0: 
sl@0: Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0: Physical walk, don't follow sym links.
sl@0: 		
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @def FTW_MOUNT			
sl@0: 
sl@0: Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0: The walk does not cross a mount point.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @def FTW_DEPTH			
sl@0: 
sl@0: Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0: Subdirs visited before the dir itself. 
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @def FTW_CHDIR			
sl@0: 
sl@0: Flags for use as the 4th argument to nftw(3).  These may be ORed together.
sl@0: Change to a directory before reading it.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: