FOPEN(2)                                                 FOPEN(2)

     NAME
          fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw,
          sclose, fflush, setvbuf, setbuf, fgetpos, ftell, fsetpos,
          fseek, rewind, feof, ferror, clearerr - standard buffered
          input/output package

     SYNOPSIS
          #include <u.h>
          #include <stdio.h>

          FILE *fopen(char *filename, char *mode)

          FILE *freopen(char *filename, char *mode, FILE *f)

          FILE *fdopen(int fd, char *mode)

          int  fileno(FILE *f)

          FILE *sopenr(char *s)

          FILE *sopenw(void)

          char *sclose(FILE *f)

          int  fclose(FILE *f)

          int  fflush(FILE *f)

          int  setvbuf(FILE *f, char *buf, int type, long size)

          void setbuf(FILE *f, char *buf)

          int  fgetpos(FILE *f, long *pos)

          long ftell(FILE *f)

          int  fsetpos(FILE *f, long *pos)

          int  fseek(FILE *f, long offset, int whence)

          void rewind(FILE *f)

          int  feof(FILE *f)

          int  ferror(FILE *f)

          void clearerr(FILE *f)

     DESCRIPTION
          The functions described in this and related pages (fgetc(2),

     Page 1                       Plan 9             (printed 3/19/24)

     FOPEN(2)                                                 FOPEN(2)

          fprintf(2), fscanf(2), and tmpfile(2)) implement the ANSI C
          buffered I/O package with extensions.

          A file with associated buffering is called a stream and is
          declared to be a pointer to a defined type FILE.  Fopen(2)
          creates certain descriptive data for a stream and returns a
          pointer to designate the stream in all further transactions.
          There are three normally open streams with constant pointers
          declared in the include file and associated with the stan-
          dard open files:

          stdin     standard input file
          stdout    standard output file
          stderr    standard error file

          A constant pointer NULL designates no stream at all.

          Fopen opens the file named by filename and associates a
          stream with it.  Fopen returns a pointer to be used to iden-
          tify the stream in subsequent operations, or NULL if the
          open fails.  Mode is a character string having one of the
          following values:
          "r"     open for reading
          "w"     truncate to zero length or create for writing
          "a"     append; open or create for writing at end of file
          "r+"    open for update (reading and writing)
          "w+"    truncate to zero length or create for update
          "a+"    append; open or create for update at end of file

          In addition, each of the above strings can have a `b' some-
          where after the first character, meaning `binary file', but
          this implementation makes no distinction between binary and
          text files.

          Fclose causes the stream pointed to by f to be flushed (see
          below) and does a close (see open(2)) on the associated
          file.  It frees any automatically allocated buffer.  Fclose
          is called automatically on exits(2) for all open streams.

          Freopen is like open except that it reuses stream pointer f.
          Freopen first attempts to close any file associated with f;
          it ignores any errors in that close.

          Fdopen associates a stream with an open Plan 9 file descrip-
          tor.

          Fileno returns the number of the Plan 9 file descriptor
          associated with the stream.

          Sopenr associates a read-only stream with a null-terminated
          string.

     Page 2                       Plan 9             (printed 3/19/24)

     FOPEN(2)                                                 FOPEN(2)

          Sopenw opens a stream for writing.  No file descriptor is
          associated with the stream; instead, all output is written
          to the stream buffer.

          Sclose closes a stream opened with sopenr or sopenw. It
          returns a pointer to the 0 terminated buffer associated with
          the stream.

          By default, output to a stream is fully buffered: it is
          accumulated in a buffer until the buffer is full, and then
          write (see read(2)) is used to write the buffer.  An excep-
          tion is standard error, which is line buffered: output is
          accumulated in a buffer until a newline is written.  Input
          is also fully buffered by default; this means that read(2)
          is used to fill a buffer as much as it can, and then charac-
          ters are taken from that buffer until it empties.  Setvbuf
          changes the buffering method for file f according to type:
          either _IOFBF for fully buffered, _IOLBF for line buffered,
          or _IONBF for unbuffered (each character causes a read or
          write). If buf is supplied, it is used as the buffer and
          size should be its size; If buf is zero, a buffer of the
          given size is allocated (except for the unbuffered case)
          using malloc(2).

          Setbuf is an older method for changing buffering.  If buf is
          supplied, it changes to fully buffered with the given
          buffer, which should be of size BUFSIZ (defined in stdio.h).
          If buf is zero, the buffering method changes to unbuffered.

          Fflush flushes the buffer of output stream f, delivering any
          unwritten buffered data to the host file.

          There is a file position indicator associated with each
          stream.  It starts out pointing at the first character
          (unless the file is opened with append mode, in which case
          the indicator is always ignored).  The file position indica-
          tor is maintained by the reading and writing functions
          described in fgetc(2).

          Fgetpos stores the current value of the file position indi-
          cator for stream f in the object pointed to by pos. It
          returns zero on success, nonzero otherwise.  Ftell returns
          the current value of the file position indicator.  The file
          position indicator is to be used only as an argument to
          fseek.

          Fsetpos sets the file position indicator for stream f to the
          value of the object pointed to by pos, which shall be a
          value returned by an earlier call to fgetpos on the same
          stream.  It returns zero on success, nonzero otherwise.
          Fseek obtains a new position, measured in characters from
          the beginning of the file, by adding offset to the position

     Page 3                       Plan 9             (printed 3/19/24)

     FOPEN(2)                                                 FOPEN(2)

          specified by whence: the beginning of the file if whence is
          SEEK_SET; the current value of the file position indicator
          for SEEK_CUR; and the end-of-file for SEEK_END.  Rewind sets
          the file position indicator to the beginning of the file.

          An integer constant EOF is returned upon end of file or
          error by integer-valued functions that deal with streams.
          Feof returns non-zero if and only if f is at its end of
          file.

          Ferror returns non-zero if and only if f is in the error
          state.  It can get into the error state if a system call
          failed on the associated file or a memory allocation failed.
          Clearerr takes a stream out of the error state.

     SOURCE
          /sys/src/libstdio

     SEE ALSO
          fprintf(2), fscanf(2), fgetc(2)
          open(2), read(2)

     DIAGNOSTICS
          The value EOF is returned uniformly to indicate that a FILE
          pointer has not been initialized with fopen, input (output)
          has been attempted on an output (input) stream, or a FILE
          pointer designates corrupt or otherwise unintelligible FILE
          data.
          Some of these functions set errstr.

     BUGS
          Buffering of output can prevent output data from being seen
          until long after it is computed - perhaps never, as when an
          abort occurs between buffer filling and flushing.
          Buffering of input can cause a process to consume more input
          than it actually uses.  This can cause trouble across
          exec(2).
          Buffering may delay the receipt of a write error until a
          subsequent stdio writing, seeking, or file-closing call.
          ANSI says that a file can be fully buffered only if the file
          is not attached to an interactive device.  In Plan 9 all are
          fully buffered except standard error.

          Fdopen, fileno, sopenr, sopenw, and sclose are not ANSI
          Stdio functions.

          Stdio offers no support for runes or UTF characters.  Unless
          external compatibility is necessary, use bio(2), which sup-
          ports UTF and is smaller, faster, and simpler than Stdio.

     Page 4                       Plan 9             (printed 3/19/24)