fopen,
fdopen,
freopen —
stream open functions
library “libc”
#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);
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.
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.
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).
open(2),
fclose(3),
fileno(3),
fseek(3),
funopen(3)
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”).
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);
}