Opening a file with the fopen
function creates a new stream and
establishes a connection between the stream and a file. This may
involve creating a new file.
Everything described in this section is declared in the header file `stdio.h'.
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:
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
call fflush
(see section Stream Buffering) or a file positioning
function such as fseek
(see section 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, fopen
fails
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 section 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 section Text and 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
changed.
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.
You can have multiple streams (or file descriptors) pointing to the same file open at the same time. If you do only input, this works straightforwardly, but you must be careful if any output streams are included. See section Dangers of Mixing Streams and Descriptors. This is equally true whether the streams are in one program (not usual) or in several programs (which can easily happen). It may be advantageous to use the file locking facilities to avoid simultaneous access. See section File Locks.
fopen
but the stream it returns a
pointer for is opened using open64
. Therefore this stream can be
used even on files larger then @math{2^31} bytes on 32 bit machines.
Please note that the return type is still FILE *
. There is no
special FILE
type for the LFS interface.
If the sources are compiled with _FILE_OFFSET_BITS == 64
on a 32
bits machine this function is available under the name fopen
and so transparently replaces the old interface.
stdin
, stdout
, and stderr
. In POSIX.1 systems this
value is determined by the OPEN_MAX
parameter; see section General Capacity Limits. In BSD and GNU, it is controlled by the RLIMIT_NOFILE
resource limit; see section Limiting Resource Usage.
fclose
and fopen
.
It first closes the stream referred to by stream, ignoring any
errors that are detected in the process. (Because errors are ignored,
you should not use freopen
on an output stream if you have
actually done any output using the stream.) Then the file named by
filename is opened with mode opentype as for fopen
,
and associated with the same stream object stream.
If the operation fails, a null pointer is returned; otherwise,
freopen
returns stream.
freopen
has traditionally been used to connect a standard stream
such as stdin
with a file of your own choice. This is useful in
programs in which use of a standard stream for certain purposes is
hard-coded. In the GNU C library, you can simply close the standard
streams and open new ones with fopen
. But other systems lack
this ability, so using freopen
is more portable.
When the sources are compiling with _FILE_OFFSET_BITS == 64
on a
32 bit machine this function is in fact freopen64
since the LFS
interface replaces transparently the old interface.
freopen
. The only difference is that
on 32 bit machine the stream returned is able to read beyond the
@math{2^31} bytes limits imposed by the normal interface. It should be
noted that the stream pointed to by stream need not be opened
using fopen64
or freopen64
since its mode is not important
for this function.
If the sources are compiled with _FILE_OFFSET_BITS == 64
on a 32
bits machine this function is available under the name freopen
and so transparently replaces the old interface.
In some situations it is useful to know whether a given stream is available for reading or writing. This information is normally not available and would have to be remembered separately. Solaris introduced a few functions to get this information from the stream descriptor and these functions are also available in the GNU C library.
__freadable
function determines whether the stream
stream was opened to allow reading. In this case the return value
is nonzero. For write-only streams the function returns zero.
This function is declared in `stdio_ext.h'.
__fwritable
function determines whether the stream
stream was opened to allow writing. In this case the return value
is nonzero. For read-only streams the function returns zero.
This function is declared in `stdio_ext.h'.
For slightly different kind of problems there are two more functions. They provide even finer-grained information.
__freading
function determines whether the stream
stream was last read from or whether it is opened read-only. In
this case the return value is nonzero, otherwise it is zero.
Determining whether a stream opened for reading and writing was last
used for writing allows to draw conclusions about the content about the
buffer, among other things.
This function is declared in `stdio_ext.h'.
__fwriting
function determines whether the stream
stream was last written to or whether it is opened write-only. In
this case the return value is nonzero, otherwise it is zero.
This function is declared in `stdio_ext.h'.
Go to the first, previous, next, last section, table of contents.