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

fdopendir.3p (8683B)


  1. '\" et
  2. .TH FDOPENDIR "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. fdopendir, opendir
  12. \(em open directory associated with file descriptor
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <dirent.h>
  17. .P
  18. DIR *fdopendir(int \fIfd\fP);
  19. DIR *opendir(const char *\fIdirname\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIfdopendir\fR()
  24. function shall be equivalent to the
  25. \fIopendir\fR()
  26. function except that the directory is specified by a file descriptor
  27. rather than by a name. The file offset associated with the file
  28. descriptor at the time of the call determines which entries are
  29. returned.
  30. .P
  31. Upon successful return from
  32. \fIfdopendir\fR(),
  33. the file descriptor is under the control of the system, and if any
  34. attempt is made to close the file descriptor, or to modify the state of
  35. the associated description, other than by means of
  36. \fIclosedir\fR(),
  37. \fIreaddir\fR(),
  38. \fIreaddir_r\fR(),
  39. \fIrewinddir\fR(),
  40. or
  41. \fIseekdir\fR(),
  42. the behavior is undefined. Upon calling
  43. \fIclosedir\fR()
  44. the file descriptor shall be closed.
  45. .P
  46. It is unspecified whether the FD_CLOEXEC flag will be set on the file
  47. descriptor by a successful call to
  48. \fIfdopendir\fR().
  49. .P
  50. The
  51. \fIopendir\fR()
  52. function shall open a directory stream corresponding to the directory
  53. named by the
  54. .IR dirname
  55. argument. The directory stream is positioned at the first entry. If
  56. the type
  57. .BR DIR
  58. is implemented using a file descriptor, applications shall only be
  59. able to open up to a total of
  60. {OPEN_MAX}
  61. files and directories.
  62. .P
  63. If the type
  64. .BR DIR
  65. is implemented using a file descriptor, the descriptor shall be
  66. obtained as if the O_DIRECTORY flag was passed to
  67. \fIopen\fR().
  68. .SH "RETURN VALUE"
  69. Upon successful completion, these functions shall return
  70. a pointer to an object of type
  71. .BR DIR .
  72. Otherwise, these functions shall return a null pointer and set
  73. .IR errno
  74. to indicate the error.
  75. .SH ERRORS
  76. The
  77. \fIfdopendir\fR()
  78. function shall fail if:
  79. .TP
  80. .BR EBADF
  81. The
  82. .IR fd
  83. argument is not a valid file descriptor open for reading.
  84. .TP
  85. .BR ENOTDIR
  86. The descriptor
  87. .IR fd
  88. is not associated with a directory.
  89. .P
  90. The
  91. \fIopendir\fR()
  92. function shall fail if:
  93. .TP
  94. .BR EACCES
  95. Search permission is denied for the component of the path prefix of
  96. .IR dirname
  97. or read permission is denied for
  98. .IR dirname .
  99. .TP
  100. .BR ELOOP
  101. A loop exists in symbolic links encountered during resolution of the
  102. .IR dirname
  103. argument.
  104. .TP
  105. .BR ENAMETOOLONG
  106. .br
  107. The length of a component of a pathname is longer than
  108. {NAME_MAX}.
  109. .TP
  110. .BR ENOENT
  111. A component of
  112. .IR dirname
  113. does not name an existing directory or
  114. .IR dirname
  115. is an empty string.
  116. .TP
  117. .BR ENOTDIR
  118. A component of
  119. .IR dirname
  120. names an existing file that is neither a directory nor a symbolic link
  121. to a directory.
  122. .br
  123. .P
  124. The
  125. \fIopendir\fR()
  126. function may fail if:
  127. .TP
  128. .BR ELOOP
  129. More than
  130. {SYMLOOP_MAX}
  131. symbolic links were encountered during resolution of the
  132. .IR dirname
  133. argument.
  134. .TP
  135. .BR EMFILE
  136. All file descriptors available to the process are currently open.
  137. .TP
  138. .BR ENAMETOOLONG
  139. .br
  140. The length of a pathname exceeds
  141. {PATH_MAX},
  142. or pathname resolution of a symbolic link produced an intermediate
  143. result with a length that exceeds
  144. {PATH_MAX}.
  145. .TP
  146. .BR ENFILE
  147. Too many files are currently open in the system.
  148. .LP
  149. .IR "The following sections are informative."
  150. .SH EXAMPLES
  151. .SS "Open a Directory Stream"
  152. .P
  153. The following program fragment demonstrates how the
  154. \fIopendir\fR()
  155. function is used.
  156. .sp
  157. .RS 4
  158. .nf
  159. #include <dirent.h>
  160. \&...
  161. DIR *dir;
  162. struct dirent *dp;
  163. \&...
  164. if ((dir = opendir (".")) == NULL) {
  165. perror ("Cannot open .");
  166. exit (1);
  167. }
  168. .P
  169. while ((dp = readdir (dir)) != NULL) {
  170. \&...
  171. .fi
  172. .P
  173. .RE
  174. .SS "Find And Open a File"
  175. .P
  176. The following program searches through a given directory looking
  177. for files whose name does not begin with a dot and whose size is
  178. larger than 1 MiB.
  179. .sp
  180. .RS 4
  181. .nf
  182. #include <stdio.h>
  183. #include <dirent.h>
  184. #include <fcntl.h>
  185. #include <sys/stat.h>
  186. #include <stdint.h>
  187. #include <stdlib.h>
  188. #include <unistd.h>
  189. .P
  190. int
  191. main(int argc, char *argv[])
  192. {
  193. struct stat statbuf;
  194. DIR *d;
  195. struct dirent *dp;
  196. int dfd, ffd;
  197. .P
  198. if ((d = fdopendir((dfd = open("./tmp", O_RDONLY)))) == NULL) {
  199. fprintf(stderr, "Cannot open ./tmp directory\en");
  200. exit(1);
  201. }
  202. while ((dp = readdir(d)) != NULL) {
  203. if (dp->d_name[0] == \(aq.\(aq)
  204. continue;
  205. /* there is a possible race condition here as the file
  206. * could be renamed between the readdir and the open */
  207. if ((ffd = openat(dfd, dp->d_name, O_RDONLY)) == -1) {
  208. perror(dp->d_name);
  209. continue;
  210. }
  211. if (fstat(ffd, &statbuf) == 0 && statbuf.st_size > (1024*1024)) {
  212. /* found it ... */
  213. printf("%s: %jdK\en", dp->d_name,
  214. (intmax_t)(statbuf.st_size / 1024));
  215. }
  216. close(ffd);
  217. }
  218. closedir(d); // note this implicitly closes dfd
  219. return 0;
  220. }
  221. .fi
  222. .P
  223. .RE
  224. .SH "APPLICATION USAGE"
  225. The
  226. \fIopendir\fR()
  227. function should be used in conjunction with
  228. \fIreaddir\fR(),
  229. \fIclosedir\fR(),
  230. and
  231. \fIrewinddir\fR()
  232. to examine the contents of the directory (see the EXAMPLES section in
  233. .IR "\fIreaddir\fR\^(\|)").
  234. This method is recommended for portability.
  235. .SH RATIONALE
  236. The purpose of the
  237. \fIfdopendir\fR()
  238. function is to enable opening files in directories other than the
  239. current working directory without exposure to race conditions. Any part
  240. of the path of a file could be changed in parallel to a call to
  241. \fIopendir\fR(),
  242. resulting in unspecified behavior.
  243. .P
  244. Based on historical implementations, the rules about file descriptors
  245. apply to directory streams as well. However, this volume of POSIX.1\(hy2017 does not
  246. mandate that the directory stream be implemented using file
  247. descriptors. The description of
  248. \fIclosedir\fR()
  249. clarifies that if a file descriptor is used for the directory stream,
  250. it is mandatory that
  251. \fIclosedir\fR()
  252. deallocate the file descriptor. When a file descriptor is used to
  253. implement the directory stream, it behaves as if the FD_CLOEXEC
  254. had been set for the file descriptor.
  255. .P
  256. The directory entries for dot
  257. and dot-dot
  258. are optional. This volume of POSIX.1\(hy2017 does not provide a way to test
  259. .IR "a priori"
  260. for their existence because an application that is portable must be
  261. written to look for (and usually ignore) those entries. Writing code
  262. that presumes that they are the first two entries does not always work,
  263. as many implementations permit them to be other than the first two
  264. entries, with a ``normal'' entry preceding them. There is negligible
  265. value in providing a way to determine what the implementation does
  266. because the code to deal with dot and dot-dot must be written in any
  267. case and because such a flag would add to the list of those flags
  268. (which has proven in itself to be objectionable) and might be abused.
  269. .P
  270. Since the structure and buffer allocation, if any, for directory
  271. operations are defined by the implementation, this volume of POSIX.1\(hy2017 imposes no
  272. portability requirements for erroneous program constructs, erroneous
  273. data, or the use of unspecified values such as the use or referencing
  274. of a
  275. .IR dirp
  276. value or a
  277. .BR dirent
  278. structure value after a directory stream has been closed or after a
  279. \fIfork\fR()
  280. or one of the
  281. .IR exec
  282. function calls.
  283. .SH "FUTURE DIRECTIONS"
  284. None.
  285. .SH "SEE ALSO"
  286. .IR "\fIclosedir\fR\^(\|)",
  287. .IR "\fIdirfd\fR\^(\|)",
  288. .IR "\fIfstatat\fR\^(\|)",
  289. .IR "\fIopen\fR\^(\|)",
  290. .IR "\fIreaddir\fR\^(\|)",
  291. .IR "\fIrewinddir\fR\^(\|)",
  292. .IR "\fIsymlink\fR\^(\|)"
  293. .P
  294. The Base Definitions volume of POSIX.1\(hy2017,
  295. .IR "\fB<dirent.h>\fP",
  296. .IR "\fB<sys_types.h>\fP"
  297. .\"
  298. .SH COPYRIGHT
  299. Portions of this text are reprinted and reproduced in electronic form
  300. from IEEE Std 1003.1-2017, Standard for Information Technology
  301. -- Portable Operating System Interface (POSIX), The Open Group Base
  302. Specifications Issue 7, 2018 Edition,
  303. Copyright (C) 2018 by the Institute of
  304. Electrical and Electronics Engineers, Inc and The Open Group.
  305. In the event of any discrepancy between this version and the original IEEE and
  306. The Open Group Standard, the original IEEE and The Open Group Standard
  307. is the referee document. The original Standard can be obtained online at
  308. http://www.opengroup.org/unix/online.html .
  309. .PP
  310. Any typographical or formatting errors that appear
  311. in this page are most likely
  312. to have been introduced during the conversion of the source files to
  313. man page format. To report such errors, see
  314. https://www.kernel.org/doc/man-pages/reporting_bugs.html .