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

NAME

12       fopen — open a stream
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

193   Opening a File
194       The  following  example  tries to open the file named file for reading.
195       The fopen() function returns a file pointer that is used in  subsequent
196       fgets()  and  fclose()  calls.  If the program cannot open the file, it
197       just ignores it.
198
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‐2017, <stdio.h>
226
228       Portions  of  this text are reprinted and reproduced in electronic form
229       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
230       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
231       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
232       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
233       event of any discrepancy between this version and the original IEEE and
234       The  Open Group Standard, the original IEEE and The Open Group Standard
235       is the referee document. The original Standard can be  obtained  online
236       at http://www.opengroup.org/unix/online.html .
237
238       Any  typographical  or  formatting  errors that appear in this page are
239       most likely to have been introduced during the conversion of the source
240       files  to  man page format. To report such errors, see https://www.ker
241       nel.org/doc/man-pages/reporting_bugs.html .
242
243
244
245IEEE/The Open Group                  2017                            FOPEN(3P)
Impressum