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