logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

nftw.3p (9321B)


  1. '\" et
  2. .TH NFTW "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. nftw
  12. \(em walk a file tree
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <ftw.h>
  17. .P
  18. int nftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *,
  19. const struct stat *, int, struct FTW *), int \fIfd_limit\fP, int \fIflags\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fInftw\fR()
  24. function shall recursively descend the directory hierarchy rooted in
  25. .IR path .
  26. The
  27. \fInftw\fR()
  28. function has a similar effect to
  29. \fIftw\fR()
  30. except that it takes an additional argument
  31. .IR flags ,
  32. which is a bitwise-inclusive OR of zero or more of the following flags:
  33. .IP FTW_CHDIR 12
  34. If set,
  35. \fInftw\fR()
  36. shall change the current working directory to each directory as it
  37. reports files in that directory. If clear,
  38. \fInftw\fR()
  39. shall not change the current working directory.
  40. .IP FTW_DEPTH 12
  41. If set,
  42. \fInftw\fR()
  43. shall report all files in a directory before reporting the directory
  44. itself. If clear,
  45. \fInftw\fR()
  46. shall report any directory before reporting the files in that directory.
  47. .IP FTW_MOUNT 12
  48. If set,
  49. \fInftw\fR()
  50. shall only report files in the same file system as
  51. .IR path .
  52. If clear,
  53. \fInftw\fR()
  54. shall report all files encountered during the walk.
  55. .IP FTW_PHYS 12
  56. If set,
  57. \fInftw\fR()
  58. shall perform a physical walk and shall not follow symbolic links.
  59. .P
  60. If FTW_PHYS is clear and FTW_DEPTH is set,
  61. \fInftw\fR()
  62. shall follow links instead of reporting them, but shall not report any
  63. directory that would be a descendant of itself. If FTW_PHYS is clear
  64. and FTW_DEPTH is clear,
  65. \fInftw\fR()
  66. shall follow links instead of reporting them, but shall not report the
  67. contents of any directory that would be a descendant of itself.
  68. .P
  69. At each file it encounters,
  70. \fInftw\fR()
  71. shall call the user-supplied function
  72. .IR fn
  73. with four arguments:
  74. .IP " *" 4
  75. The first argument is the pathname of the object.
  76. .IP " *" 4
  77. The second argument is a pointer to the
  78. .BR stat
  79. buffer containing information on the object, filled in as if
  80. \fIfstatat\fR(),
  81. \fIstat\fR(),
  82. or
  83. \fIlstat\fR()
  84. had been called to retrieve the information.
  85. .IP " *" 4
  86. The third argument is an integer giving additional information. Its
  87. value is one of the following:
  88. .RS 4
  89. .IP FTW_D 10
  90. The object is a directory.
  91. .IP FTW_DNR 10
  92. The object is a directory that cannot be read. The
  93. .IR fn
  94. function shall not be called for any of its descendants.
  95. .IP FTW_DP 10
  96. The object is a directory and subdirectories have been visited. (This
  97. condition shall only occur if the FTW_DEPTH flag is included in
  98. .IR flags .)
  99. .IP FTW_F 10
  100. The object is a non-directory file.
  101. .IP FTW_NS 10
  102. The
  103. \fIstat\fR()
  104. function failed on the object because of lack of appropriate
  105. permission. The
  106. .BR stat
  107. buffer passed to
  108. .IR fn
  109. is undefined. Failure of
  110. \fIstat\fR()
  111. for any other reason is considered an error and
  112. \fInftw\fR()
  113. shall return \-1.
  114. .IP FTW_SL 10
  115. The object is a symbolic link. (This condition shall only occur if the
  116. FTW_PHYS flag is included in
  117. .IR flags .)
  118. .IP FTW_SLN 10
  119. The object is a symbolic link that does not name an existing file.
  120. (This condition shall only occur if the FTW_PHYS flag is not included in
  121. .IR flags .)
  122. .RE
  123. .IP " *" 4
  124. The fourth argument is a pointer to an
  125. .BR FTW
  126. structure.
  127. The value of
  128. .BR base
  129. is the offset of the object's filename in the pathname passed as the
  130. first argument to
  131. .IR fn .
  132. The value of
  133. .BR level
  134. indicates depth relative to the root of the walk, where the root level
  135. is 0.
  136. .P
  137. The results are unspecified if the application-supplied
  138. .IR fn
  139. function does not preserve the current working directory.
  140. .P
  141. The argument
  142. .IR fd_limit
  143. sets the maximum number of file descriptors that shall be used by
  144. \fInftw\fR()
  145. while traversing the file tree. At most one file descriptor shall be
  146. used for each directory level.
  147. .P
  148. The
  149. \fInftw\fR()
  150. function need not be thread-safe.
  151. .SH "RETURN VALUE"
  152. The
  153. \fInftw\fR()
  154. function shall continue until the first of the following conditions
  155. occurs:
  156. .IP " *" 4
  157. An invocation of
  158. .IR fn
  159. shall return a non-zero value, in which case
  160. \fInftw\fR()
  161. shall return that value.
  162. .IP " *" 4
  163. The
  164. \fInftw\fR()
  165. function detects an error other than
  166. .BR [EACCES]
  167. (see FTW_DNR and FTW_NS above),
  168. in which case
  169. \fInftw\fR()
  170. shall return \-1 and set
  171. .IR errno
  172. to indicate the error.
  173. .IP " *" 4
  174. The tree is exhausted, in which case
  175. \fInftw\fR()
  176. shall return 0.
  177. .SH ERRORS
  178. The
  179. \fInftw\fR()
  180. function shall fail if:
  181. .TP
  182. .BR EACCES
  183. Search permission is denied for any component of
  184. .IR path
  185. or read permission is denied for
  186. .IR path ,
  187. or
  188. .IR fn
  189. returns \-1 and does not reset
  190. .IR errno .
  191. .TP
  192. .BR ELOOP
  193. A loop exists in symbolic links encountered during resolution of the
  194. .IR path
  195. argument.
  196. .TP
  197. .BR ENAMETOOLONG
  198. .br
  199. The length of a component of a pathname is longer than
  200. {NAME_MAX}.
  201. .TP
  202. .BR ENOENT
  203. A component of
  204. .IR path
  205. does not name an existing file or
  206. .IR path
  207. is an empty string.
  208. .TP
  209. .BR ENOTDIR
  210. A component of
  211. .IR path
  212. names an existing file that is neither a directory nor a symbolic link
  213. to a directory.
  214. .TP
  215. .BR EOVERFLOW
  216. A field in the
  217. .BR stat
  218. structure cannot be represented correctly in the current programming
  219. environment for one or more files found in the file hierarchy.
  220. .P
  221. The
  222. \fInftw\fR()
  223. function may fail if:
  224. .TP
  225. .BR ELOOP
  226. More than
  227. {SYMLOOP_MAX}
  228. symbolic links were encountered during resolution of the
  229. .IR path
  230. argument.
  231. .TP
  232. .BR EMFILE
  233. All file descriptors available to the process are currently open.
  234. .TP
  235. .BR ENAMETOOLONG
  236. .br
  237. The length of a pathname exceeds
  238. {PATH_MAX},
  239. or pathname resolution of a symbolic link produced an intermediate
  240. result with a length that exceeds
  241. {PATH_MAX}.
  242. .TP
  243. .BR ENFILE
  244. Too many files are currently open in the system.
  245. .P
  246. In addition,
  247. .IR errno
  248. may be set if the function pointed to by
  249. .IR fn
  250. causes
  251. .IR errno
  252. to be set.
  253. .LP
  254. .IR "The following sections are informative."
  255. .SH EXAMPLES
  256. The following program traverses the directory tree under the path named
  257. in its first command-line argument, or under the current directory if
  258. no argument is supplied. It displays various information about each
  259. file. The second command-line argument can be used to specify characters
  260. that control the value assigned to the
  261. .IR flags
  262. argument when calling
  263. \fInftw\fR().
  264. .sp
  265. .RS 4
  266. .nf
  267. #include <ftw.h>
  268. #include <stdio.h>
  269. #include <stdlib.h>
  270. #include <string.h>
  271. #include <stdint.h>
  272. .P
  273. static int
  274. display_info(const char *fpath, const struct stat *sb,
  275. int tflag, struct FTW *ftwbuf)
  276. {
  277. printf("%-3s %2d %7jd %-40s %d %s\en",
  278. (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
  279. (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ?
  280. (S_ISBLK(sb->st_mode) ? "f b" :
  281. S_ISCHR(sb->st_mode) ? "f c" :
  282. S_ISFIFO(sb->st_mode) ? "f p" :
  283. S_ISREG(sb->st_mode) ? "f r" :
  284. S_ISSOCK(sb->st_mode) ? "f s" : "f ?") :
  285. (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
  286. (tflag == FTW_SLN) ? "sln" : "?",
  287. ftwbuf->level, (intmax_t) sb->st_size,
  288. fpath, ftwbuf->base, fpath + ftwbuf->base);
  289. return 0; /* To tell nftw() to continue */
  290. }
  291. .P
  292. int
  293. main(int argc, char *argv[])
  294. {
  295. int flags = 0;
  296. .P
  297. if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
  298. flags |= FTW_DEPTH;
  299. if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
  300. flags |= FTW_PHYS;
  301. .P
  302. if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == -1)
  303. {
  304. perror("nftw");
  305. exit(EXIT_FAILURE);
  306. }
  307. .P
  308. exit(EXIT_SUCCESS);
  309. }
  310. .fi
  311. .P
  312. .RE
  313. .SH "APPLICATION USAGE"
  314. The
  315. \fInftw\fR()
  316. function may allocate dynamic storage during its operation. If
  317. \fInftw\fR()
  318. is forcibly terminated, such as by
  319. \fIlongjmp\fR()
  320. or
  321. \fIsiglongjmp\fR()
  322. being executed by the function pointed to by
  323. .IR fn
  324. or an interrupt routine,
  325. \fInftw\fR()
  326. does not have a chance to free that storage, so it remains permanently
  327. allocated. A safe way to handle interrupts is to store the fact that an
  328. interrupt has occurred, and arrange to have the function pointed to by
  329. .IR fn
  330. return a non-zero value at its next invocation.
  331. .SH RATIONALE
  332. None.
  333. .SH "FUTURE DIRECTIONS"
  334. None.
  335. .SH "SEE ALSO"
  336. .IR "\fIfdopendir\fR\^(\|)",
  337. .IR "\fIfstatat\fR\^(\|)",
  338. .IR "\fIreaddir\fR\^(\|)"
  339. .P
  340. The Base Definitions volume of POSIX.1\(hy2017,
  341. .IR "\fB<ftw.h>\fP"
  342. .\"
  343. .SH COPYRIGHT
  344. Portions of this text are reprinted and reproduced in electronic form
  345. from IEEE Std 1003.1-2017, Standard for Information Technology
  346. -- Portable Operating System Interface (POSIX), The Open Group Base
  347. Specifications Issue 7, 2018 Edition,
  348. Copyright (C) 2018 by the Institute of
  349. Electrical and Electronics Engineers, Inc and The Open Group.
  350. In the event of any discrepancy between this version and the original IEEE and
  351. The Open Group Standard, the original IEEE and The Open Group Standard
  352. is the referee document. The original Standard can be obtained online at
  353. http://www.opengroup.org/unix/online.html .
  354. .PP
  355. Any typographical or formatting errors that appear
  356. in this page are most likely
  357. to have been introduced during the conversion of the source files to
  358. man page format. To report such errors, see
  359. https://www.kernel.org/doc/man-pages/reporting_bugs.html .