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