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

fopen.3p (9717B)


  1. '\" et
  2. .TH FOPEN "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. fopen
  12. \(em open a stream
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. FILE *fopen(const char *restrict \fIpathname\fP, const char *restrict \fImode\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The functionality described on this reference page is aligned with the
  22. ISO\ C standard. Any conflict between the requirements described here and the
  23. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  24. .P
  25. The
  26. \fIfopen\fR()
  27. function shall open the file whose pathname is the string pointed to by
  28. .IR pathname ,
  29. and associates a stream with it.
  30. .P
  31. The
  32. .IR mode
  33. argument points to a string. If the string is one of the following, the
  34. file shall be opened in the indicated mode. Otherwise, the behavior is
  35. undefined.
  36. .IP "\fIr\fP\ or\ \fIrb\fP" 14
  37. Open file for reading.
  38. .IP "\fIw\fP\ or\ \fIwb\fP" 14
  39. Truncate to zero length or create file for writing.
  40. .IP "\fIa\fP\ or\ \fIab\fP" 14
  41. Append; open or create file for writing at end-of-file.
  42. .IP "\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP" 14
  43. Open file for update (reading and writing).
  44. .IP "\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP" 14
  45. Truncate to zero length or create file for update.
  46. .IP "\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP" 14
  47. Append; open or create file for update, writing at end-of-file.
  48. .P
  49. The character
  50. .BR 'b'
  51. shall have no effect, but is allowed for ISO\ C standard conformance.
  52. Opening a file with read mode (\fIr\fP as the first character in the
  53. .IR mode
  54. argument) shall fail if the file does not exist or cannot be read.
  55. .P
  56. Opening a file with append mode (\fIa\fP as the first character in the
  57. .IR mode
  58. argument) shall cause all subsequent writes to the file to be forced to
  59. the then current end-of-file, regardless of intervening calls to
  60. \fIfseek\fR().
  61. .P
  62. When a file is opened with update mode (\c
  63. .BR '+'
  64. as the second or third character in the
  65. .IR mode
  66. argument), both input and output may be performed on the associated
  67. stream. However, the application shall ensure that output is not
  68. directly followed by input without an intervening call to
  69. \fIfflush\fR()
  70. or to a file positioning function (\c
  71. \fIfseek\fR(),
  72. \fIfsetpos\fR(),
  73. or
  74. \fIrewind\fR()),
  75. and input is not directly followed by output without an intervening
  76. call to a file positioning function, unless the input operation
  77. encounters end-of-file.
  78. .P
  79. When opened, a stream is fully buffered if and only if it can be
  80. determined not to refer to an interactive device. The error and
  81. end-of-file indicators for the stream shall be cleared.
  82. .P
  83. If
  84. .IR mode
  85. is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+,
  86. \fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file
  87. did not previously exist, upon successful completion,
  88. \fIfopen\fR()
  89. shall mark for update the last data access, last data modification, and
  90. last file status change timestamps of the file and the last file status
  91. change and last data modification timestamps of the parent directory.
  92. .P
  93. If
  94. .IR mode
  95. is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+,
  96. \fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file
  97. did not previously exist, the
  98. \fIfopen\fR()
  99. function shall create a file as if it called the
  100. \fIcreat\fR()
  101. function with a value appropriate for the
  102. .IR path
  103. argument interpreted from
  104. .IR pathname
  105. and a value of S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH |
  106. S_IWOTH for the
  107. .IR mode
  108. argument.
  109. .P
  110. If
  111. .IR mode
  112. is \fIw\fR, \fIwb\fR, \fIw\fR+, \fIwb\fR+, or \fIw\fR+\fIb\fR, and the
  113. file did previously exist, upon successful completion,
  114. \fIfopen\fR()
  115. shall mark for update the last data modification and last file
  116. status change timestamps of the file.
  117. .P
  118. After a successful call to the
  119. \fIfopen\fR()
  120. function, the orientation of the stream shall be cleared,
  121. the encoding rule shall be cleared,
  122. and the associated
  123. .BR mbstate_t
  124. object shall be set to describe an initial conversion state.
  125. .P
  126. The file descriptor associated with the opened stream shall be allocated
  127. and opened as if by a call to
  128. \fIopen\fR()
  129. with the following flags:
  130. .TS
  131. center box tab(!);
  132. cB | cB
  133. l | l.
  134. \fIfopen\fP(\^) Mode!\fIopen\fP(\^) Flags
  135. _
  136. \fIr\fR or \fIrb\fR!O_RDONLY
  137. \fIw\fR or \fIwb\fR!O_WRONLY|O_CREAT|O_TRUNC
  138. \fIa\fR or \fIab\fR!O_WRONLY|O_CREAT|O_APPEND
  139. \fIr+\fR or \fIrb+\fR or \fIr+b\fR!O_RDWR
  140. \fIw+\fR or \fIwb+\fR or \fIw+b\fR!O_RDWR|O_CREAT|O_TRUNC
  141. \fIa+\fR or \fIab+\fR or \fIa+b\fR!O_RDWR|O_CREAT|O_APPEND
  142. .TE
  143. .SH "RETURN VALUE"
  144. Upon successful completion,
  145. \fIfopen\fR()
  146. shall return a pointer to the object controlling the stream. Otherwise,
  147. a null pointer shall be returned,
  148. and
  149. .IR errno
  150. shall be set to indicate the error.
  151. .SH ERRORS
  152. The
  153. \fIfopen\fR()
  154. function shall fail if:
  155. .TP
  156. .BR EACCES
  157. Search permission is denied on a component of the path prefix, or the
  158. file exists and the permissions specified by
  159. .IR mode
  160. are denied, or the file does not exist and write permission is denied
  161. for the parent directory of the file to be created.
  162. .TP
  163. .BR EINTR
  164. A signal was caught during
  165. \fIfopen\fR().
  166. .TP
  167. .BR EISDIR
  168. The named file is a directory and
  169. .IR mode
  170. requires write access.
  171. .TP
  172. .BR ELOOP
  173. A loop exists in symbolic links encountered during resolution of the
  174. .IR path
  175. argument.
  176. .TP
  177. .BR EMFILE
  178. All file descriptors available to the process are currently open.
  179. .TP
  180. .BR EMFILE
  181. {STREAM_MAX}
  182. streams are currently open in the calling process.
  183. .TP
  184. .BR ENAMETOOLONG
  185. .br
  186. The length of a pathname exceeds
  187. {PATH_MAX},
  188. or pathname resolution of a symbolic link produced an intermediate
  189. result with a length that exceeds
  190. {PATH_MAX}.
  191. .TP
  192. .BR ENFILE
  193. The maximum allowable number of files is currently open in the system.
  194. .TP
  195. .BR ENOENT
  196. The
  197. .IR mode
  198. string begins with
  199. .BR 'r'
  200. and a component of
  201. .IR pathname
  202. does not name an existing file, or
  203. .IR mode
  204. begins with
  205. .BR 'w'
  206. or
  207. .BR 'a'
  208. and a component of the path prefix of
  209. .IR pathname
  210. does not name an existing file, or
  211. .IR pathname
  212. is an empty string.
  213. .TP
  214. .BR ENOENT " or " ENOTDIR
  215. .br
  216. The
  217. .IR pathname
  218. argument contains at least one non-\c
  219. <slash>
  220. character and ends with one or more trailing
  221. <slash>
  222. characters. If
  223. .IR pathname
  224. without the trailing
  225. <slash>
  226. characters would name an existing file, an
  227. .BR [ENOENT]
  228. error shall not occur.
  229. .TP
  230. .BR ENOSPC
  231. The directory or file system that would contain the new file cannot be
  232. expanded, the file does not exist, and the file was to be created.
  233. .TP
  234. .BR ENOTDIR
  235. A component of the path prefix names an existing file that is neither
  236. a directory nor a symbolic link to a directory, or the
  237. .IR pathname
  238. argument contains at least one non-\c
  239. <slash>
  240. character and ends with one or more trailing
  241. <slash>
  242. characters and the last pathname component names an existing file that
  243. is neither a directory nor a symbolic link to a directory.
  244. .TP
  245. .BR ENXIO
  246. The named file is a character special or block special file,
  247. and the device associated with this special file does not exist.
  248. .TP
  249. .BR EOVERFLOW
  250. The named file is a regular file and the size of the file cannot be
  251. represented correctly in an object of type
  252. .BR off_t .
  253. .TP
  254. .BR EROFS
  255. The named file resides on a read-only file system and
  256. .IR mode
  257. requires write access.
  258. .P
  259. The
  260. \fIfopen\fR()
  261. function may fail if:
  262. .TP
  263. .BR EINVAL
  264. The value of the
  265. .IR mode
  266. argument is not valid.
  267. .TP
  268. .BR ELOOP
  269. More than
  270. {SYMLOOP_MAX}
  271. symbolic links were encountered during resolution of the
  272. .IR path
  273. argument.
  274. .TP
  275. .BR EMFILE
  276. {FOPEN_MAX}
  277. streams are currently open in the calling process.
  278. .TP
  279. .BR ENAMETOOLONG
  280. .br
  281. The length of a component of a pathname is longer than
  282. {NAME_MAX}.
  283. .TP
  284. .BR ENOMEM
  285. Insufficient storage space is available.
  286. .TP
  287. .BR ETXTBSY
  288. The file is a pure procedure (shared text) file that is being executed
  289. and
  290. .IR mode
  291. requires write access.
  292. .LP
  293. .IR "The following sections are informative."
  294. .SH EXAMPLES
  295. .SS "Opening a File"
  296. .P
  297. The following example tries to open the file named
  298. .BR file
  299. for reading. The
  300. \fIfopen\fR()
  301. function returns a file pointer that is used in subsequent
  302. \fIfgets\fR()
  303. and
  304. \fIfclose\fR()
  305. calls. If the program cannot open the file, it just ignores it.
  306. .sp
  307. .RS 4
  308. .nf
  309. #include <stdio.h>
  310. \&...
  311. FILE *fp;
  312. \&...
  313. void rgrep(const char *file)
  314. {
  315. \&...
  316. if ((fp = fopen(file, "r")) == NULL)
  317. return;
  318. \&...
  319. }
  320. .fi
  321. .P
  322. .RE
  323. .SH "APPLICATION USAGE"
  324. None.
  325. .SH RATIONALE
  326. None.
  327. .SH "FUTURE DIRECTIONS"
  328. None.
  329. .SH "SEE ALSO"
  330. .IR "Section 2.5" ", " "Standard I/O Streams",
  331. .IR "\fIcreat\fR\^(\|)",
  332. .IR "\fIfclose\fR\^(\|)",
  333. .IR "\fIfdopen\fR\^(\|)",
  334. .IR "\fIfmemopen\fR\^(\|)",
  335. .IR "\fIfreopen\fR\^(\|)",
  336. .IR "\fIopen_memstream\fR\^(\|)"
  337. .P
  338. The Base Definitions volume of POSIX.1\(hy2017,
  339. .IR "\fB<stdio.h>\fP"
  340. .\"
  341. .SH COPYRIGHT
  342. Portions of this text are reprinted and reproduced in electronic form
  343. from IEEE Std 1003.1-2017, Standard for Information Technology
  344. -- Portable Operating System Interface (POSIX), The Open Group Base
  345. Specifications Issue 7, 2018 Edition,
  346. Copyright (C) 2018 by the Institute of
  347. Electrical and Electronics Engineers, Inc and The Open Group.
  348. In the event of any discrepancy between this version and the original IEEE and
  349. The Open Group Standard, the original IEEE and The Open Group Standard
  350. is the referee document. The original Standard can be obtained online at
  351. http://www.opengroup.org/unix/online.html .
  352. .PP
  353. Any typographical or formatting errors that appear
  354. in this page are most likely
  355. to have been introduced during the conversion of the source files to
  356. man page format. To report such errors, see
  357. https://www.kernel.org/doc/man-pages/reporting_bugs.html .