NAME
fopen,
fdopen,
freopen
—
stream open functions
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdio.h>
FILE *
fopen(
const char
* restrict path,
const char
* restrict mode);
FILE *
fdopen(
int
fildes,
const char
*mode);
FILE *
freopen(
const
char * restrict path,
const
char * restrict mode,
FILE
* restrict stream);
DESCRIPTION
The
fopen() function opens the file whose name is the string
pointed to by
path and associates a stream with it.
The argument
mode points to a string beginning with one of
the following sequences (Additional characters may follow these sequences.):
-
-
- “
a
”
- Append; open for writing. The file is created if it does
not exist.
-
-
- “
a+
”
- Append; open for reading and writing. The file is created
if it does not exist.
-
-
- “
r
”
- Open for reading.
-
-
- “
r+
”
- Open for reading and writing.
-
-
- “
w
”
- Open for writing. Truncate file to zero length or create
file.
-
-
- “
w+
”
- Open for reading and writing. Truncate file to zero length
or create file.
Additionally, the
mode string can also include one of the
following letters:
-
-
- ‘b’
- The letter ‘b’ may appear 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 ANSI X3.159-1989
(“ANSI C89”) and has no effect; the
‘b’ is ignored.
-
-
- ‘e’
- The letter ‘e’ in the mode string sets the
close-on-exec flag in the file descriptors of the newly opened file files;
if the operation fails, fopen() will fail. This is a non
ANSI X3.159-1989 (“ANSI C89”)
extension.
-
-
- ‘f’
- The letter ‘f’ in the mode string restricts
fopen() to regular files; if the file opened is not a
regular file, fopen() will fail. This is a non
ANSI X3.159-1989 (“ANSI C89”)
extension.
-
-
- ‘x’
- The letter ‘x’ in the mode turns on exclusive
open mode to the file (
O_EXCL
) which means that
the file will not be created if it already exists.
Any created files will have mode "
S_IRUSR
|
S_IWUSR
|
S_IRGRP
|
S_IWGRP
|
S_IROTH
|
S_IWOTH
" (
0666
), as
modified by the process'
umask(2)
value.
Opening a file with append mode causes all subsequent writes to it to be forced
to the then current end of file, regardless of intervening repositioning of
the stream.
The
fopen() and
freopen() functions
initially position the stream at the start of the file unless the file is
opened with append mode, in which case the stream is initially positioned at
the end of the file.
The
fdopen() function associates a stream with the existing
file descriptor,
fildes. The
mode
of the stream must be compatible with the mode of the file descriptor. The
stream is positioned at the file offset of the file descriptor.
The
freopen() function opens the file whose name is the string
pointed to by
path and associates the stream pointed to
by
stream with it. The original stream (if it exists) is
closed. The
mode argument is used just as in the
fopen() function. The primary use of the
freopen() function is to change the file associated with a
standard text stream (
stderr,
stdin, or
stdout).
Input and output against the opened stream will be fully buffered, unless it
refers to an interactive terminal device, or a different kind of buffering is
specified in the environment. See
setvbuf(3) for additional
details.
RETURN VALUES
Upon successful completion
fopen(),
fdopen()
and
freopen() return a FILE pointer. Otherwise,
NULL
is returned and the global variable
errno is set to indicate the error.
ERRORS
The functions may fail if:
-
-
- [
EFTYPE
]
- The file is not a regular file and the character ``f'' is
specified in the mode.
-
-
- [
EINVAL
]
- The specified mode was invalid.
The
fopen(),
fdopen() and
freopen() functions may also fail and set
errno for any of the errors specified for the routine
malloc(3).
The
fopen() function may also fail and set
errno for any of the errors specified for the routine
open(2).
The
fdopen() function may also fail and set
errno for any of the errors specified for the routine
fcntl(2).
The
freopen() function may also fail and set
errno for any of the errors specified for the routines
open(2),
fclose(3) and
fflush(3).
SEE ALSO
open(2),
fclose(3),
fileno(3),
fseek(3),
funopen(3)
STANDARDS
The
fopen() and
freopen() functions conform
to
ANSI X3.159-1989 (“ANSI C89”). All
three functions are specified in
IEEE Std 1003.1-2008
(“POSIX.1”).
CAVEATS
Proper code using
fdopen() with error checking should
close(2)
fildes in case of failure, and
fclose(3) the resulting FILE *
in case of success.
FILE *file;
int fd;
if ((file = fdopen(fd, "r")) != NULL) {
/* perform operations on the FILE * */
fclose(file);
} else {
/* failure, report the error */
close(fd);
}