| .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" This code is derived from software contributed to Berkeley by |
| .\" Chris Torek and the American National Standards Committee X3, |
| .\" on Information Processing Systems. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 |
| .\" |
| .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu |
| .\" Modified, aeb, 960421, 970806 |
| .\" Modified, joey, aeb, 2002-01-03 |
| .\" |
| .TH FOPEN 3 2019-05-09 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| fopen, fdopen, freopen \- stream open functions |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdio.h> |
| .PP |
| .BI "FILE *fopen(const char *" pathname ", const char *" mode ); |
| .PP |
| .BI "FILE *fdopen(int " fd ", const char *" mode ); |
| .PP |
| .BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR fdopen (): |
| _POSIX_C_SOURCE |
| .SH DESCRIPTION |
| The |
| .BR fopen () |
| function opens the file whose name is the string pointed to by |
| .I pathname |
| and associates a stream with it. |
| .PP |
| The argument |
| .I mode |
| points to a string beginning with one of the following sequences |
| (possibly followed by additional characters, as described below): |
| .TP |
| .B r |
| Open text file for reading. |
| The stream is positioned at the beginning of the file. |
| .TP |
| .B r+ |
| Open for reading and writing. |
| The stream is positioned at the beginning of the file. |
| .TP |
| .B w |
| Truncate file to zero length or create text file for writing. |
| The stream is positioned at the beginning of the file. |
| .TP |
| .B w+ |
| Open for reading and writing. |
| The file is created if it does not exist, otherwise it is truncated. |
| The stream is positioned at the beginning of |
| the file. |
| .TP |
| .B a |
| Open for appending (writing at end of file). |
| The file is created if it does not exist. |
| The stream is positioned at the end of the file. |
| .TP |
| .B a+ |
| Open for reading and appending (writing at end of file). |
| The file is created if it does not exist. |
| Output is always appended to the end of the file. |
| POSIX is silent on what the initial read position is when using this mode. |
| For glibc, the initial file position for reading is at |
| the beginning of the file, but for Android/BSD/MacOS, the |
| initial file position for reading is at the end of the file. |
| .PP |
| The |
| .I mode |
| string can also include the letter \(aqb\(aq either as a last character or as |
| a character between the characters in any of the two-character strings |
| described above. |
| This is strictly for compatibility with C89 |
| and has no effect; the \(aqb\(aq is ignored on all POSIX |
| conforming systems, including Linux. |
| (Other systems may treat text files and binary files differently, |
| and adding the \(aqb\(aq may be a good idea if you do I/O to a binary |
| file and expect that your program may be ported to non-UNIX |
| environments.) |
| .PP |
| See NOTES below for details of glibc extensions for |
| .IR mode . |
| .PP |
| Any created file will have the mode |
| .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH |
| (0666), as modified by the process's umask value (see |
| .BR umask (2)). |
| .PP |
| Reads and writes may be intermixed on read/write streams in any order. |
| Note that ANSI C requires that a file positioning function intervene |
| between output and input, unless an input operation encounters end-of-file. |
| (If this condition is not met, then a read is allowed to return the |
| result of writes other than the most recent.) |
| Therefore it is good practice (and indeed sometimes necessary |
| under Linux) to put an |
| .BR fseek (3) |
| or |
| .BR fgetpos (3) |
| operation between write and read operations on such a stream. |
| This operation may be an apparent no-op |
| (as in \fIfseek(..., 0L, SEEK_CUR)\fP |
| called for its synchronizing side effect). |
| .PP |
| Opening a file in append mode (\fBa\fP as the first character of |
| .IR mode ) |
| causes all subsequent write operations to this stream to occur |
| at end-of-file, as if preceded the call: |
| .PP |
| .in +4n |
| .EX |
| fseek(stream, 0, SEEK_END); |
| .EE |
| .in |
| .PP |
| The file descriptor associated with the stream is opened as if by a call to |
| .BR open (2) |
| with the following flags: |
| .RS |
| .TS |
| allbox; |
| lb lb |
| c l. |
| fopen() mode open() flags |
| \fIr\fP O_RDONLY |
| \fIw\fP O_WRONLY | O_CREAT | O_TRUNC |
| \fIa\fP O_WRONLY | O_CREAT | O_APPEND |
| \fIr+\fP O_RDWR |
| \fIw+\fP O_RDWR | O_CREAT | O_TRUNC |
| \fIa+\fP O_RDWR | O_CREAT | O_APPEND |
| .TE |
| .RE |
| .\" |
| .SS fdopen() |
| The |
| .BR fdopen () |
| function associates a stream with the existing file descriptor, |
| .IR fd . |
| The |
| .I mode |
| of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") |
| must be compatible with the mode of the file descriptor. |
| The file position indicator of the new stream is set to that |
| belonging to |
| .IR fd , |
| and the error and end-of-file indicators are cleared. |
| Modes "w" or "w+" do not cause truncation of the file. |
| The file descriptor is not dup'ed, and will be closed when |
| the stream created by |
| .BR fdopen () |
| is closed. |
| The result of applying |
| .BR fdopen () |
| to a shared memory object is undefined. |
| .\" |
| .SS freopen() |
| The |
| .BR freopen () |
| function opens the file whose name is the string pointed to by |
| .I pathname |
| and associates the stream pointed to by |
| .I stream |
| with it. |
| The original stream (if it exists) is closed. |
| The |
| .I mode |
| argument is used just as in the |
| .BR fopen () |
| function. |
| .PP |
| If the |
| .I pathname |
| argument is a null pointer, |
| .BR freopen () |
| changes the mode of the stream to that specified in |
| .IR mode ; |
| that is, |
| .BR freopen () |
| reopens the pathname that is associated with the stream. |
| The specification for this behavior was added in the C99 standard, which says: |
| .PP |
| .RS |
| In this case, |
| the file descriptor associated with the stream need not be closed |
| if the call to |
| .BR freopen () |
| succeeds. |
| It is implementation-defined which changes of mode are permitted (if any), |
| and under what circumstances. |
| .RE |
| .PP |
| The primary use of the |
| .BR freopen () |
| function is to change the file associated with a standard text stream |
| .RI ( stderr ", " stdin ", or " stdout ). |
| .SH RETURN VALUE |
| Upon successful completion |
| .BR fopen (), |
| .BR fdopen () |
| and |
| .BR freopen () |
| return a |
| .I FILE |
| pointer. |
| Otherwise, NULL is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EINVAL |
| The |
| .I mode |
| provided to |
| .BR fopen (), |
| .BR fdopen (), |
| or |
| .BR freopen () |
| was invalid. |
| .PP |
| The |
| .BR fopen (), |
| .BR fdopen () |
| and |
| .BR freopen () |
| functions may also fail and set |
| .I errno |
| for any of the errors specified for the routine |
| .BR malloc (3). |
| .PP |
| The |
| .BR fopen () |
| function may also fail and set |
| .I errno |
| for any of the errors specified for the routine |
| .BR open (2). |
| .PP |
| The |
| .BR fdopen () |
| function may also fail and set |
| .I errno |
| for any of the errors specified for the routine |
| .BR fcntl (2). |
| .PP |
| The |
| .BR freopen () |
| function may also fail and set |
| .I errno |
| for any of the errors specified for the routines |
| .BR open (2), |
| .BR fclose (3), |
| and |
| .BR fflush (3). |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw28 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR fopen (), |
| .BR fdopen (), |
| .BR freopen () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| .BR fopen (), |
| .BR freopen (): |
| POSIX.1-2001, POSIX.1-2008, C89, C99. |
| .PP |
| .BR fdopen (): |
| POSIX.1-2001, POSIX.1-2008. |
| .SH NOTES |
| .SS Glibc notes |
| The GNU C library allows the following extensions for the string specified in |
| .IR mode : |
| .TP |
| .BR c " (since glibc 2.3.3)" |
| Do not make the open operation, |
| or subsequent read and write operations, |
| thread cancellation points. |
| This flag is ignored for |
| .BR fdopen (). |
| .TP |
| .BR e " (since glibc 2.7)" |
| Open the file with the |
| .B O_CLOEXEC |
| flag. |
| See |
| .BR open (2) |
| for more information. |
| This flag is ignored for |
| .BR fdopen (). |
| .TP |
| .BR m " (since glibc 2.3)" |
| Attempt to access the file using |
| .BR mmap (2), |
| rather than I/O system calls |
| .RB ( read (2), |
| .BR write (2)). |
| Currently, |
| .\" As at glibc 2.4: |
| use of |
| .BR mmap (2) |
| is attempted only for a file opened for reading. |
| .TP |
| .B x |
| .\" Since glibc 2.0? |
| .\" FIXME . C11 specifies this flag |
| Open the file exclusively |
| (like the |
| .B O_EXCL |
| flag of |
| .BR open (2)). |
| If the file already exists, |
| .BR fopen () |
| fails, and sets |
| .I errno |
| to |
| .BR EEXIST . |
| This flag is ignored for |
| .BR fdopen (). |
| .PP |
| In addition to the above characters, |
| .BR fopen () |
| and |
| .BR freopen () |
| support the following syntax |
| in |
| .IR mode : |
| .PP |
| .BI " ,ccs=" string |
| .PP |
| The given |
| .I string |
| is taken as the name of a coded character set and |
| the stream is marked as wide-oriented. |
| Thereafter, internal conversion functions convert I/O |
| to and from the character set |
| .IR string . |
| If the |
| .BI ,ccs= string |
| syntax is not specified, |
| then the wide-orientation of the stream is |
| determined by the first file operation. |
| If that operation is a wide-character operation, |
| the stream is marked wide-oriented, |
| and functions to convert to the coded character set are loaded. |
| .SH BUGS |
| When parsing for individual flag characters in |
| .IR mode |
| (i.e., the characters preceding the "ccs" specification), |
| the glibc implementation of |
| .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 |
| .BR fopen () |
| and |
| .BR freopen () |
| limits the number of characters examined in |
| .I mode |
| to 7 (or, in glibc versions before 2.14, to 6, |
| which was not enough to include possible specifications such as "rb+cmxe"). |
| The current implementation of |
| .BR fdopen () |
| parses at most 5 characters in |
| .IR mode . |
| .SH SEE ALSO |
| .BR open (2), |
| .BR fclose (3), |
| .BR fileno (3), |
| .BR fmemopen (3), |
| .BR fopencookie (3), |
| .BR open_memstream (3) |