fopen function opens a stream for I/O to the file
filename, and returns a pointer to the stream.
The opentype argument is a string that controls how the file is
opened and specifies attributes of the resulting stream. It must begin
with one of the following sequences of characters:
- Open an existing file for reading only.
- Open the file for writing only. If the file already exists, it is
truncated to zero length. Otherwise a new file is created.
- Open a file for append access; that is, writing at the end of file only.
If the file already exists, its initial contents are unchanged and
output to the stream is appended to the end of the file.
Otherwise, a new, empty file is created.
- Open an existing file for both reading and writing. The initial contents
of the file are unchanged and the initial file position is at the
beginning of the file.
- Open a file for both reading and writing. If the file already exists, it
is truncated to zero length. Otherwise, a new file is created.
- Open or create file for both reading and appending. If the file exists,
its initial contents are unchanged. Otherwise, a new file is created.
The initial file position for reading is at the beginning of the file,
but output is always appended to the end of the file.
As you can see, `+' requests a stream that can do both input and
output. The ISO standard says that when using such a stream, you must
fflush (see Stream Buffering) or a file positioning
function such as
fseek (see File Positioning) when switching
from reading to writing or vice versa. Otherwise, internal buffers
might not be emptied properly. The GNU C library does not have this
limitation; you can do arbitrary reading and writing operations on a
stream in whatever order.
Additional characters may appear after these to specify flags for the
call. Always put the mode (`r', `w+', etc.) first; that is
the only part you are guaranteed will be understood by all systems.
The GNU C library defines one additional character for use in
opentype: the character `x' insists on creating a new
file—if a file filename already exists,
rather than opening it. If you use `x' you are guaranteed that
you will not clobber an existing file. This is equivalent to the
O_EXCL option to the
open function (see Opening and Closing Files).
The character `b' in opentype has a standard meaning; it
requests a binary stream rather than a text stream. But this makes no
difference in POSIX systems (including the GNU system). If both
`+' and `b' are specified, they can appear in either order.
See Binary Streams.
If the opentype string contains the sequence
,ccs=STRING then STRING is taken as the name of a
coded character set and
fopen will mark the stream as
wide-oriented which appropriate conversion functions in place to convert
from and to the character set STRING is place. Any other stream
is opened initially unoriented and the orientation is decided with the
first file operation. If the first operation is a wide character
operation, the stream is not only marked as wide-oriented, also the
conversion functions to convert to the coded character set used for the
current locale are loaded. This will not change anymore from this point
on even if the locale selected for the
LC_CTYPE category is
Any other characters in opentype are simply ignored. They may be
meaningful in other systems.
If the open fails,
fopen returns a null pointer.
When the sources are compiling with
_FILE_OFFSET_BITS == 64 on a
32 bit machine this function is in fact
fopen64 since the LFS
interface replaces transparently the old interface.