ftw.h 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  1. /****************************************************************************
  2. * include/ftw.h
  3. *
  4. * Licensed to the Apache Software Foundation (ASF) under one or more
  5. * contributor license agreements. See the NOTICE file distributed with
  6. * this work for additional information regarding copyright ownership. The
  7. * ASF licenses this file to you under the Apache License, Version 2.0 (the
  8. * "License"); you may not use this file except in compliance with the
  9. * License. You may obtain a copy of the License at
  10. *
  11. * http://www.apache.org/licenses/LICENSE-2.0
  12. *
  13. * Unless required by applicable law or agreed to in writing, software
  14. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  15. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  16. * License for the specific language governing permissions and limitations
  17. * under the License.
  18. *
  19. ****************************************************************************/
  20. #ifndef __INCLUDE_FTW_H
  21. #define __INCLUDE_FTW_H
  22. /****************************************************************************
  23. * Included Files
  24. ****************************************************************************/
  25. /* The <ftw.h> header defines the stat structure and the symbolic names for
  26. * st_mode and the file type test macros as described in sys/stat.h.
  27. *
  28. * Inclusion of the <ftw.h> header may also make visible all symbols from
  29. * sys/stat.h.
  30. */
  31. #include <sys/stat.h>
  32. /****************************************************************************
  33. * Pre-processor Definitions
  34. ****************************************************************************/
  35. /* Macros for use as values of the third argument to the application-supplied
  36. * function that is passed as the second argument to ftw() and nftw():
  37. */
  38. #define FTW_F 0 /* File */
  39. #define FTW_D 1 /* Directory */
  40. #define FTW_DNR 2 /* Directory without read permission */
  41. #define FTW_DP 3 /* Directory with subdirectories visited */
  42. #define FTW_NS 4 /* Unknown type; stat() failed */
  43. #define FTW_SL 5 /* Symbolic link */
  44. #define FTW_SLN 6 /* Symbolic link that names a nonexistent file */
  45. /* Macros for use as values of the fourth argument to nftw() */
  46. #define FTW_PHYS 1 /* Physical walk, does not follow symbolic links.
  47. * Otherwise, nftw() follows links but does not walk
  48. * down any path that crosses itself. */
  49. #define FTW_MOUNT 2 /* The walk does not cross a mount point. */
  50. #define FTW_DEPTH 4 /* All subdirectories are visited before the directory
  51. * itself. */
  52. #ifndef CONFIG_DISABLE_ENVIRON
  53. #define FTW_CHDIR 8 /* The walk changes to each directory before reading
  54. * it. */
  55. #endif
  56. /****************************************************************************
  57. * Public Types
  58. ****************************************************************************/
  59. /* The fourth argument of the ftw/nftw callback is a pointer to an FTW
  60. * structure. The value of base is the offset of the object's filename in
  61. * the pathname passed as the first argument to the callback. The value of
  62. * level indicates depth relative to the root of the walk, where the root
  63. * level is 0.
  64. */
  65. struct FTW
  66. {
  67. int base; /* Offset of object's filename in the pathname */
  68. int level; /* Depth relative to the root of the walk */
  69. };
  70. /* This is the type of the ftw callback */
  71. typedef int (*ftw_cb_t)(FAR const char *path, FAR const struct stat *buf,
  72. int info);
  73. /* This is the type of the nftw callback */
  74. typedef int (*nftw_cb_t)(FAR const char *path, FAR const struct stat *buf,
  75. int info, FAR struct FTW *pftw);
  76. /****************************************************************************
  77. * Public Function Prototypes
  78. ****************************************************************************/
  79. #ifdef __cplusplus
  80. #define EXTERN extern "C"
  81. extern "C"
  82. {
  83. #else
  84. #define EXTERN extern
  85. #endif
  86. /****************************************************************************
  87. * Name: ftw
  88. *
  89. * Description:
  90. * The ftw() function will recursively descend the directory hierarchy
  91. * rooted in 'path'. For each object in the hierarchy, ftw() will call
  92. * the function pointed to by 'fn', passing it a pointer to a null-
  93. * terminated character string containing the name of the object, a
  94. * pointer to a stat structure containing information about the object,
  95. * and an integer that characterizes object.
  96. *
  97. * The ftw() function will visit a directory before visiting any of its
  98. * descendants.
  99. *
  100. * The ftw() function will use at most one file descriptor for each level
  101. * in the tree.
  102. *
  103. * The tree traversal will continue until either the tree is exhausted, an
  104. * invocation of 'fn' returns a non-zero value, or some error, other than
  105. * EACCES, is detected within ftw().
  106. *
  107. * When ftw() returns it will close any directory streams and file
  108. * descriptors it uses not counting any opened by the application-supplied
  109. * 'fn' function.
  110. *
  111. * The results are unspecified if the application-supplied 'fn' function
  112. * does not preserve the current working directory.
  113. *
  114. * The ftw() function need not be reentrant. A function that is not
  115. * required to be reentrant is not required to be thread-safe.
  116. *
  117. * Input Parameters:
  118. * path - The 'root' of the directory hierarchy to descend
  119. * fn - The callback function to be invoked as each object in the
  120. * hierarchy is encountered.
  121. * fdlimit - The fdlimit argument specifies the maximum number of directory
  122. * streams or file descriptors or both available for use by ftw()
  123. * while traversing the tree.The maximum depth of the directories
  124. * to visit. The fdlimit argument should be in the range [1,
  125. * {OPEN_MAX}].
  126. *
  127. * Returned Value:
  128. * If the tree is exhausted, ftw() will return 0. If the function pointed
  129. * to by fn returns a non-zero value, ftw() will stop its tree traversal
  130. * and return whatever value was returned by the function pointed to by
  131. * 'fn'. If ftw() detects an error, it will return -1 and set errno to
  132. * indicate the error.
  133. *
  134. * If ftw() encounters an error other than EACCES (see FTW_DNR and FTW_NS),
  135. * it will return -1 and set errno to indicate the error. The external
  136. * variable errno may contain any error value that is possible when a
  137. * directory is opened or when one of the stat functions is executed on a
  138. * directory or file.
  139. *
  140. ****************************************************************************/
  141. int ftw(FAR const char *path, ftw_cb_t fn, int fdlimit);
  142. /****************************************************************************
  143. * Name: nftw
  144. *
  145. * Description:
  146. * The nftw() function will recursively descend the directory hierarchy
  147. * rooted in 'path'. The nftw() function has a similar effect to ftw()
  148. * except that it takes an additional argument 'flags'
  149. *
  150. * Input Parameters:
  151. *
  152. * path - The 'root' of the directory hierarchy to descend
  153. * fn - The callback function to be invoked as each object in the
  154. * hierarchy is encountered.
  155. * fdlimit - The fdlimit argument specifies the maximum number of directory
  156. * streams or file descriptors or both available for use by
  157. * nftw() while traversing the tree.The maximum depth of the
  158. * directories to visit. The fdlimit argument should be in the
  159. * range [1, {OPEN_MAX}].
  160. * flags - A bitwise-inclusive OR of zero or more of the following flags:
  161. *
  162. * FTW_CHDIR
  163. * If set, nftw() will change the current working directory to each
  164. * directory as it reports files in that directory. If clear, nftw()
  165. * will not change the current working directory.
  166. * FTW_DEPTH
  167. * If set, nftw() will report all files in a directory before
  168. * reporting the directory itself. If clear, nftw() will report any
  169. * directory before reporting the files in that directory.
  170. * FTW_MOUNT
  171. * If set, nftw() will only report files in the same file system as
  172. * path. If clear, nftw() will report all files encountered during
  173. * the walk.
  174. * FTW_PHYS
  175. * If set, nftw() will perform a physical walk and will not follow
  176. * symbolic links.
  177. *
  178. * Returned Value:
  179. * If the tree is exhausted, nftw() will return 0. If the function pointed
  180. * to by fn returns a non-zero value, nftw() will stop its tree traversal
  181. * and return whatever value was returned by the function pointed to by
  182. * 'fn'. If nftw() detects an error, it will return -1 and set errno to
  183. * indicate the error.
  184. *
  185. * If nftw() encounters an error other than EACCES (see FTW_DNR and
  186. * FTW_NS), it will return -1 and set errno to indicate the error. The
  187. * external variable errno may contain any error value that is possible
  188. * when a directory is opened or when one of the stat functions is
  189. * executed on a directory or file.
  190. *
  191. *
  192. ****************************************************************************/
  193. int nftw(FAR const char *path, nftw_cb_t fn, int fdlimit, int flags);
  194. #undef EXTERN
  195. #ifdef __cplusplus
  196. }
  197. #endif
  198. #endif /* __INCLUDE_FTW_H */