glenda.party
term% ls -F
term% pwd
$home/manuals/9front/2/fopen
term% cat index.txt
FOPEN(2)                      System Calls Manual                     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),
       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 descrip‐
       tive 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
       standard 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 identify the stream in subsequent
       operations, or NULL if the open fails.  Mode is a character string hav‐
       ing 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 somewhere 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  auto‐
       matically 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 er‐
       rors in that close.

       Fdopen associates a stream with an open Plan 9 file descriptor.

       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.

       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 exception 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 characters 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 indicator is maintained by the reading and writing func‐
       tions described in fgetc(2).

       Fgetpos stores the current value of the  file  position  indicator  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  posi‐
       tion  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  suc‐
       cess,  nonzero  otherwise.   Fseek  obtains a new position, measured in
       characters from the beginning of the file, by adding offset to the  po‐
       sition  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 posi‐
       tion indicator to the beginning of the file.

       An integer constant EOF is returned upon end of file or error by  inte‐
       ger-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  er‐
       ror 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 oth‐
       erwise 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 at‐
       tached  to an interactive device.  In Plan 9 all are fully buffered ex‐
       cept standard error.

       Fdopen, fileno, sopenr, sopenw, and sclose are  not  ANSI  Stdio  func‐
       tions.

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



                                                                      FOPEN(2)