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