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 .\" 3. 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: src/lib/libc/stdio/fopen.3,v 1.20 2007/01/09 00:28:06 imp Exp $
  34 .\"
  35 .Dd February 22, 2018
  36 .Dt FOPEN 3
  37 .Os
  38 .Sh NAME
  39 .Nm fopen ,
  40 .Nm fdopen ,
  41 .Nm freopen
  42 .Nd stream open functions
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdio.h
  47 .Ft FILE *
  48 .Fn fopen "const char * restrict path" "const char * restrict mode"
  49 .Ft FILE *
  50 .Fn fdopen "int fildes" "const char *mode"
  51 .Ft FILE *
  52 .Fn freopen "const char * restrict path" "const char * restrict mode" "FILE * restrict stream"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn fopen
  56 function
  57 opens the file whose name is the string pointed to by
  58 .Fa path
  59 and associates a stream with it.
  60 .Pp
  61 The argument
  62 .Fa mode
  63 points to a string beginning with one of the following
  64 sequences (Additional characters may follow these sequences.):
  65 .Bl -tag -width indent
  66 .It Dq Li r
  67 Open file for reading.
  68 The stream is positioned at the beginning of the file.
  69 .It Dq Li w
  70 Open file for writing.
  71 Creates the file if it does not already exist,
  72 truncates the file if it does.
  73 .It Dq Li a
  74 Open file for append.
  75 Creates the file if it does not already exist.
  76 Seeks to end of the file.
  77 Subsequent writes to the file will always end up at the then current
  78 end of file, irrespective of any intervening
  79 .Xr fseek 3
  80 or similar operation.
  81 .El
  82 .Pp
  83 Additional flags may modify the primary mode as follows:
  84 .Bl -tag -width indent
  85 .It Dq Li +
  86 The file will be opened for both reading and writing.
  87 For example 'r+' or 'w+'.
  88 .It Dq Li x
  89 The open will fail if the file already exists (C11).
  90 For example 'wx'.
  91 .It Dq Li e
  92 Close-on-exec.  The underlying descriptor will automatically be closed on
  93 any exec() (glibc compatibility).
  94 .It Dq Li b
  95 Binary mode.  On UNIX systems file reading and writing is always in binary
  96 mode so this flag has no effect.
  97 .El
  98 .Pp
  99 The
 100 .Fa mode
 101 string can also include the letter ``b'' either as a third character or
 102 as a character between the characters in any of the two-character strings
 103 described above.
 104 This is strictly for compatibility with
 105 .St -isoC-2011
 106 and has no effect; the ``b'' is ignored.
 107 .Pp
 108 Any created files will have mode
 109 .Pf \\*q Dv S_IRUSR
 110 \&|
 111 .Dv S_IWUSR
 112 \&|
 113 .Dv S_IRGRP
 114 \&|
 115 .Dv S_IWGRP
 116 \&|
 117 .Dv S_IROTH
 118 \&|
 119 .Dv S_IWOTH Ns \\*q
 120 .Pq Li 0666 ,
 121 as modified by the process'
 122 umask value (see
 123 .Xr umask 2 ) .
 124 .Pp
 125 Reads and writes may be intermixed on read/write streams in any order,
 126 and do not require an intermediate seek as in previous versions of
 127 .Em stdio .
 128 This is not portable to other systems, however;
 129 .Tn ANSI C
 130 requires that
 131 a file positioning function intervene between output and input, unless
 132 an input operation encounters end-of-file.
 133 .Pp
 134 The
 135 .Fn fdopen
 136 function associates a stream with the existing file descriptor,
 137 .Fa fildes .
 138 The mode
 139 of the stream must be compatible with the mode of the file descriptor.
 140 When the stream is closed via
 141 .Xr fclose 3 ,
 142 .Fa fildes
 143 is closed also.
 144 .Pp
 145 The
 146 .Fn freopen
 147 function
 148 opens the file whose name is the string pointed to by
 149 .Fa path
 150 and associates the stream pointed to by
 151 .Fa stream
 152 with it.
 153 The original stream (if it exists) is closed.
 154 The
 155 .Fa mode
 156 argument is used just as in the
 157 .Fn fopen
 158 function.
 159 .Pp
 160 If the
 161 .Fa path
 162 argument is
 163 .Dv NULL ,
 164 .Fn freopen
 165 attempts to re-open the file associated with
 166 .Fa stream
 167 with a new mode.
 168 The new mode must be compatible with the mode that the stream was originally
 169 opened with:
 170 .Bl -bullet -offset indent
 171 .It
 172 Streams originally opened with mode
 173 .Dq Li r
 174 can only be reopened with that same mode.
 175 .It
 176 Streams originally opened with mode
 177 .Dq Li a
 178 can be reopened with the same mode, or mode
 179 .Dq Li w .
 180 .It
 181 Streams originally opened with mode
 182 .Dq Li w
 183 can be reopened with the same mode, or mode
 184 .Dq Li a .
 185 .It
 186 Streams originally opened with mode
 187 .Dq Li r+ ,
 188 .Dq Li w+ ,
 189 or
 190 .Dq Li a+
 191 can be reopened with any mode.
 192 .El
 193 .Pp
 194 The primary use of the
 195 .Fn freopen
 196 function
 197 is to change the file associated with a
 198 standard text stream
 199 .Dv ( stderr , stdin ,
 200 or
 201 .Dv stdout ) .
 202 .Sh RETURN VALUES
 203 Upon successful completion
 204 .Fn fopen ,
 205 .Fn fdopen
 206 and
 207 .Fn freopen
 208 return a
 209 .Tn FILE
 210 pointer.
 211 Otherwise,
 212 .Dv NULL
 213 is returned and the global variable
 214 .Va errno
 215 is set to indicate the error.
 216 .Sh ERRORS
 217 .Bl -tag -width Er
 218 .It Bq Er EINVAL
 219 The
 220 .Fa mode
 221 argument
 222 to
 223 .Fn fopen ,
 224 .Fn fdopen ,
 225 or
 226 .Fn freopen
 227 was invalid.
 228 .El
 229 .Pp
 230 The
 231 .Fn fopen ,
 232 .Fn fdopen
 233 and
 234 .Fn freopen
 235 functions
 236 may also fail and set
 237 .Va errno
 238 for any of the errors specified for the routine
 239 .Xr malloc 3 .
 240 .Pp
 241 The
 242 .Fn fopen
 243 function
 244 may also fail and set
 245 .Va errno
 246 for any of the errors specified for the routine
 247 .Xr open 2 .
 248 .Pp
 249 The
 250 .Fn fdopen
 251 function
 252 may also fail and set
 253 .Va errno
 254 for any of the errors specified for the routine
 255 .Xr fcntl 2 .
 256 .Pp
 257 The
 258 .Fn freopen
 259 function
 260 may also fail and set
 261 .Va errno
 262 for any of the errors specified for the routines
 263 .Xr open 2 ,
 264 .Xr fclose 3
 265 and
 266 .Xr fflush 3 .
 267 .Sh SEE ALSO
 268 .Xr open 2 ,
 269 .Xr fclose 3 ,
 270 .Xr fileno 3 ,
 271 .Xr fseek 3 ,
 272 .Xr funopen 3
 273 .Sh STANDARDS
 274 The
 275 .Fn fopen
 276 and
 277 .Fn freopen
 278 functions
 279 conform to
 280 .St -isoC-2011 .
 281 The
 282 .Fn fdopen
 283 function
 284 conforms to
 285 .St -p1003.1-88 .