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

readdir.3p (10344B)


  1. '\" et
  2. .TH READDIR "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. readdir,
  12. readdir_r
  13. \(em read a directory
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <dirent.h>
  18. .P
  19. struct dirent *readdir(DIR *\fIdirp\fP);
  20. int readdir_r(DIR *restrict \fIdirp\fP, struct dirent *restrict \fIentry\fP,
  21. struct dirent **restrict \fIresult\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The type
  25. .BR DIR ,
  26. which is defined in the
  27. .IR <dirent.h>
  28. header, represents a
  29. .IR "directory stream" ,
  30. which is an ordered sequence of all the directory entries in a
  31. particular directory. Directory entries represent files; files may be
  32. removed from a directory or added to a directory asynchronously to the
  33. operation of
  34. \fIreaddir\fR().
  35. .P
  36. The
  37. \fIreaddir\fR()
  38. function shall return a pointer to a structure representing the
  39. directory entry at the current position in the directory stream
  40. specified by the argument
  41. .IR dirp ,
  42. and position the directory stream at the next entry. It shall return a
  43. null pointer upon reaching the end of the directory stream. The
  44. structure
  45. .BR dirent
  46. defined in the
  47. .IR <dirent.h>
  48. header describes a directory entry. The value of the structure's
  49. .IR d_ino
  50. member shall be set to the file serial number of the file named by the
  51. .IR d_name
  52. member. If the
  53. .IR d_name
  54. member names a symbolic link, the value of the
  55. .IR d_ino
  56. member shall be set to the file serial number of the symbolic link itself.
  57. .P
  58. The
  59. \fIreaddir\fR()
  60. function shall not return directory entries containing empty names. If
  61. entries for dot or dot-dot exist, one entry shall be returned for dot
  62. and one entry shall be returned for dot-dot; otherwise, they shall not
  63. be returned.
  64. .P
  65. The application shall not modify the structure to which the return
  66. value of
  67. \fIreaddir\fR()
  68. points, nor any storage areas pointed to by pointers within the
  69. structure. The returned pointer, and pointers within the structure,
  70. might be invalidated or the structure or the storage areas might be
  71. overwritten by a subsequent call to
  72. \fIreaddir\fR()
  73. on the same directory stream. They shall not be affected by a call to
  74. \fIreaddir\fR()
  75. on a different directory stream. The returned pointer, and pointers
  76. within the structure, might also be invalidated if the calling thread
  77. is terminated.
  78. .P
  79. If a file is removed from or added to the directory after the most
  80. recent call to
  81. \fIopendir\fR()
  82. or
  83. \fIrewinddir\fR(),
  84. whether a subsequent call to
  85. \fIreaddir\fR()
  86. returns an entry for that file is unspecified.
  87. .P
  88. The
  89. \fIreaddir\fR()
  90. function may buffer several directory entries per actual read
  91. operation;
  92. \fIreaddir\fR()
  93. shall mark for update the last data access timestamp
  94. of the directory each time the directory is actually read.
  95. .P
  96. After a call to
  97. \fIfork\fR(),
  98. either the parent or child (but not both) may continue processing the
  99. directory stream using
  100. \fIreaddir\fR(),
  101. \fIrewinddir\fR(),
  102. or
  103. \fIseekdir\fR().
  104. If both the parent and child processes use these functions, the result
  105. is undefined.
  106. .P
  107. The
  108. \fIreaddir\fR()
  109. function need not be thread-safe.
  110. .P
  111. Applications wishing to check for error situations should set
  112. .IR errno
  113. to 0 before calling
  114. \fIreaddir\fR().
  115. If
  116. .IR errno
  117. is set to non-zero on return, an error occurred.
  118. .P
  119. The
  120. \fIreaddir_r\fR()
  121. function shall initialize the
  122. .BR dirent
  123. structure referenced by
  124. .IR entry
  125. to represent the directory entry at the current position in the
  126. directory stream referred to by
  127. .IR dirp ,
  128. store a pointer to this structure at the location referenced by
  129. .IR result ,
  130. and position the directory stream at the next entry.
  131. .P
  132. The storage pointed to by
  133. .IR entry
  134. shall be large enough for a
  135. .BR dirent
  136. with an array of
  137. .BR char
  138. .IR d_name
  139. members containing at least
  140. {NAME_MAX}+1
  141. elements.
  142. .P
  143. Upon successful return, the pointer returned at *\fIresult\fP shall have
  144. the same value as the argument
  145. .IR entry .
  146. Upon reaching the end of the directory stream, this pointer shall
  147. have the value NULL.
  148. .P
  149. The
  150. \fIreaddir_r\fR()
  151. function shall not return directory entries containing empty names.
  152. .P
  153. If a file is removed from or added to the directory after the most
  154. recent call to
  155. \fIopendir\fR()
  156. or
  157. \fIrewinddir\fR(),
  158. whether a subsequent call to
  159. \fIreaddir_r\fR()
  160. returns an entry for that file is unspecified.
  161. .P
  162. The
  163. \fIreaddir_r\fR()
  164. function may buffer several directory entries per actual read
  165. operation;
  166. \fIreaddir_r\fR()
  167. shall mark for update the last data access timestamp of the directory
  168. each time the directory is actually read.
  169. .SH "RETURN VALUE"
  170. Upon successful completion,
  171. \fIreaddir\fR()
  172. shall return a pointer to an object of type
  173. .BR "struct dirent" .
  174. When an error is encountered, a null pointer shall be returned and
  175. .IR errno
  176. shall be set to indicate the error. When the end of the directory is
  177. encountered, a null pointer shall be returned and
  178. .IR errno
  179. is not changed.
  180. .P
  181. If successful, the
  182. \fIreaddir_r\fR()
  183. function shall return zero; otherwise, an error number shall be
  184. returned to indicate the error.
  185. .SH ERRORS
  186. These functions shall fail if:
  187. .TP
  188. .BR EOVERFLOW
  189. One of the values in the structure to be returned cannot be represented
  190. correctly.
  191. .P
  192. These functions may fail if:
  193. .TP
  194. .BR EBADF
  195. The
  196. .IR dirp
  197. argument does not refer to an open directory stream.
  198. .TP
  199. .BR ENOENT
  200. The current position of the directory stream is invalid.
  201. .LP
  202. .IR "The following sections are informative."
  203. .SH "EXAMPLES"
  204. The following sample program searches the current directory for
  205. each of the arguments supplied on the command line.
  206. .sp
  207. .RS 4
  208. .nf
  209. #include <dirent.h>
  210. #include <errno.h>
  211. #include <stdio.h>
  212. #include <string.h>
  213. .P
  214. static void lookup(const char *arg)
  215. {
  216. DIR *dirp;
  217. struct dirent *dp;
  218. .P
  219. if ((dirp = opendir(".")) == NULL) {
  220. perror("couldn\(aqt open \(aq.\(aq");
  221. return;
  222. }
  223. .P
  224. do {
  225. errno = 0;
  226. if ((dp = readdir(dirp)) != NULL) {
  227. if (strcmp(dp->d_name, arg) != 0)
  228. continue;
  229. .P
  230. (void) printf("found %s\en", arg);
  231. (void) closedir(dirp);
  232. return;
  233. .P
  234. }
  235. } while (dp != NULL);
  236. .P
  237. if (errno != 0)
  238. perror("error reading directory");
  239. else
  240. (void) printf("failed to find %s\en", arg);
  241. (void) closedir(dirp);
  242. return;
  243. }
  244. .P
  245. int main(int argc, char *argv[])
  246. {
  247. int i;
  248. for (i = 1; i < argc; i++)
  249. lookup(argv[i]);
  250. return (0);
  251. }
  252. .fi
  253. .P
  254. .RE
  255. .SH "APPLICATION USAGE"
  256. The
  257. \fIreaddir\fR()
  258. function should be used in conjunction with
  259. \fIopendir\fR(),
  260. \fIclosedir\fR(),
  261. and
  262. \fIrewinddir\fR()
  263. to examine the contents of the directory.
  264. .P
  265. The
  266. \fIreaddir_r\fR()
  267. function is thread-safe and shall return values in a user-supplied
  268. buffer instead of possibly using a static data area that may be
  269. overwritten by each call.
  270. .SH RATIONALE
  271. The returned value of
  272. \fIreaddir\fR()
  273. merely \fIrepresents\fP a directory entry. No equivalence should be
  274. inferred.
  275. .P
  276. Historical implementations of
  277. \fIreaddir\fR()
  278. obtain multiple directory entries on a single read operation, which
  279. permits subsequent
  280. \fIreaddir\fR()
  281. operations to operate from the buffered information. Any wording that
  282. required each successful
  283. \fIreaddir\fR()
  284. operation to mark the directory last data access timestamp
  285. for update would disallow such historical performance-oriented
  286. implementations.
  287. .P
  288. When returning a directory entry for the root of a mounted file system,
  289. some historical implementations of
  290. \fIreaddir\fR()
  291. returned the file serial number of the underlying mount point, rather
  292. than of the root of the mounted file system. This behavior is considered
  293. to be a bug, since the underlying file serial number has no significance
  294. to applications.
  295. .P
  296. Since
  297. \fIreaddir\fR()
  298. returns NULL
  299. when it detects an error and when the end of the directory is
  300. encountered, an application that needs to tell the difference must set
  301. .IR errno
  302. to zero before the call and check it if NULL is returned.
  303. Since the function must not change
  304. .IR errno
  305. in the second case and must set it to a non-zero value in the first
  306. case, a zero
  307. .IR errno
  308. after a call returning NULL indicates end-of-directory; otherwise, an
  309. error.
  310. .P
  311. Routines to deal with this problem more directly were proposed:
  312. .sp
  313. .RS 4
  314. .nf
  315. int derror (\fIdirp\fP)
  316. DIR *\fIdirp\fP;
  317. .P
  318. void clearderr (\fIdirp\fP)
  319. DIR *\fIdirp\fP;
  320. .fi
  321. .P
  322. .RE
  323. .P
  324. The first would indicate whether an error had occurred, and the second
  325. would clear the error indication. The simpler method involving
  326. .IR errno
  327. was adopted instead by requiring that
  328. \fIreaddir\fR()
  329. not change
  330. .IR errno
  331. when end-of-directory is encountered.
  332. .P
  333. An error or signal indicating that a directory has changed while open
  334. was considered but rejected.
  335. .P
  336. The thread-safe version of the directory reading function returns
  337. values in a user-supplied buffer instead of possibly using a static
  338. data area that may be overwritten by each call. Either the
  339. {NAME_MAX}
  340. compile-time constant or the corresponding
  341. \fIpathconf\fR()
  342. option can be used to determine the maximum sizes of returned
  343. pathnames.
  344. .SH "FUTURE DIRECTIONS"
  345. None.
  346. .SH "SEE ALSO"
  347. .IR "\fIclosedir\fR\^(\|)",
  348. .IR "\fIdirfd\fR\^(\|)",
  349. .IR "\fIexec\fR\^",
  350. .IR "\fIfdopendir\fR\^(\|)",
  351. .IR "\fIfstatat\fR\^(\|)",
  352. .IR "\fIrewinddir\fR\^(\|)",
  353. .IR "\fIsymlink\fR\^(\|)"
  354. .P
  355. The Base Definitions volume of POSIX.1\(hy2017,
  356. .IR "\fB<dirent.h>\fP",
  357. .IR "\fB<sys_types.h>\fP"
  358. .\"
  359. .SH COPYRIGHT
  360. Portions of this text are reprinted and reproduced in electronic form
  361. from IEEE Std 1003.1-2017, Standard for Information Technology
  362. -- Portable Operating System Interface (POSIX), The Open Group Base
  363. Specifications Issue 7, 2018 Edition,
  364. Copyright (C) 2018 by the Institute of
  365. Electrical and Electronics Engineers, Inc and The Open Group.
  366. In the event of any discrepancy between this version and the original IEEE and
  367. The Open Group Standard, the original IEEE and The Open Group Standard
  368. is the referee document. The original Standard can be obtained online at
  369. http://www.opengroup.org/unix/online.html .
  370. .PP
  371. Any typographical or formatting errors that appear
  372. in this page are most likely
  373. to have been introduced during the conversion of the source files to
  374. man page format. To report such errors, see
  375. https://www.kernel.org/doc/man-pages/reporting_bugs.html .