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 .Pp
 144 Reads and writes may be intermixed on read/write streams in any order,
 145 and do not require an intermediate seek as in previous versions of
 146 .Em stdio .
 147 This is not portable to other systems, however;
 148 .Tn ANSI C
 149 requires that
 150 a file positioning function intervene between output and input, unless
 151 an input operation encounters end-of-file.
 152 .Pp
 153 The
 154 .Fn fdopen
 155 function associates a stream with the existing file descriptor,
 156 .Fa fildes .
 157 The mode
 158 of the stream must be compatible with the mode of the file descriptor.
 159 When the stream is closed via
 160 .Xr fclose 3 ,
 161 .Fa fildes
 162 is closed also.
 163 .Pp
 164 The
 165 .Fn freopen
 166 function
 167 opens the file whose name is the string pointed to by
 168 .Fa filename
 169 and associates the stream pointed to by
 170 .Fa stream
 171 with it.
 172 The original stream (if it exists) is closed.
 173 The
 174 .Fa mode
 175 argument is used just as in the
 176 .Fn fopen
 177 function.
 178 .Pp
 179 If the
 180 .Fa filename
 181 argument is
 182 .Dv NULL ,
 183 .Fn freopen
 184 attempts to re-open the file associated with
 185 .Fa stream
 186 with a new mode.
 187 The new mode must be compatible with the mode that the stream was originally
 188 opened with:
 189 .Bl -bullet -offset indent
 190 .It
 191 Streams originally opened with mode
 192 .Dq Li r
 193 can only be reopened with that same mode.
 194 .It
 195 Streams originally opened with mode
 196 .Dq Li a
 197 can be reopened with the same mode, or mode
 198 .Dq Li w .
 199 .It
 200 Streams originally opened with mode
 201 .Dq Li w
 202 can be reopened with the same mode, or mode
 203 .Dq Li a .
 204 .It
 205 Streams originally opened with mode
 206 .Dq Li r+ ,
 207 .Dq Li w+ ,
 208 or
 209 .Dq Li a+
 210 can be reopened with any mode.
 211 .El
 212 .Pp
 213 The primary use of the
 214 .Fn freopen
 215 function
 216 is to change the file associated with a
 217 standard text stream
 218 .Dv ( stderr , stdin ,
 219 or
 220 .Dv stdout ) .
 221 .Sh RETURN VALUES
 222 Upon successful completion
 223 .Fn fopen ,
 224 .Fn fdopen ,
 225 and
 226 .Fn freopen
 227 return a
 228 .Tn FILE
 229 pointer.
 230 Otherwise,
 231 .Dv NULL
 232 is returned and the global variable
 233 .Va errno
 234 is set to indicate the error.
 235 .Sh ERRORS
 236 .Bl -tag -width Er
 237 .It Bq Er EINVAL
 238 The
 239 .Fa mode
 240 argument
 241 to
 242 .Fn fopen ,
 243 .Fn fdopen ,
 244 or
 245 .Fn freopen
 246 was invalid.
 247 .El
 248 .Pp
 249 The
 250 .Fn fopen ,
 251 .Fn fdopen
 252 and
 253 .Fn freopen
 254 functions
 255 may also fail and set
 256 .Va errno
 257 for any of the errors specified for the routine
 258 .Xr malloc 3 .
 259 .Pp
 260 The
 261 .Fn fopen
 262 function
 263 may also fail and set
 264 .Va errno
 265 for any of the errors specified for the routine
 266 .Xr open 2 .
 267 .Pp
 268 The
 269 .Fn fdopen
 270 function
 271 may also fail and set
 272 .Va errno
 273 for any of the errors specified for the routine
 274 .Xr fcntl 2 .
 275 .Pp
 276 The
 277 .Fn freopen
 278 function
 279 may also fail and set
 280 .Va errno
 281 for any of the errors specified for the routines
 282 .Xr open 2 ,
 283 .Xr fclose 3
 284 and
 285 .Xr fflush 3 .
 286 .Sh SEE ALSO
 287 .Xr open 2 ,
 288 .Xr fclose 3 ,
 289 .Xr fileno 3 ,
 290 .Xr fseek 3 ,
 291 .Xr funopen 3
 292 .Sh STANDARDS
 293 The
 294 .Fn fopen
 295 and
 296 .Fn freopen
 297 functions
 298 conform to
 299 .St -isoC .
 300 The
 301 .Fn fdopen
 302 function
 303 conforms to
 304 .St -p1003.1-88 .