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

freopen.3p (9514B)


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