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. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)fopen.3     8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdio/fopen.3,v 1.18 2003/01/26 10:01:59 tjr Exp $
  38 .\"
  39 .Dd January 26, 2003
  40 .Dt FOPEN 3
  41 .Os
  42 .Sh NAME
  43 .Nm fdopen ,
  44 .Nm fopen ,
  45 .Nm freopen
  46 .Nd stream open functions
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In stdio.h
  51 .Ft FILE *
  52 .Fo fdopen
  53 .Fa "int fildes"
  54 .Fa "const char *mode"
  55 .Fc
  56 .Ft FILE *
  57 .Fo fopen
  58 .Fa "const char *restrict filename"
  59 .Fa "const char *restrict mode"
  60 .Fc
  61 .Ft FILE *
  62 .Fo freopen
  63 .Fa "const char *restrict filename"
  64 .Fa "const char *restrict mode"
  65 .Fa "FILE *restrict stream"
  66 .Fc
  67 .Sh DESCRIPTION
  68 The
  69 .Fn fopen
  70 function
  71 opens the file whose name is the string pointed to by
  72 .Fa filename
  73 and associates a stream with it.
  74 .Pp
  75 The argument
  76 .Fa mode
  77 points to a string beginning with one of the following
  78 sequences (Additional characters may follow these sequences.):
  79 .Bl -tag -width indent
  80 .It Dq Li r
  81 Open text file for reading.
  82 The stream is positioned at the beginning of the file.
  83 .It Dq Li r+
  84 Open for reading and writing.
  85 The stream is positioned at the beginning of the file.
  86 .It Dq Li w
  87 Truncate file to zero length or create text file for writing.
  88 The stream is positioned at the beginning of the file.
  89 .It Dq Li w+
  90 Open for reading and writing.
  91 The file is created if it does not exist, otherwise it is truncated.
  92 The stream is positioned at the beginning of the file.
  93 .It Dq Li a
  94 Open for writing.
  95 The file is created if it does not exist.
  96 The stream is positioned at the end of the file.
  97 Subsequent writes to the file will always end up at the then current
  98 end of file, irrespective of any intervening
  99 .Xr fseek 3
 100 or similar.
 101 .It Dq Li a+
 102 Open for reading and writing.
 103 The file is created if it does not exist.
 104 The stream is positioned at the end of the file.
 105 Subsequent writes to the file will always end up at the then current
 106 end of file, irrespective of any intervening
 107 .Xr fseek 3
 108 or similar.
 109 .El
 110 .Pp
 111 The
 112 .Fa mode
 113 string can also include the letter ``b'' either as a third character or
 114 as a character between the characters in any of the two-character strings
 115 described above.
 116 This is strictly for compatibility with
 117 .St -isoC
 118 and has no effect; the ``b'' is ignored.
 119 .Pp
 120 Finally, as an extension to the standards (and thus may not be portable),
 121 .Fa mode
 122 string may end with the letter ``x'', which insists on creating a new file
 123 when used with ``w'' or ``a''.
 124 If
 125 .Fa path
 126 exists, then an error is returned (this is the equivalent of specifying
 127 .Dv O_EXCL
 128 with
 129 .Xr open 2 ) .
 130 .Pp
 131 Any created files will have mode
 132 .Pf \\*q Dv S_IRUSR
 133 \&|
 134 .Dv S_IWUSR
 135 \&|
 136 .Dv S_IRGRP
 137 \&|
 138 .Dv S_IWGRP
 139 \&|
 140 .Dv S_IROTH
 141 \&|
 142 .Dv S_IWOTH Ns \\*q
 143 .Pq Li 0666 ,
 144 as modified by the process'
 145 umask value (see
 146 .Xr umask 2 ) .
 147 .Pp
 148 Reads and writes may be intermixed on read/write streams in any order,
 149 and do not require an intermediate seek as in previous versions of
 150 .Em stdio .
 151 This is not portable to other systems, however;
 152 .Tn ANSI C
 153 requires that
 154 a file positioning function intervene between output and input, unless
 155 an input operation encounters end-of-file.
 156 .Pp
 157 The
 158 .Fn fdopen
 159 function associates a stream with the existing file descriptor,
 160 .Fa fildes .
 161 The mode
 162 of the stream must be compatible with the mode of the file descriptor.
 163 When the stream is closed via
 164 .Xr fclose 3 ,
 165 .Fa fildes
 166 is closed also.
 167 .Pp
 168 The
 169 .Fn freopen
 170 function
 171 opens the file whose name is the string pointed to by
 172 .Fa filename
 173 and associates the stream pointed to by
 174 .Fa stream
 175 with it.
 176 The original stream (if it exists) is closed.
 177 The
 178 .Fa mode
 179 argument is used just as in the
 180 .Fn fopen
 181 function.
 182 .Pp
 183 If the
 184 .Fa filename
 185 argument is
 186 .Dv NULL ,
 187 .Fn freopen
 188 attempts to re-open the file associated with
 189 .Fa stream
 190 with a new mode.
 191 The new mode must be compatible with the mode that the stream was originally
 192 opened with:
 193 .Bl -bullet -offset indent
 194 .It
 195 Streams originally opened with mode
 196 .Dq Li r
 197 can only be reopened with that same mode.
 198 .It
 199 Streams originally opened with mode
 200 .Dq Li a
 201 can be reopened with the same mode, or mode
 202 .Dq Li w .
 203 .It
 204 Streams originally opened with mode
 205 .Dq Li w
 206 can be reopened with the same mode, or mode
 207 .Dq Li a .
 208 .It
 209 Streams originally opened with mode
 210 .Dq Li r+ ,
 211 .Dq Li w+ ,
 212 or
 213 .Dq Li a+
 214 can be reopened with any mode.
 215 .El
 216 .Pp
 217 The primary use of the
 218 .Fn freopen
 219 function
 220 is to change the file associated with a
 221 standard text stream
 222 .Dv ( stderr , stdin ,
 223 or
 224 .Dv stdout ) .
 225 .Sh RETURN VALUES
 226 Upon successful completion
 227 .Fn fopen ,
 228 .Fn fdopen ,
 229 and
 230 .Fn freopen
 231 return a
 232 .Tn FILE
 233 pointer.
 234 Otherwise,
 235 .Dv NULL
 236 is returned and the global variable
 237 .Va errno
 238 is set to indicate the error.
 239 .Sh ERRORS
 240 .Bl -tag -width Er
 241 .It Bq Er EINVAL
 242 The
 243 .Fa mode
 244 argument
 245 to
 246 .Fn fopen ,
 247 .Fn fdopen ,
 248 or
 249 .Fn freopen
 250 was invalid.
 251 .El
 252 .Pp
 253 The
 254 .Fn fopen ,
 255 .Fn fdopen
 256 and
 257 .Fn freopen
 258 functions
 259 may also fail and set
 260 .Va errno
 261 for any of the errors specified for the routine
 262 .Xr malloc 3 .
 263 .Pp
 264 The
 265 .Fn fopen
 266 function
 267 may also fail and set
 268 .Va errno
 269 for any of the errors specified for the routine
 270 .Xr open 2 .
 271 .Pp
 272 The
 273 .Fn fdopen
 274 function
 275 may also fail and set
 276 .Va errno
 277 for any of the errors specified for the routine
 278 .Xr fcntl 2 .
 279 .Pp
 280 The
 281 .Fn freopen
 282 function
 283 may also fail and set
 284 .Va errno
 285 for any of the errors specified for the routines
 286 .Xr open 2 ,
 287 .Xr fclose 3
 288 and
 289 .Xr fflush 3 .
 290 .Sh SEE ALSO
 291 .Xr open 2 ,
 292 .Xr fclose 3 ,
 293 .Xr fileno 3 ,
 294 .Xr fseek 3 ,
 295 .Xr funopen 3
 296 .Sh STANDARDS
 297 The
 298 .Fn fopen
 299 and
 300 .Fn freopen
 301 functions
 302 conform to
 303 .St -isoC .
 304 The
 305 .Fn fdopen
 306 function
 307 conforms to
 308 .St -p1003.1-88 .