


Synopsys:
     #include <stdio.h>
     void clearerr(FILE *FP);
   
Description:
The stdio functions maintain an error indicator with each file
pointer FP, to record whether any read or write errors have occurred on
the associated file or stream.  Similarly, it maintains an end-of-file
indicator to record whether there is no more data in the file.

   Use 'clearerr' to reset both of these indicators.

   See ferror and feof to query the two indicators.

Returns:
clearerr does not return a result.

Portability:
ANSI C requires clearerr.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     int fclose(FILE *FP);
     int _fclose_r(struct _reent *REENT, FILE *FP);
   
Description:
If the file or stream identified by FP is open, 'fclose' closes it,
after first ensuring that any pending data is written (by calling
fflush(FP)).

   The alternate function '_fclose_r' is a reentrant version.  The
extra argument REENT is a pointer to a reentrancy structure.

Returns:
fclose returns 0 if successful (including when FP is NULL or not
an open file); otherwise, it returns 'EOF'.

Portability:
fclose is required by ANSI C.

   Required OS subroutines: close, fstat, isatty, lseek,
read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int fcloseall(void);
     int _fcloseall_r (struct _reent *PTR);
   
Description:
'fcloseall' closes all files in the current reentrancy structs domain.
The function '_fcloseall_r' is the same function, except the reentrancy
struct is passed in as the PTR argument.

   This function is not recommended as it closes all streams, including
the std streams.

Returns:
fclose returns 0 if all closes are successful.  Otherwise, 'EOF' is
returned.

Portability:
fcloseall is a glibc extension.

   Required OS subroutines: close, fstat, isatty, lseek,
read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int feof(FILE *FP);
   
Description:
'feof' tests whether or not the end of the file identified by FP has
been reached.

Returns:
feof returns 0 if the end of file has not yet been reached; if at
end of file, the result is nonzero.

Portability:
feof is required by ANSI C.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     int ferror(FILE *FP);
   
Description:
The stdio functions maintain an error indicator with each file
pointer FP, to record whether any read or write errors have occurred on
the associated file or stream.  Use 'ferror' to query this indicator.

   See clearerr to reset the error indicator.

Returns:
ferror returns 0 if no errors have occurred; it returns a nonzero
value otherwise.

Portability:
ANSI C requires ferror.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     int fflush(FILE *FP);
   
Description:
The stdio output functions can buffer output before delivering it to
the host system, in order to minimize the overhead of system calls.

   Use 'fflush' to deliver any such pending output (for the file or
stream identified by FP) to the host system.

   If FP is NULL, fflush delivers pending output from all open
files.

Returns:
fflush returns 0 unless it encounters a write error; in that
situation, it returns 'EOF'.

Portability:
ANSI C requires fflush.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     int fgetc(FILE *FP);
   
Description:
Use 'fgetc' to get the next single character from the file or stream
identified by FP.  As a side effect, fgetc advances the files
current position indicator.

   For a macro version of this function, see getc.

Returns:
The next character (read as an unsigned char, and cast to int),
unless there is no more data, or the host system reports a read error;
in either of these situations, fgetc returns 'EOF'.

   You can distinguish the two situations that cause an EOF result by
using the ferror and feof functions.

Portability:
ANSI C requires fgetc.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int fgetpos(FILE *FP, fpos_t *POS);
     int _fgetpos_r(struct _reent *PTR, FILE *FP, fpos_t *POS);
   
Description:
Objects of type FILE can have a "position" that records how much of
the file your program has already read.  Many of the stdio functions
depend on this position, and many change it as a side effect.

   You can use 'fgetpos'/'_fgetpos_r' to report on the current position for a file
identified by FP; fgetpos will write a value representing that
position at *POS.  Later, you can use this value with fsetpos to
return the file to this position.

   In the current implementation, fgetpos simply uses a character
count to represent the file position; this is the same number that
would be returned by ftell.

Returns:
fgetpos returns 0 when successful.  If fgetpos fails, the result
is 1.  Failure occurs on streams that do not support positioning; the
global errno indicates this condition with the value 'ESPIPE'.

Portability:
fgetpos is required by the ANSI C standard, but the meaning of the
value it records is not specified beyond requiring that it be
acceptable as an argument to fsetpos.  In particular, other
conforming C implementations may return a different result from ftell
than what fgetpos writes at *POS.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     char *fgets(char *BUF, int N, FILE *FP);
   
Description:
'fgets' reads at most N-1 characters from FP until a newline is found. The
characters including to the newline are stored in BUF. The buffer is
terminated with a 0.

Returns:
fgets returns the buffer passed to it, with the data filled in. If
end of file occurs with some data already accumulated, the data is
returned with no other indication. If no data are read, NULL is
returned instead.

Portability:
fgets should replace all uses of gets. Note however that fgets
returns all of the data, while gets removes the trailing newline
(with no indication that it has done so.)

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int fileno(FILE *FP);
   
Description:
You can use 'fileno' to return the file descriptor identified by FP.

Returns:
fileno returns a non-negative integer when successful.  If FP is not
an open stream, fileno returns -1.

Portability:
fileno is not part of ANSI C.  POSIX requires fileno.

   Supporting OS subroutines required: none.

 





Synopsys:
     #include <stdio.h>
     FILE *fopen(const char *FILE, const char *MODE);

     FILE *_fopen_r(struct _reent *REENT,
         const char *FILE, const char *MODE);
   
Description:
'fopen' initializes the data structures needed to read or write a file.
Specify the files name as the string at FILE, and the kind of access
you need to the file with the string at MODE.

   The alternate function '_fopen_r' is a reentrant version.  The extra
argument REENT is a pointer to a reentrancy structure.

   Three fundamental kinds of access are available: read, write, and
append.  *MODE must begin with one of the three characters r,
w, or a, to select one of these:

r
     Open the file for reading; the operation will fail if the file does
     not exist, or if the host system does not permit you to read it.

w
     Open the file for writing _from the beginning_ of the file:
     effectively, this always creates a new file.  If the file whose
     name you specified already existed, its old contents are discarded.

a
     Open the file for appending data, that is writing from the end of
     file.  When you open a file this way, all data always goes to the
     current end of file; you cannot change this using fseek.

   Some host systems distinguish between "binary" and "text" files.
Such systems may perform data transformations on data written to, or
read from, files opened as "text".  If your system is one of these,
then you can append a b to any of the three modes above, to specify
that you are opening the file as a binary file (the default is to open
the file as a text file).

   rb, then, means "read binary"; wb, "write binary"; and
ab, "append binary".

   To make C programs more portable, the b is accepted on all
systems, whether or not it makes a difference.

   Finally, you might need to both read and write from the same file.
You can also append a + to any of the three modes, to permit this.
(If you want to append both b and +, you can do it in either
order: for example, "rb+" means the same thing as "r+b" when used
as a mode string.)

   Use "r+" (or "rb+") to permit reading and writing anywhere in an
existing file, without discarding any data; "w+" (or "wb+") to
create a new file (or begin by discarding all data from an old one)
that permits reading and writing anywhere in it; and "a+" (or
"ab+") to permit reading anywhere in an existing file, but writing
only at the end.

Returns:
fopen returns a file pointer which you can use for other file
operations, unless the file you requested could not be opened; in that
situation, the result is NULL.  If the reason for failure was an
invalid string at MODE, errno is set to 'EINVAL'.

Portability:
fopen is required by ANSI C.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, open, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     FILE *fdopen(int FD, const char *MODE);
     FILE *_fdopen_r(struct _reent *REENT,
         int FD, const char *MODE);
   
Description:
'fdopen'/'_fdopen_r' produces a file descriptor of type FILE *, from a descriptor
for an already-open file (returned, for example, by the system
subroutine open rather than by fopen).  The MODE argument has the
same meanings as in fopen.

Returns:
File pointer or NULL, as for fopen.

Portability:
fdopen is ANSI.

 





Synopsys:
     #include <stdio.h>
     int fputc(int CH, FILE *FP);
   
Description:
'fputc' converts the argument CH from an int to an unsigned char,
then writes it to the file or stream identified by FP.

   If the file was opened with append mode (or if the stream cannot
support positioning), then the new character goes at the end of the
file or stream.  Otherwise, the new character is written at the current
value of the position indicator, and the position indicator oadvances
by one.

   For a macro version of this function, see putc.

Returns:
If successful, fputc returns its argument CH.  If an error
intervenes, the result is 'EOF'.  You can use ferror(FP) to query
for errors.

Portability:
fputc is required by ANSI C.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int fputs(const char *S, FILE *FP);
   
Description:
'fputs' writes the string at S (but without the trailing null) to the
file or stream identified by FP.

Returns:
If successful, the result is 0; otherwise, the result is 'EOF'.

Portability:
ANSI C requires fputs, but does not specify that the result on
success must be 0; any non-negative value is permitted.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     size_t fread(void *BUF, size_t SIZE, size_t COUNT,
         FILE *FP);
   
Description:
'fread' attempts to copy, from the file or stream identified by FP,
COUNT elements (each of size SIZE) into memory, starting at BUF.
fread may copy fewer elements than COUNT if an error, or end of file,
intervenes.

   fread also advances the file position indicator (if any) for FP by
the number of _characters_ actually read.

Returns:
The result of fread is the number of elements it succeeded in reading.

Portability:
ANSI C requires fread.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     FILE *freopen(const char *FILE, const char *MODE,
         FILE *FP);
     FILE *_freopen_r(struct _reent *PTR, const char *FILE,
         const char *MODE, FILE *FP);
   
Description:
Use 'freopen'/'_freopen_r' variant of fopen if you wish to specify a particular file
descriptor FP (notably stdin, stdout, or stderr) for the file.

   If FP was associated with another file or stream, freopen closes
that other file or stream (but ignores any errors while closing it).

   FILE and MODE are used just as in fopen.

Returns:
If successful, the result is the same as the argument FP.  If the file
cannot be opened as specified, the result is NULL.

Portability:
ANSI C requires freopen.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, open, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int fseek(FILE *FP, long OFFSET, int WHENCE)
     int fseeko(FILE *FP, off_t OFFSET, int WHENCE)
     int _fseek_r(struct _reent *PTR, FILE *FP,
         long OFFSET, int WHENCE)
     int _fseeko_r(struct _reent *PTR, FILE *FP,
         off_t OFFSET, int WHENCE)
   
Description:
Objects of type FILE can have a "position" that records how much of
the file your program has already read.  Many of the stdio functions
depend on this position, and many change it as a side effect.

   You can use 'fseek'/'fseeko' to set the position for the file
identified by FP.  The value of OFFSET determines the new position, in
one of three ways selected by the value of WHENCE (defined as macros in
stdio.h):

   SEEK_SET--OFFSET is the absolute file position (an offset from the
beginning of the file) desired.  OFFSET must be positive.

   SEEK_CUR--OFFSET is relative to the current file position.  OFFSET
can meaningfully be either positive or negative.

   SEEK_END--OFFSET is relative to the current end of file.  OFFSET
can meaningfully be either positive (to increase the size of the file)
or negative.

   See ftell/ftello to determine the current file position.
   
   '_fseek_r'/'_fseeko_r' are the reentrant versions.

Returns:
fseek/fseeko return 0 when successful.  On failure, the result is
EOF.  The reason for failure is indicated in errno: either ESPIPE
(the stream identified by FP doesnt support repositioning) or EINVAL
(invalid file position).

Portability:
ANSI C requires fseek.

   fseeko is defined by the Single Unix specification.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int fsetpos(FILE *FP, const fpos_t *POS);
     int _fsetpos_r(struct _reent *PTR, FILE *FP, l
         const fpos_t *POS);
   
Description:
Objects of type 'FILE' can have a "position" that records how much of
the file your program has already read.  Many of the stdio functions
depend on this position, and many change it as a side effect.

   You can use 'fsetpos'/'_fsetpos_r' to return the file identified by FP to a
previous position *POS (after first recording it with fgetpos).

   See fseek for a similar facility.

Returns:
fgetpos returns 0 when successful.  If fgetpos fails, the result
is 1.  The reason for failure is indicated in errno: either
'ESPIPE' (the stream identified by FP doesnt support repositioning) or
'EINVAL' (invalid file position).

Portability:
ANSI C requires fsetpos, but does not specify the nature of *POS
beyond identifying it as written by fgetpos.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     long ftell(FILE *FP);
     off_t ftello(FILE *FP);
     long _ftell_r(struct _reent *PTR, FILE *FP);
     off_t _ftello_r(struct _reent *PTR, FILE *FP);
   
Description:
Objects of type FILE can have a "position" that records how much of
the file your program has already read.  Many of the stdio functions
depend on this position, and many change it as a side effect.

   The result of 'ftell'/'ftello' is the current position for a file
identified by FP.  If you record this result, you can later use it with
fseek/fseeko to return the file to this position.  The difference
between ftell and ftello is that ftell returns long and
ftello returns 'off_t'.

   In the current implementation, ftell/ftello simply uses a
character count to represent the file position; this is the same number
that would be recorded by fgetpos.

   '_ftell_r' and '_ftello_r' are reentrant versions.
Returns:
ftell/ftello return the file position, if possible.  If they cannot
do this, they return -1L.  Failure occurs on streams that do not
support positioning; the global errno indicates this condition with
the value 'ESPIPE'.

Portability:
ftell is required by the ANSI C standard, but the meaning of its
result (when successful) is not specified beyond requiring that it be
acceptable as an argument to fseek.  In particular, other conforming
C implementations may return a different result from ftell than what
fgetpos records.

   ftello is defined by the Single Unix specification.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     size_t fwrite(const void *BUF, size_t SIZE,
         size_t COUNT, FILE *FP);
   
Description:
'fwrite' attempts to copy, starting from the memory location BUF, COUNT
elements (each of size SIZE) into the file or stream identified by FP.
fwrite may copy fewer elements than COUNT if an error intervenes.

   fwrite also advances the file position indicator (if any) for FP
by the number of _characters_ actually written.

Returns:
If fwrite succeeds in writing all the elements you specify, the
result is the same as the argument COUNT.  In any event, the result is
the number of complete elements that fwrite copied to the file.

Portability:
ANSI C requires fwrite.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 





Synopsys:
     #include <stdio.h>
     int getc(FILE *FP);
   
Description:
'getc' is a macro, defined in stdio.h.  You can use getc to get the
next single character from the file or stream identified by FP.  As a
side effect, getc advances the files current position indicator.

   For a subroutine version of this macro, see fgetc.

Returns:
The next character (read as an unsigned char, and cast to int),
unless there is no more data, or the host system reports a read error;
in either of these situations, getc returns EOF.

   You can distinguish the two situations that cause an 'EOF' result by
using the ferror and feof functions.

Portability:
ANSI C requires getc; it suggests, but does not require, that getc
be implemented as a macro.  The standard explicitly permits macro
implementations of getc to use the argument more than once;
therefore, in a portable program, you should not use an expression with
side effects as the getc argument.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.

 






Description:
'getc_unlocked' is a non-thread-safe version of getc declared in
stdio.h.  getc_unlocked may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile().  These
functions may safely be used in a multi-threaded program if and only if
they are called while the invoking thread owns the ( FILE *) object, as
is the case after a successful call to the flockfile() or
ftrylockfile() functions.  If threads are disabled, then
getc_unlocked is equivalent to getc.

Returns:
See getc.

Portability:
POSIX 1003.1 requires getc_unlocked.  getc_unlocked may be
implemented as a macro, so arguments should not have side-effects.

   Supporting OS subroutines required: close, fstat, isatty,
lseek, read, sbrk, write.
 

