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