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. 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.7.2.6 2001/12/14 18:33:57 ru Exp $
  38 .\"
  39 .Dd June 4, 1993
  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 *path" "const char *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
 141 .Fa mode
 142 of the stream must be compatible with the mode of the file descriptor.
 143 When the stream is closed via
 144 .Xr fclose 3 ,
 145 .Fa fildes
 146 is closed also.
 147 .Pp
 148 The
 149 .Fn freopen
 150 function
 151 opens the file whose name is the string pointed to by
 152 .Fa path
 153 and associates the stream pointed to by
 154 .Fa stream
 155 with it.
 156 The original stream (if it exists) is closed.
 157 The
 158 .Fa mode
 159 argument is used just as in the
 160 .Fn fopen
 161 function.
 162 The primary use of the
 163 .Fn freopen
 164 function
 165 is to change the file associated with a
 166 standard text stream
 167 .Pf ( Em stderr ,
 168 .Em stdin ,
 169 or
 170 .Em stdout ) .
 171 .Sh RETURN VALUES
 172 Upon successful completion
 173 .Fn fopen ,
 174 .Fn fdopen
 175 and
 176 .Fn freopen
 177 return a
 178 .Tn FILE
 179 pointer.
 180 Otherwise,
 181 .Dv NULL
 182 is returned and the global variable
 183 .Va errno
 184 is set to indicate the error.
 185 .Sh ERRORS
 186 .Bl -tag -width Er
 187 .It Bq Er EINVAL
 188 The
 189 .Fa mode
 190 provided to
 191 .Fn fopen ,
 192 .Fn fdopen ,
 193 or
 194 .Fn freopen
 195 was invalid.
 196 .El
 197 .Pp
 198 The
 199 .Fn fopen ,
 200 .Fn fdopen
 201 and
 202 .Fn freopen
 203 functions
 204 may also fail and set
 205 .Va errno
 206 for any of the errors specified for the routine
 207 .Xr malloc 3 .
 208 .Pp
 209 The
 210 .Fn fopen
 211 function
 212 may also fail and set
 213 .Va errno
 214 for any of the errors specified for the routine
 215 .Xr open 2 .
 216 .Pp
 217 The
 218 .Fn fdopen
 219 function
 220 may also fail and set
 221 .Va errno
 222 for any of the errors specified for the routine
 223 .Xr fcntl 2 .
 224 .Pp
 225 The
 226 .Fn freopen
 227 function
 228 may also fail and set
 229 .Va errno
 230 for any of the errors specified for the routines
 231 .Xr open 2 ,
 232 .Xr fclose 3
 233 and
 234 .Xr fflush 3 .
 235 .Sh SEE ALSO
 236 .Xr open 2 ,
 237 .Xr fclose 3 ,
 238 .Xr fileno 3 ,
 239 .Xr fseek 3 ,
 240 .Xr funopen 3
 241 .Sh STANDARDS
 242 The
 243 .Fn fopen
 244 and
 245 .Fn freopen
 246 functions
 247 conform to
 248 .St -isoC .
 249 The
 250 .Fn fdopen
 251 function
 252 conforms to
 253 .St -p1003.1-88 .