1FOPEN(3)                   Linux Programmer's Manual                  FOPEN(3)
2
3
4

NAME

6       fopen, fdopen, freopen - stream open functions
7

SYNOPSIS

9       #include <stdio.h>
10
11       FILE *fopen(const char *path, const char *mode);
12
13       FILE *fdopen(int fd, const char *mode);
14
15       FILE *freopen(const char *path, const char *mode, FILE *stream);
16
17   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18
19       fdopen(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
20

DESCRIPTION

22       The fopen() function opens the file whose name is the string pointed to
23       by path and associates a stream with it.
24
25       The argument mode points to a string beginning with one of the  follow‐
26       ing sequences (Additional characters may follow these sequences.):
27
28       r      Open  text  file  for  reading.  The stream is positioned at the
29              beginning of the file.
30
31       r+     Open for reading and writing.  The stream is positioned  at  the
32              beginning of the file.
33
34       w      Truncate  file  to  zero length or create text file for writing.
35              The stream is positioned at the beginning of the file.
36
37       w+     Open for reading and writing.  The file is created  if  it  does
38              not  exist, otherwise it is truncated.  The stream is positioned
39              at the beginning of the file.
40
41       a      Open for appending (writing at end of file).  The file  is  cre‐
42              ated  if it does not exist.  The stream is positioned at the end
43              of the file.
44
45       a+     Open for reading and appending (writing at end  of  file).   The
46              file is created if it does not exist.  The initial file position
47              for reading is at the beginning  of  the  file,  but  output  is
48              always appended to the end of the file.
49
50       The  mode string can also include the letter 'b' either as a last char‐
51       acter or as a character between the characters in any of the  two-char‐
52       acter strings described above.  This is strictly for compatibility with
53       C89 and has no effect; the 'b' is ignored on all POSIX conforming  sys‐
54       tems,  including Linux.  (Other systems may treat text files and binary
55       files differently, and adding the 'b' may be a good idea if you do  I/O
56       to a binary file and expect that your program may be ported to non-Unix
57       environments.)
58
59       See NOTES below for details of glibc extensions for mode.
60
61       Any created files will have mode S_IRUSR | S_IWUSR | S_IRGRP |  S_IWGRP
62       |  S_IROTH  |  S_IWOTH (0666), as modified by the process's umask value
63       (see umask(2)).
64
65       Reads and writes may be intermixed on read/write streams in any  order.
66       Note  that  ANSI  C requires that a file positioning function intervene
67       between output and input, unless an input operation encounters  end-of-
68       file.   (If this condition is not met, then a read is allowed to return
69       the result of writes other than the most recent.)  Therefore it is good
70       practice  (and  indeed  sometimes  necessary  under  Linux)  to  put an
71       fseek(3) or fgetpos(3) operation between write and read  operations  on
72       such  a  stream.   This  operation  may  be  an  apparent  no-op (as in
73       fseek(..., 0L, SEEK_CUR) called for its synchronizing side effect.
74
75       Opening a file in append mode (a as the first character of mode) causes
76       all subsequent write operations to this stream to occur at end-of-file,
77       as if preceded by an
78
79           fseek(stream,0,SEEK_END);
80
81       call.
82
83       The fdopen() function  associates  a  stream  with  the  existing  file
84       descriptor,  fd.   The mode of the stream (one of the values "r", "r+",
85       "w", "w+", "a", "a+") must be compatible with  the  mode  of  the  file
86       descriptor.   The  file  position indicator of the new stream is set to
87       that belonging to fd, and the  error  and  end-of-file  indicators  are
88       cleared.   Modes  "w" or "w+" do not cause truncation of the file.  The
89       file descriptor is not dup'ed, and will be closed when the stream  cre‐
90       ated  by  fdopen()  is  closed.   The  result of applying fdopen() to a
91       shared memory object is undefined.
92
93       The freopen() function opens the file whose name is the string  pointed
94       to by path and associates the stream pointed to by stream with it.  The
95       original stream (if it exists) is closed.  The mode  argument  is  used
96       just  as  in  the  fopen()  function.  The primary use of the freopen()
97       function is to change the file associated with a standard  text  stream
98       (stderr, stdin, or stdout).
99

RETURN VALUE

101       Upon  successful  completion  fopen(),  fdopen() and freopen() return a
102       FILE pointer.  Otherwise, NULL is returned and errno is set to indicate
103       the error.
104

ERRORS

106       EINVAL The  mode  provided  to  fopen(),  fdopen(),  or  freopen()  was
107              invalid.
108
109       The fopen(), fdopen() and freopen() functions may  also  fail  and  set
110       errno for any of the errors specified for the routine malloc(3).
111
112       The  fopen() function may also fail and set errno for any of the errors
113       specified for the routine open(2).
114
115       The fdopen() function may also fail and set errno for any of the errors
116       specified for the routine fcntl(2).
117
118       The  freopen()  function  may  also  fail  and set errno for any of the
119       errors specified for the routines open(2), fclose(3) and fflush(3).
120

CONFORMING TO

122       The fopen() and freopen() functions conform to C89.  The fdopen() func‐
123       tion conforms to POSIX.1-1990.
124

NOTES

126   Glibc Notes
127       The GNU C library allows the following extensions for the string speci‐
128       fied in mode:
129
130       c (since glibc 2.3.3)
131              Do not make the open operation, or  subsequent  read  and  write
132              operations, thread cancellation points.
133
134       e (since glibc 2.7)
135              Open  the  file  with  the O_CLOEXEC flag.  See open(2) for more
136              information.
137
138       m (since glibc 2.3)
139              Attempt to access the file using mmap(2), rather than I/O system
140              calls  (read(2),  write(2)).   Currently, use of mmap(2) is only
141              attempted for a file opened for reading.
142
143       x      Open the file exclusively (like the O_EXCL flag of open(2)).  If
144              the  file  already exists, fopen() fails, and sets errno to EEX‐
145              IST.  This flag is ignored for fdopen().
146

SEE ALSO

148       open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3)
149

COLOPHON

151       This page is part of release 3.22 of the Linux  man-pages  project.   A
152       description  of  the project, and information about reporting bugs, can
153       be found at http://www.kernel.org/doc/man-pages/.
154
155
156
157GNU                               2009-02-23                          FOPEN(3)
Impressum