sys/man/2/fopen

   1 .TH FOPEN 2
   2 .SH NAME
   3 fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw, sclose, fflush, setvbuf, setbuf, fgetpos, ftell, fsetpos, fseek, rewind, feof, ferror, clearerr \- standard buffered input/output package
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <stdio.h>
   8 .PP
   9 .ta \w'\fLFILE 'u
  10 .B
  11 FILE    *fopen(char *filename, char *mode)
  12 .PP
  13 .B
  14 FILE    *freopen(char *filename, char *mode, FILE *f)
  15 .PP
  16 .B
  17 FILE    *fdopen(int fd, char *mode)
  18 .PP
  19 .B
  20 int     fileno(FILE *f)
  21 .PP
  22 .B
  23 FILE    *sopenr(char *s)
  24 .PP
  25 .B
  26 FILE    *sopenw(void)
  27 .PP
  28 .B
  29 char    *sclose(FILE *f)
  30 .PP
  31 .B
  32 int     fclose(FILE *f)
  33 .PP
  34 .B
  35 int     fflush(FILE *f)
  36 .PP
  37 .B
  38 int     setvbuf(FILE *f, char *buf, int type, long size)
  39 .PP
  40 .B
  41 void    setbuf(FILE *f, char *buf)
  42 .PP
  43 .B
  44 int     fgetpos(FILE *f, long *pos)
  45 .PP
  46 .B
  47 long    ftell(FILE *f)
  48 .PP
  49 .B
  50 int     fsetpos(FILE *f, long *pos)
  51 .PP
  52 .B
  53 int     fseek(FILE *f, long offset, int whence)
  54 .PP
  55 .B
  56 void    rewind(FILE *f)
  57 .PP
  58 .B
  59 int     feof(FILE *f)
  60 .PP
  61 .B
  62 int     ferror(FILE *f)
  63 .PP
  64 .B
  65 void    clearerr(FILE *f)
  66 .SH DESCRIPTION
  67 The functions described in this and related pages
  68 .RI ( fgetc (2),
  69 .IR fprintf (2),
  70 .IR fscanf (2),
  71 and
  72 .IR tmpfile (2))
  73 implement the
  74 ANSI C buffered I/O package with extensions.
  75 .PP
  76 A file with associated buffering is called a
  77 .I stream
  78 and is declared to be a pointer to a defined type
  79 .BR FILE .
  80 .IR  Fopen (2)
  81 creates certain descriptive data for a stream
  82 and returns a pointer to designate the stream in all
  83 further transactions.
  84 There are three normally open streams with constant
  85 pointers declared in
  86 the include file and associated with the standard open files:
  87 .TP 10n
  88 .BR stdin
  89 standard input file
  90 .br
  91 .ns
  92 .TP
  93 .B stdout
  94 standard output file
  95 .br
  96 .ns
  97 .TP
  98 .B stderr
  99 standard error file
 100 .PP
 101 A constant pointer
 102 .B NULL
 103 designates no stream at all.
 104 .PP
 105 .I Fopen
 106 opens the file named by
 107 .I filename
 108 and associates a stream with it.
 109 .I Fopen
 110 returns a pointer to be used to identify
 111 the stream in subsequent operations, or
 112 .B NULL
 113 if the open fails.
 114 .I Mode
 115 is a character string having one of the following values:
 116 .nf
 117 .ta 8n
 118 \fL"r"\fP       open for reading
 119 \fL"w"\fP       truncate to zero length or create for writing
 120 \fL"a"\fP       append; open or create for writing at end of file
 121 \fL"r+"\fP      open for update (reading and writing)
 122 \fL"w+"\fP      truncate to zero length or create for update
 123 \fL"a+"\fP      append; open or create for update at end of file
 124 .fi
 125 .PP
 126 In addition, each of the above strings can have a
 127 .L b
 128 somewhere after the first character,
 129 meaning `binary file', but this implementation makes no distinction
 130 between binary and text files.
 131 .PP
 132 .I Fclose
 133 causes the stream pointed to by
 134 .I f
 135 to be flushed (see below) and does a
 136 .I close
 137 (see
 138 .IR open (2))
 139 on the associated file.
 140 It frees any automatically allocated buffer.
 141 .I Fclose
 142 is called automatically on
 143 .IR exits (2)
 144 for all open streams.
 145 .PP
 146 .I Freopen
 147 is like open except that it reuses stream pointer
 148 .IR f .
 149 .I Freopen
 150 first attempts to close any file associated with
 151 .IR f ;
 152 it ignores any errors in that close.
 153 .PP
 154 .I Fdopen
 155 associates a stream with an open Plan 9 file descriptor.
 156 .PP
 157 .I Fileno
 158 returns the number of the Plan 9 file descriptor associated with the stream.
 159 .PP
 160 .I Sopenr
 161 associates a read-only stream with a null-terminated string.
 162 .PP
 163 .I Sopenw
 164 opens a stream for writing.
 165 No file descriptor is associated with the stream;
 166 instead, all output is written to the stream buffer.
 167 .PP
 168 .I Sclose
 169 closes a stream opened with
 170 .I sopenr
 171 or
 172 .IR sopenw .
 173 It returns a pointer to the 0 terminated buffer associated with the stream.
 174 .PP
 175 By default, output to a stream is fully buffered: it is accumulated in
 176 a buffer until the buffer is full, and then
 177 .I write
 178 (see
 179 .IR read (2))
 180 is used to write the buffer.
 181 An exception is standard error, which is line buffered:
 182 output is accumulated in a buffer until
 183 a newline is written.
 184 Input is also fully buffered by default; this means that
 185 .IR read (2)
 186 is used to fill a buffer as much as it can, and then characters
 187 are taken from that buffer until it empties.
 188 .I Setvbuf
 189 changes the buffering method for file
 190 .I f
 191 according to
 192 .IR type:
 193 either
 194 .B _IOFBF
 195 for fully buffered,
 196 .B _IOLBF
 197 for line buffered,
 198 or
 199 .B _IONBF
 200 for unbuffered (each character causes a
 201 .I read
 202 or
 203 .IR write).
 204 If
 205 .I buf
 206 is supplied, it is used as the buffer and
 207 .I size
 208 should be its size;
 209 If
 210 .I buf
 211 is zero, a buffer of the given size is allocated (except for the unbuffered case) using
 212 .IR malloc (2).
 213 .PP
 214 .I Setbuf
 215 is an older method for changing buffering.  If
 216 .I buf
 217 is supplied, it changes to fully buffered with the given buffer, which should
 218 be of size
 219 .B BUFSIZ
 220 (defined in
 221 .BR stdio.h ).
 222 If
 223 .I buf
 224 is zero, the buffering method changes to unbuffered.
 225 .PP
 226 .I Fflush
 227 flushes the buffer of output stream
 228 .IR f ,
 229 delivering any unwritten buffered data to the host file.
 230 .PP
 231 There is a
 232 .I file position indicator
 233 associated with each stream.
 234 It starts out pointing at the first character (unless the file is opened
 235 with append mode, in which case the indicator is always ignored).
 236 The file position indicator is maintained by the reading and writing
 237 functions described in
 238 .IR fgetc (2).
 239 .PP
 240 .I Fgetpos
 241 stores the current value of the file position indicator for stream
 242 .I f
 243 in the object pointed to by
 244 .IR pos .
 245 It returns zero on success, nonzero otherwise.
 246 .I Ftell
 247 returns the current value of the file position indicator.
 248 The file position indicator is to
 249 be used only as an argument to
 250 .IR fseek.
 251 .PP
 252 .I Fsetpos
 253 sets the file position indicator for stream
 254 .I f
 255 to the value of the object pointed to by
 256 .IR pos ,
 257 which shall be a value returned by an earlier call to
 258 .I fgetpos
 259 on the same stream.
 260 It returns zero on success, nonzero otherwise.
 261 .I Fseek
 262 obtains a new position, measured in characters from the beginning
 263 of the file, by adding
 264 .I offset
 265 to the position specified by
 266 .IR whence :
 267 the beginning of the file if
 268 .I whence
 269 is
 270 .BR SEEK_SET ;
 271 the current value of the file position indicator for
 272 .BR SEEK_CUR ;
 273 and the end-of-file for
 274 .BR SEEK_END .
 275 .I Rewind
 276 sets the file position indicator to the beginning of the file.
 277 .PP
 278 An integer constant
 279 .B EOF
 280 is returned
 281 upon end of file or error by integer-valued functions that
 282 deal with streams.
 283 .I Feof
 284 returns non-zero if and only if
 285 .I f
 286 is at its end of file.
 287 .PP
 288 .I Ferror
 289 returns non-zero if and only if
 290 .I f
 291 is in the error state.  It can get into the error state
 292 if a system call failed on the associated file
 293 or a memory allocation failed.
 294 .I Clearerr
 295 takes a stream out of the error state.
 296 .SH SOURCE
 297 .B /sys/src/libstdio
 298 .SH "SEE ALSO"
 299 .IR fprintf (2),
 300 .IR fscanf (2),
 301 .IR fgetc (2)
 302 .br
 303 .IR open (2),
 304 .IR read (2)
 305 .SH DIAGNOSTICS
 306 The value
 307 .B EOF
 308 is returned uniformly to indicate that a
 309 .B FILE
 310 pointer has not been initialized with
 311 .IR fopen ,
 312 input (output) has been attempted on an output (input) stream,
 313 or a
 314 .B FILE
 315 pointer designates corrupt or otherwise unintelligible
 316 .B FILE
 317 data.
 318 .br
 319 Some of these functions set
 320 .IR errstr .
 321 .SH BUGS
 322 Buffering of output can prevent output data
 323 from being seen until long after it is computed \- perhaps
 324 never, as when an abort occurs between buffer filling and flushing.
 325 .br
 326 Buffering of input can cause a process to consume
 327 more input than it actually uses.
 328 This can cause trouble across
 329 .IR exec (2).
 330 .br
 331 Buffering may delay the receipt of a write error until a subsequent
 332 .I stdio
 333 writing, seeking, or file-closing call.
 334 .br
 335 ANSI says that a file can be fully buffered only if
 336 the file is not attached to an interactive device.
 337 In Plan 9 all are fully buffered except standard error.
 338 .PP
 339 .IR Fdopen ,
 340 .IR fileno ,
 341 .IR sopenr ,
 342 .IR sopenw ,
 343 and
 344 .I sclose
 345 are not ANSI Stdio functions.
 346 .PP
 347 Stdio offers no support for runes or
 348 .SM UTF
 349 characters.
 350 Unless external compatibility is necessary, use
 351 .IR bio (2),
 352 which supports
 353 .SM UTF
 354 and is smaller, faster, and simpler than Stdio.