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