man3/fopen.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   9 .\"
  10 .\"     @(#)fopen.3     6.8 (Berkeley) 6/29/91
  11 .\"
  12 .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
  13 .\" Modified, aeb, 960421, 970806
  14 .\" Modified, joey, aeb, 2002-01-03
  15 .\"
  16 .TH fopen 3 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 fopen, fdopen, freopen \- stream open functions
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <stdio.h>
  25 .PP
  26 .BI "FILE *fopen(const char *restrict " pathname \
  27 ", const char *restrict " mode );
  28 .BI "FILE *fdopen(int " fd ", const char *" mode );
  29 .BI "FILE *freopen(const char *restrict " pathname \
  30 ", const char *restrict " mode ,
  31 .BI "              FILE *restrict " stream );
  32 .fi
  33 .PP
  34 .RS -4
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .RE
  38 .PP
  39 .BR fdopen ():
  40 .nf
  41     _POSIX_C_SOURCE
  42 .fi
  43 .SH DESCRIPTION
  44 The
  45 .BR fopen ()
  46 function opens the file whose name is the string pointed to by
  47 .I pathname
  48 and associates a stream with it.
  49 .PP
  50 The argument
  51 .I mode
  52 points to a string beginning with one of the following sequences
  53 (possibly followed by additional characters, as described below):
  54 .TP
  55 .B r
  56 Open text file for reading.
  57 The stream is positioned at the beginning of the file.
  58 .TP
  59 .B r+
  60 Open for reading and writing.
  61 The stream is positioned at the beginning of the file.
  62 .TP
  63 .B w
  64 Truncate file to zero length or create text file for writing.
  65 The stream is positioned at the beginning of the file.
  66 .TP
  67 .B w+
  68 Open for reading and writing.
  69 The file is created if it does not exist, otherwise it is truncated.
  70 The stream is positioned at the beginning of
  71 the file.
  72 .TP
  73 .B a
  74 Open for appending (writing at end of file).
  75 The file is created if it does not exist.
  76 The stream is positioned at the end of the file.
  77 .TP
  78 .B a+
  79 Open for reading and appending (writing at end of file).
  80 The file is created if it does not exist.
  81 Output is always appended to the end of the file.
  82 POSIX is silent on what the initial read position is when using this mode.
  83 For glibc, the initial file position for reading is at
  84 the beginning of the file, but for Android/BSD/MacOS, the
  85 initial file position for reading is at the end of the file.
  86 .PP
  87 The
  88 .I mode
  89 string can also include the letter \(aqb\(aq either as a last character or as
  90 a character between the characters in any of the two-character strings
  91 described above.
  92 This is strictly for compatibility with C89
  93 and has no effect; the \(aqb\(aq is ignored on all POSIX
  94 conforming systems, including Linux.
  95 (Other systems may treat text files and binary files differently,
  96 and adding the \(aqb\(aq may be a good idea if you do I/O to a binary
  97 file and expect that your program may be ported to non-UNIX
  98 environments.)
  99 .PP
 100 See NOTES below for details of glibc extensions for
 101 .IR mode .
 102 .PP
 103 Any created file will have the mode
 104 .BR S_IRUSR " | " S_IWUSR " | "  S_IRGRP " | "  S_IWGRP " | " S_IROTH " | " S_IWOTH
 105 (0666), as modified by the process's umask value (see
 106 .BR umask (2)).
 107 .PP
 108 Reads and writes may be intermixed on read/write streams in any order.
 109 Note that ANSI C requires that a file positioning function intervene
 110 between output and input, unless an input operation encounters end-of-file.
 111 (If this condition is not met, then a read is allowed to return the
 112 result of writes other than the most recent.)
 113 Therefore it is good practice (and indeed sometimes necessary
 114 under Linux) to put an
 115 .BR fseek (3)
 116 or
 117 .BR fsetpos (3)
 118 operation between write and read operations on such a stream.
 119 This operation may be an apparent no-op
 120 (as in \fIfseek(..., 0L, SEEK_CUR)\fP
 121 called for its synchronizing side effect).
 122 .PP
 123 Opening a file in append mode (\fBa\fP as the first character of
 124 .IR mode )
 125 causes all subsequent write operations to this stream to occur
 126 at end-of-file, as if preceded by the call:
 127 .PP
 128 .in +4n
 129 .EX
 130 fseek(stream, 0, SEEK_END);
 131 .EE
 132 .in
 133 .PP
 134 The file descriptor associated with the stream is opened as if by a call to
 135 .BR open (2)
 136 with the following flags:
 137 .RS
 138 .TS
 139 allbox;
 140 lb lb
 141 c l.
 142 fopen() mode    open() flags
 143 \fIr\fP O_RDONLY
 144 \fIw\fP O_WRONLY | O_CREAT | O_TRUNC
 145 \fIa\fP O_WRONLY | O_CREAT | O_APPEND
 146 \fIr+\fP        O_RDWR
 147 \fIw+\fP        O_RDWR | O_CREAT | O_TRUNC
 148 \fIa+\fP        O_RDWR | O_CREAT | O_APPEND
 149 .TE
 150 .RE
 151 .\"
 152 .SS fdopen()
 153 The
 154 .BR fdopen ()
 155 function associates a stream with the existing file descriptor,
 156 .IR fd .
 157 The
 158 .I mode
 159 of the stream (one of the values "r", "r+", "w", "w+", "a", "a+")
 160 must be compatible with the mode of the file descriptor.
 161 The file position indicator of the new stream is set to that
 162 belonging to
 163 .IR fd ,
 164 and the error and end-of-file indicators are cleared.
 165 Modes "w" or "w+" do not cause truncation of the file.
 166 The file descriptor is not dup'ed, and will be closed when
 167 the stream created by
 168 .BR fdopen ()
 169 is closed.
 170 The result of applying
 171 .BR fdopen ()
 172 to a shared memory object is undefined.
 173 .\"
 174 .SS freopen()
 175 The
 176 .BR freopen ()
 177 function opens the file whose name is the string pointed to by
 178 .I pathname
 179 and associates the stream pointed to by
 180 .I stream
 181 with it.
 182 The original stream (if it exists) is closed.
 183 The
 184 .I mode
 185 argument is used just as in the
 186 .BR fopen ()
 187 function.
 188 .PP
 189 If the
 190 .I pathname
 191 argument is a null pointer,
 192 .BR freopen ()
 193 changes the mode of the stream to that specified in
 194 .IR mode ;
 195 that is,
 196 .BR freopen ()
 197 reopens the pathname that is associated with the stream.
 198 The specification for this behavior was added in the C99 standard, which says:
 199 .PP
 200 .RS
 201 In this case,
 202 the file descriptor associated with the stream need not be closed
 203 if the call to
 204 .BR freopen ()
 205 succeeds.
 206 It is implementation-defined which changes of mode are permitted (if any),
 207 and under what circumstances.
 208 .RE
 209 .PP
 210 The primary use of the
 211 .BR freopen ()
 212 function is to change the file associated with a standard text stream
 213 .RI ( stderr ", " stdin ", or " stdout ).
 214 .SH RETURN VALUE
 215 Upon successful completion
 216 .BR fopen (),
 217 .BR fdopen (),
 218 and
 219 .BR freopen ()
 220 return a
 221 .I FILE
 222 pointer.
 223 Otherwise, NULL is returned and
 224 .I errno
 225 is set to indicate the error.
 226 .SH ERRORS
 227 .TP
 228 .B EINVAL
 229 The
 230 .I mode
 231 provided to
 232 .BR fopen (),
 233 .BR fdopen (),
 234 or
 235 .BR freopen ()
 236 was invalid.
 237 .PP
 238 The
 239 .BR fopen (),
 240 .BR fdopen (),
 241 and
 242 .BR freopen ()
 243 functions may also fail and set
 244 .I errno
 245 for any of the errors specified for the routine
 246 .BR malloc (3).
 247 .PP
 248 The
 249 .BR fopen ()
 250 function may also fail and set
 251 .I errno
 252 for any of the errors specified for the routine
 253 .BR open (2).
 254 .PP
 255 The
 256 .BR fdopen ()
 257 function may also fail and set
 258 .I errno
 259 for any of the errors specified for the routine
 260 .BR fcntl (2).
 261 .PP
 262 The
 263 .BR freopen ()
 264 function may also fail and set
 265 .I errno
 266 for any of the errors specified for the routines
 267 .BR open (2),
 268 .BR fclose (3),
 269 and
 270 .BR fflush (3).
 271 .SH ATTRIBUTES
 272 For an explanation of the terms used in this section, see
 273 .BR attributes (7).
 274 .ad l
 275 .nh
 276 .TS
 277 allbox;
 278 lbx lb lb
 279 l l l.
 280 Interface       Attribute       Value
 281 T{
 282 .BR fopen (),
 283 .BR fdopen (),
 284 .BR freopen ()
 285 T}      Thread safety   MT-Safe
 286 .TE
 287 .hy
 288 .ad
 289 .sp 1
 290 .SH STANDARDS
 291 .BR fopen (),
 292 .BR freopen ():
 293 POSIX.1-2001, POSIX.1-2008, C89, C99.
 294 .PP
 295 .BR fdopen ():
 296 POSIX.1-2001, POSIX.1-2008.
 297 .SH NOTES
 298 .SS Glibc notes
 299 The GNU C library allows the following extensions for the string specified in
 300 .IR mode :
 301 .TP
 302 .BR c " (since glibc 2.3.3)"
 303 Do not make the open operation,
 304 or subsequent read and write operations,
 305 thread cancelation points.
 306 This flag is ignored for
 307 .BR fdopen ().
 308 .TP
 309 .BR e " (since glibc 2.7)"
 310 Open the file with the
 311 .B O_CLOEXEC
 312 flag.
 313 See
 314 .BR open (2)
 315 for more information.
 316 This flag is ignored for
 317 .BR fdopen ().
 318 .TP
 319 .BR m " (since glibc 2.3)"
 320 Attempt to access the file using
 321 .BR mmap (2),
 322 rather than I/O system calls
 323 .RB ( read (2),
 324 .BR write (2)).
 325 Currently,
 326 .\" As at glibc 2.4:
 327 use of
 328 .BR mmap (2)
 329 is attempted only for a file opened for reading.
 330 .TP
 331 .B x
 332 .\" Since glibc 2.0?
 333 .\" FIXME . C11 specifies this flag
 334 Open the file exclusively
 335 (like the
 336 .B O_EXCL
 337 flag of
 338 .BR open (2)).
 339 If the file already exists,
 340 .BR fopen ()
 341 fails, and sets
 342 .I errno
 343 to
 344 .BR EEXIST .
 345 This flag is ignored for
 346 .BR fdopen ().
 347 .PP
 348 In addition to the above characters,
 349 .BR fopen ()
 350 and
 351 .BR freopen ()
 352 support the following syntax
 353 in
 354 .IR mode :
 355 .PP
 356 .BI "    ,ccs=" string
 357 .PP
 358 The given
 359 .I string
 360 is taken as the name of a coded character set and
 361 the stream is marked as wide-oriented.
 362 Thereafter, internal conversion functions convert I/O
 363 to and from the character set
 364 .IR string .
 365 If the
 366 .BI ,ccs= string
 367 syntax is not specified,
 368 then the wide-orientation of the stream is
 369 determined by the first file operation.
 370 If that operation is a wide-character operation,
 371 the stream is marked wide-oriented,
 372 and functions to convert to the coded character set are loaded.
 373 .SH BUGS
 374 When parsing for individual flag characters in
 375 .I mode
 376 (i.e., the characters preceding the "ccs" specification),
 377 the glibc implementation of
 378 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685
 379 .BR fopen ()
 380 and
 381 .BR freopen ()
 382 limits the number of characters examined in
 383 .I mode
 384 to 7 (or, in glibc versions before 2.14, to 6,
 385 which was not enough to include possible specifications such as "rb+cmxe").
 386 The current implementation of
 387 .BR fdopen ()
 388 parses at most 5 characters in
 389 .IR mode .
 390 .SH SEE ALSO
 391 .BR open (2),
 392 .BR fclose (3),
 393 .BR fileno (3),
 394 .BR fmemopen (3),
 395 .BR fopencookie (3),
 396 .BR open_memstream (3)