1FOPEN(3P)                  POSIX Programmer's Manual                 FOPEN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       fopen — open a stream
14

SYNOPSIS

16       #include <stdio.h>
17
18       FILE *fopen(const char *restrict pathname, const char *restrict mode);
19

DESCRIPTION

21       The functionality described on this reference page is aligned with  the
22       ISO C  standard.  Any  conflict between the requirements described here
23       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2008
24       defers to the ISO C standard.
25
26       The  fopen()  function shall open the file whose pathname is the string
27       pointed to by pathname, and associates a stream with it.
28
29       The mode argument points to a string. If the string is one of the  fol‐
30       lowing,  the file shall be opened in the indicated mode. Otherwise, the
31       behavior is undefined.
32
33       r or rb       Open file for reading.
34
35       w or wb       Truncate to zero length or create file for writing.
36
37       a or ab       Append; open or create file for writing at end-of-file.
38
39       r+ or rb+ or r+b
40                     Open file for update (reading and writing).
41
42       w+ or wb+ or w+b
43                     Truncate to zero length or create file for update.
44
45       a+ or ab+ or a+b
46                     Append; open or create file for update, writing  at  end-
47                     of-file.
48
49       The  character 'b' shall have no effect, but is allowed for ISO C stan‐
50       dard conformance.  Opening a file with read mode (r as the first  char‐
51       acter  in  the  mode argument) shall fail if the file does not exist or
52       cannot be read.
53
54       Opening a file with append mode (a as the first character in  the  mode
55       argument) shall cause all subsequent writes to the file to be forced to
56       the then  current  end-of-file,  regardless  of  intervening  calls  to
57       fseek().
58
59       When  a  file  is  opened  with update mode ('+' as the second or third
60       character in the mode argument), both input and output may be performed
61       on  the  associated  stream. However, the application shall ensure that
62       output is not directly followed by input without an intervening call to
63       fflush()  or  to  a  file  positioning function (fseek(), fsetpos(), or
64       rewind()), and input is not directly  followed  by  output  without  an
65       intervening call to a file positioning function, unless the input oper‐
66       ation encounters end-of-file.
67
68       When opened, a stream is fully buffered if and only if it can be deter‐
69       mined  not to refer to an interactive device. The error and end-of-file
70       indicators for the stream shall be cleared.
71
72       If mode is w, wb, a, ab, w+, wb+, w+b, a+, ab+, or a+b,  and  the  file
73       did  not  previously  exist,  upon successful completion, fopen() shall
74       mark for update the last data access, last data modification, and  last
75       file  status  change  timestamps  of  the file and the last file status
76       change and last data modification timestamps of the parent directory.
77
78       If mode is w, wb, a, ab, w+, wb+, w+b, a+, ab+, or a+b,  and  the  file
79       did  not  previously exist, the fopen() function shall create a file as
80       if it called the creat() function with a value appropriate for the path
81       argument  interpreted  from pathname and a value of S_IRUSR | S_IWUSR |
82       S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH for the mode argument.
83
84       If mode is w, wb, w+, wb+, or w+b, and the file did  previously  exist,
85       upon successful completion, fopen() shall mark for update the last data
86       modification and last file status change timestamps of the file.
87
88       After a successful call to the fopen() function, the orientation of the
89       stream  shall  be  cleared, the encoding rule shall be cleared, and the
90       associated mbstate_t object shall be set to describe an initial conver‐
91       sion state.
92
93       The  file  descriptor  associated with the opened stream shall be allo‐
94       cated and opened as if by a call to open() with the following flags:
95
96                   ┌─────────────────┬───────────────────────────┐
97fopen() Mode   open() Flags        
98                   ├─────────────────┼───────────────────────────┤
99r or rb          │ O_RDONLY                  │
100w or wb          │ O_WRONLY|O_CREAT|O_TRUNC  │
101a or ab          │ O_WRONLY|O_CREAT|O_APPEND │
102r+ or rb+ or r+b │ O_RDWR                    │
103w+ or wb+ or w+b │ O_RDWR|O_CREAT|O_TRUNC    │
104a+ or ab+ or a+b │ O_RDWR|O_CREAT|O_APPEND   │
105                   └─────────────────┴───────────────────────────┘

RETURN VALUE

107       Upon successful completion, fopen()  shall  return  a  pointer  to  the
108       object  controlling  the  stream.  Otherwise,  a  null pointer shall be
109       returned, and errno shall be set to indicate the error.
110

ERRORS

112       The fopen() function shall fail if:
113
114       EACCES Search permission is denied on a component of the  path  prefix,
115              or  the  file  exists  and the permissions specified by mode are
116              denied, or the file does  not  exist  and  write  permission  is
117              denied for the parent directory of the file to be created.
118
119       EINTR  A signal was caught during fopen().
120
121       EISDIR The named file is a directory and mode requires write access.
122
123       ELOOP  A loop exists in symbolic links encountered during resolution of
124              the path argument.
125
126       EMFILE All file descriptors available  to  the  process  are  currently
127              open.
128
129       EMFILE {STREAM_MAX} streams are currently open in the calling process.
130
131       ENAMETOOLONG
132              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
133              tion of a symbolic link produced an intermediate result  with  a
134              length that exceeds {PATH_MAX}.
135
136       ENFILE The  maximum  allowable number of files is currently open in the
137              system.
138
139       ENOENT The mode string begins with 'r' and a component of pathname does
140              not  name an existing file, or mode begins with 'w' or 'a' and a
141              component of the path prefix of pathname does not name an exist‐
142              ing file, or pathname is an empty string.
143
144       ENOENT or ENOTDIR
145              The  pathname argument contains at least one non-<slash> charac‐
146              ter and ends with one or more trailing  <slash>  characters.  If
147              pathname  names  an  existing  file, an [ENOENT] error shall not
148              occur.
149
150       ENOSPC The directory or file system that would  contain  the  new  file
151              cannot be expanded, the file does not exist, and the file was to
152              be created.
153
154       ENOTDIR
155              A component of the path prefix names an existing  file  that  is
156              neither  a  directory nor a symbolic link to a directory, or the
157              pathname argument contains at least  one  non-<slash>  character
158              and  ends  with  one or more trailing <slash> characters and the
159              last pathname component names an existing file that is neither a
160              directory nor a symbolic link to a directory.
161
162       ENXIO  The named file is a character special or block special file, and
163              the device associated with this special file does not exist.
164
165       EOVERFLOW
166              The named file is a regular file and the size of the file cannot
167              be represented correctly in an object of type off_t.
168
169       EROFS  The  named  file  resides  on  a  read-only file system and mode
170              requires write access.
171
172       The fopen() function may fail if:
173
174       EINVAL The value of the mode argument is not valid.
175
176       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
177              resolution of the path argument.
178
179       EMFILE {FOPEN_MAX} streams are currently open in the calling process.
180
181       ENAMETOOLONG
182              The  length  of  a  component  of  a  pathname  is  longer  than
183              {NAME_MAX}.
184
185       ENOMEM Insufficient storage space is available.
186
187       ETXTBSY
188              The file is a pure procedure (shared text) file  that  is  being
189              executed and mode requires write access.
190
191       The following sections are informative.
192

EXAMPLES

194   Opening a File
195       The  following  example  tries to open the file named file for reading.
196       The fopen() function returns a file pointer that is used in  subsequent
197       fgets()  and  fclose()  calls.  If the program cannot open the file, it
198       just ignores it.
199
200           #include <stdio.h>
201           ...
202           FILE *fp;
203           ...
204           void rgrep(const char *file)
205           {
206           ...
207               if ((fp = fopen(file, "r")) == NULL)
208                   return;
209           ...
210           }
211

APPLICATION USAGE

213       None.
214

RATIONALE

216       None.
217

FUTURE DIRECTIONS

219       None.
220

SEE ALSO

222       Section 2.5, Standard I/O Streams, creat(), fclose(), fdopen(),  fmemo‐
223       pen(), freopen(), open_memstream()
224
225       The Base Definitions volume of POSIX.1‐2008, <stdio.h>
226
228       Portions  of  this text are reprinted and reproduced in electronic form
229       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
230       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
231       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
232       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
233       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
234       event of any discrepancy between this version and the original IEEE and
235       The Open Group Standard, the original IEEE and The Open Group  Standard
236       is  the  referee document. The original Standard can be obtained online
237       at http://www.unix.org/online.html .
238
239       Any typographical or formatting errors that appear  in  this  page  are
240       most likely to have been introduced during the conversion of the source
241       files to man page format. To report such errors,  see  https://www.ker
242       nel.org/doc/man-pages/reporting_bugs.html .
243
244
245
246IEEE/The Open Group                  2013                            FOPEN(3P)
Impressum