lib/libc/stdio/fopen.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  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 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)fopen.3     8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd January 30, 2013
  36 .Dt FOPEN 3
  37 .Os
  38 .Sh NAME
  39 .Nm fopen ,
  40 .Nm fdopen ,
  41 .Nm freopen ,
  42 .Nm fmemopen
  43 .Nd stream open functions
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In stdio.h
  48 .Ft FILE *
  49 .Fn fopen "const char * restrict path" "const char * restrict mode"
  50 .Ft FILE *
  51 .Fn fdopen "int fildes" "const char *mode"
  52 .Ft FILE *
  53 .Fn freopen "const char *path" "const char *mode" "FILE *stream"
  54 .Ft FILE *
  55 .Fn fmemopen "void *restrict *buf" "size_t size" "const char * restrict mode"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn fopen
  59 function
  60 opens the file whose name is the string pointed to by
  61 .Fa path
  62 and associates a stream with it.
  63 .Pp
  64 The argument
  65 .Fa mode
  66 points to a string beginning with one of the following letters:
  67 .Bl -tag -width indent
  68 .It Dq Li r
  69 Open for reading.
  70 The stream is positioned at the beginning of the file.
  71 Fail if the file does not exist.
  72 .It Dq Li w
  73 Open for writing.
  74 The stream is positioned at the beginning of the file.
  75 Create the file if it does not exist.
  76 .It Dq Li a
  77 Open for writing.
  78 The stream is positioned at the end of the file.
  79 Subsequent writes to the file will always end up at the then current
  80 end of file, irrespective of any intervening
  81 .Xr fseek 3
  82 or similar.
  83 Create the file if it does not exist.
  84 .El
  85 .Pp
  86 An optional
  87 .Dq Li +
  88 following
  89 .Dq Li r ,
  90 .Dq Li w ,
  91 or
  92 .Dq Li a
  93 opens the file for both reading and writing.
  94 An optional
  95 .Dq Li x
  96 following
  97 .Dq Li w
  98 or
  99 .Dq Li w+
 100 causes the
 101 .Fn fopen
 102 call to fail if the file already exists.
 103 An optional
 104 .Dq Li e
 105 following the above
 106 causes the
 107 .Fn fopen
 108 call to set the
 109 .Dv FD_CLOEXEC
 110 flag on the underlying file descriptor.
 111 .Pp
 112 The
 113 .Fa mode
 114 string can also include the letter
 115 .Dq Li b
 116 after either the
 117 .Dq Li +
 118 or the first letter.
 119 This is strictly for compatibility with
 120 .St -isoC
 121 and has effect only for
 122 .Fn fmemopen
 123 ; otherwise the ``b'' is ignored.
 124 .Pp
 125 Any created files will have mode
 126 .Do Dv S_IRUSR
 127 \&|
 128 .Dv S_IWUSR
 129 \&|
 130 .Dv S_IRGRP
 131 \&|
 132 .Dv S_IWGRP
 133 \&|
 134 .Dv S_IROTH
 135 \&|
 136 .Dv S_IWOTH Dc
 137 .Pq Li 0666 ,
 138 as modified by the process'
 139 umask value (see
 140 .Xr umask 2 ) .
 141 .Pp
 142 Reads and writes may be intermixed on read/write streams in any order,
 143 and do not require an intermediate seek as in previous versions of
 144 .Em stdio .
 145 This is not portable to other systems, however;
 146 .Tn ANSI C
 147 requires that
 148 a file positioning function intervene between output and input, unless
 149 an input operation encounters end-of-file.
 150 .Pp
 151 The
 152 .Fn fdopen
 153 function associates a stream with the existing file descriptor,
 154 .Fa fildes .
 155 The mode
 156 of the stream must be compatible with the mode of the file descriptor.
 157 The
 158 .Dq Li x
 159 mode option is ignored.
 160 If the
 161 .Dq Li e
 162 mode option is present, the
 163 .Dv FD_CLOEXEC
 164 flag is set, otherwise it remains unchanged.
 165 When the stream is closed via
 166 .Xr fclose 3 ,
 167 .Fa fildes
 168 is closed also.
 169 .Pp
 170 The
 171 .Fn freopen
 172 function
 173 opens the file whose name is the string pointed to by
 174 .Fa path
 175 and associates the stream pointed to by
 176 .Fa stream
 177 with it.
 178 The original stream (if it exists) is closed.
 179 The
 180 .Fa mode
 181 argument is used just as in the
 182 .Fn fopen
 183 function.
 184 .Pp
 185 If the
 186 .Fa path
 187 argument is
 188 .Dv NULL ,
 189 .Fn freopen
 190 attempts to re-open the file associated with
 191 .Fa stream
 192 with a new mode.
 193 The new mode must be compatible with the mode that the stream was originally
 194 opened with:
 195 Streams open for reading can only be re-opened for reading,
 196 streams open for writing can only be re-opened for writing,
 197 and streams open for reading and writing can be re-opened in any mode.
 198 The
 199 .Dq Li x
 200 mode option is not meaningful in this context.
 201 .Pp
 202 The primary use of the
 203 .Fn freopen
 204 function
 205 is to change the file associated with a
 206 standard text stream
 207 .Dv ( stderr , stdin ,
 208 or
 209 .Dv stdout ) .
 210 .Pp
 211 The
 212 .Fn fmemopen
 213 function
 214 associates the buffer given by the
 215 .Fa buf
 216 and
 217 .Fa size
 218 arguments with a stream.
 219 The
 220 .Fa buf
 221 argument is either a null pointer or point to a buffer that
 222 is at least
 223 .Fa size
 224 bytes long.
 225 If a null pointer is specified as the
 226 .Fa buf
 227 argument,
 228 .Fn fmemopen
 229 allocates
 230 .Fa size
 231 bytes of memory. This buffer is automatically freed when the
 232 stream is closed. Buffers can be opened in text-mode (default) or binary-mode
 233 (if ``b'' is present in the second or third position of the
 234 .Fa mode
 235 argument). Buffers opened in text-mode make sure that writes are terminated with
 236 a NULL byte, if the last write hasn't filled up the whole buffer. Buffers
 237 opened in binary-mode never append a NULL byte.
 238 .Sh RETURN VALUES
 239 Upon successful completion
 240 .Fn fopen ,
 241 .Fn fdopen
 242 and
 243 .Fn freopen
 244 return a
 245 .Tn FILE
 246 pointer.
 247 Otherwise,
 248 .Dv NULL
 249 is returned and the global variable
 250 .Va errno
 251 is set to indicate the error.
 252 .Sh ERRORS
 253 .Bl -tag -width Er
 254 .It Bq Er EINVAL
 255 The
 256 .Fa mode
 257 argument
 258 to
 259 .Fn fopen ,
 260 .Fn fdopen ,
 261 .Fn freopen ,
 262 or
 263 .Fn fmemopen
 264 was invalid.
 265 .El
 266 .Pp
 267 The
 268 .Fn fopen ,
 269 .Fn fdopen ,
 270 .Fn freopen
 271 and
 272 .Fn fmemopen
 273 functions
 274 may also fail and set
 275 .Va errno
 276 for any of the errors specified for the routine
 277 .Xr malloc 3 .
 278 .Pp
 279 The
 280 .Fn fopen
 281 function
 282 may also fail and set
 283 .Va errno
 284 for any of the errors specified for the routine
 285 .Xr open 2 .
 286 .Pp
 287 The
 288 .Fn fdopen
 289 function
 290 may also fail and set
 291 .Va errno
 292 for any of the errors specified for the routine
 293 .Xr fcntl 2 .
 294 .Pp
 295 The
 296 .Fn freopen
 297 function
 298 may also fail and set
 299 .Va errno
 300 for any of the errors specified for the routines
 301 .Xr open 2 ,
 302 .Xr fclose 3
 303 and
 304 .Xr fflush 3 .
 305 .Pp
 306 The
 307 .Fn fmemopen
 308 function
 309 may also fail and set
 310 .Va errno
 311 if the
 312 .Fa size
 313 argument is 0.
 314 .Sh SEE ALSO
 315 .Xr open 2 ,
 316 .Xr fclose 3 ,
 317 .Xr fileno 3 ,
 318 .Xr fseek 3 ,
 319 .Xr funopen 3
 320 .Sh STANDARDS
 321 The
 322 .Fn fopen
 323 and
 324 .Fn freopen
 325 functions
 326 conform to
 327 .St -isoC ,
 328 with the exception of the
 329 .Dq Li x
 330 mode option which conforms to
 331 .St -isoC-2011 .
 332 The
 333 .Fn fdopen
 334 function
 335 conforms to
 336 .St -p1003.1-88 .
 337 The
 338 .Dq Li e
 339 mode option does not conform to any standard
 340 but is also supported by glibc.
 341 The
 342 .Fn fmemopen
 343 function
 344 conforms to
 345 .St -p1003.1-2008 .
 346 The ``b'' mode does not conform to any standard
 347 but is also supported by glibc.