FOPEN(3) NEWLIB FOPEN(3)NAME
4.17 `fopen'--open a file
SYNOPSIS
#include <stdio.h>
FILE *fopen(const char *FILE, const char *MODE);
FILE *_fopen_r(struct _reent *REENT,
const char *FILE, const char *MODE);
DESCRIPTION
`fopen' initializes the data structures needed to read or write a file.
Specify the file's name as the string at FILE, and the kind of access
you need to the file with the string at MODE.
The alternate function `_fopen_r' is a reentrant version. The extra
argument REENT is a pointer to a reentrancy structure.
Three fundamental kinds of access are available: read, write, and
append. `*MODE' must begin with one of the three characters ``r'',
``w'', or ``a'', to select one of these:
`r'
Open the file for reading; the operation will fail if the file
does
not exist, or if the host system does not permit you to read it.
`w'
Open the file for writing _from the beginning_ of the file:
effectively, this always creates a new file. If the file whose
name you specified already existed, its old contents are dis‐
carded.
`a'
Open the file for appending data, that is writing from the end of
file. When you open a file this way, all data always goes to the
current end of file; you cannot change this using `fseek'.
Some host systems distinguish between "binary" and "text" files.
Such systems may perform data transformations on data written to, or
read from, files opened as "text". If your system is one of these,
then you can append a ``b'' to any of the three modes above, to specify
that you are opening the file as a binary file (the default is to open
the file as a text file).
``rb'', then, means "read binary"; ``wb'', "write binary"; and
``ab'', "append binary".
To make C programs more portable, the ``b'' is accepted on all sys‐
tems, whether or not it makes a difference.
Finally, you might need to both read and write from the same file.
You can also append a ``+'' to any of the three modes, to permit this.
(If you want to append both ``b'' and ``+'', you can do it in either
order: for example, `"rb+"' means the same thing as `"r+b"' when used
as a mode string.)
Use `"r+"' (or `"rb+"') to permit reading and writing anywhere in an
existing file, without discarding any data; `"w+"' (or `"wb+"') to cre‐
ate a new file (or begin by discarding all data from an old one) that
permits reading and writing anywhere in it; and `"a+"' (or `"ab+"') to
permit reading anywhere in an existing file, but writing only at the
end.
RETURNS
`fopen' returns a file pointer which you can use for other file opera‐
tions, unless the file you requested could not be opened; in that situ‐
ation, the result is `NULL'. If the reason for failure was an invalid
string at MODE, `errno' is set to `EINVAL'.
PORTABILITY
`fopen' is required by ANSI C.
Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `open', `read', `sbrk', `write'.
SEE ALSOfopen is part of the library. The full documentation for is maintained
as a Texinfo manual. If info and are properly installed at your site,
the command
info
will give you access to the complete manual.
NEWLIB April 2010 FOPEN(3)
