



Synopsys:
     #include <stdio.h>
     int getchar(void);

     int _getchar_r(struct _reent *REENT);
   
Description:
'getchar' is a macro, defined in stdio.h.  You can use getchar to
get the next single character from the standard input stream.  As a
side effect, getchar advances the standard inputs current position
indicator.

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

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, getchar returns EOF.

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

Portability:
ANSI C requires getchar; it suggests, but does not require, that
getchar be implemented as a macro.

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

 






Description:
'getchar_unlocked' is a non-thread-safe version of getchar declared
in stdio.h.  getchar_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
getchar_unlocked is equivalent to getchar.

Returns:
See getchar.

Portability:
POSIX 1003.1 requires getchar_unlocked.  getchar_unlocked may be
implemented as a macro.

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





Synopsys:
     #include <stdio.h>
     int getdelim(char **BUFPTR, size_t *N,
         int DELIM, FILE *FP);
   
Description:
'getdelim' reads a file FP up to and possibly including a specified
delimeter DELIM.  The line is read into a buffer pointed to by BUFPTR
and designated with size *N.  If the buffer is not large enough, it
will be dynamically grown by getdelim.  As the buffer is grown, the
pointer to the size N will be updated.

Returns:
getdelim returns -1 if no characters were successfully read,
otherwise, it returns the number of bytes successfully read.  at end of
file, the result is nonzero.

Portability:
getdelim is a glibc extension.

   No supporting OS subroutines are directly required.

 





Synopsys:
     #include <stdio.h>
     ssize_t getline(char **BUFPTR, size_t *N, FILE *FP);
   
Description:
'getline' reads a file FP up to and possibly including the newline
character.  The line is read into a buffer pointed to by BUFPTR and
designated with size *N.  If the buffer is not large enough, it will be
dynamically grown by getdelim.  As the buffer is grown, the pointer
to the size N will be updated.

   getline is equivalent to getdelim(bufptr, n, \n, fp);

Returns:
getline returns -1 if no characters were successfully read,
otherwise, it returns the number of bytes successfully read.  at end of
file, the result is nonzero.

Portability:
getline is a glibc extension.

   No supporting OS subroutines are directly required.

 





Synopsys:
     #include <stdio.h>

     char *gets(char *BUF);

     char *_gets_r(struct _reent *REENT, char *BUF);
   
Description:
'gets' reads characters from standard input until a newline is found.  The
characters up to the newline are stored in BUF. The newline is
discarded, and the buffer is terminated with a 0.

   This is a _dangerous_ function, as it has no way of checking the
amount of space available in BUF. One of the attacks used by the
Internet Worm of 1988 used this to overrun a buffer allocated on the
stack of the finger daemon and overwrite the return address, causing
the daemon to execute code downloaded into it over the connection.

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

Returns:
gets 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 end of file occurs with no data in the
buffer, NULL is returned.

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

 





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

   RETURNS The next word (read as an int), unless there is no more
data, or the host system reports a read error; in either of these
situations, getw returns 'EOF'.  Since EOF is a valid int, you
must use ferror or feof to distinguish these situations.

Portability:
getw is a remnant of K&R C, it is not part of any ISO C Standard.
fread should be used instead.  In fact, this implementation of getw
is based upon fread.

   Supporting OS subroutines required: fread.
 





Synopsys:
     #include <stdio.h>
     char *mktemp(char *PATH);
     int mkstemp(char *PATH);

     char *_mktemp_r(struct _reent *REENT, char *PATH);
     int *_mkstemp_r(struct _reent *REENT, char *PATH);
   
Description:
'mktemp' and 'mkstemp' attempt to generate a file name that is not yet
in use for any existing file.  mkstemp creates the file and opens it
for reading and writing; mktemp simply generates the file name.

   You supply a simple pattern for the generated file name, as the
string at PATH.  The pattern should be a valid filename (including path
information if you wish) ending with some number of X characters.
The generated filename will match the leading part of the name you
supply, with the trailing X characters replaced by some combination
of digits and letters.

   The alternate functions '_mktemp_r' and '_mkstemp_r' are reentrant
versions.  The extra argument REENT is a pointer to a reentrancy
structure.

Returns:
mktemp returns the pointer PATH to the modified string representing
an unused filename, unless it could not generate one, or the pattern
you provided is not suitable for a filename; in that case, it returns
NULL.

   mkstemp returns a file descriptor to the newly created file,
unless it could not generate an unused filename, or the pattern you
provided is not suitable for a filename; in that case, it returns -1.

Portability:
ANSI C does not require either mktemp or mkstemp; the System V
Interface Definition requires mktemp as of Issue 2.

   Supporting OS subroutines required: getpid, open, stat.

 





Synopsys:
     #include <stdio.h>
     void perror(char *PREFIX);

     void _perror_r(struct _reent *REENT, char *PREFIX);
   
Description:
Use 'perror' to print (on standard error) an error message
corresponding to the current value of the global variable errno.
Unless you use NULL as the value of the argument PREFIX, the error
message will begin with the string at PREFIX, followed by a colon and a
space (: ). The remainder of the error message is one of the strings
described for strerror.

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

Returns:
perror returns no result.

Portability:
ANSI C requires perror, but the strings issued vary from one
implementation to another.

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

 





Synopsys:
     #include <stdio.h>
     int putc(int CH, FILE *FP);
   
Description:
'putc' is a macro, defined in stdio.h.  putc writes the argument CH
to the file or stream identified by FP, after converting it from an
int to an unsigned char.

   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 advances by
one.

   For a subroutine version of this macro, see fputc.

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

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

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

 






Description:
'putc_unlocked' is a non-thread-safe version of putc declared in
stdio.h.  putc_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
putc_unlocked is equivalent to putc.

Returns:
See putc.

Portability:
POSIX 1003.1 requires putc_unlocked.  putc_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.

 





Synopsys:
     #include <stdio.h>
     int putchar(int CH);

     int _putchar_r(struct _reent *REENT, int CH);
   
Description:
'putchar' is a macro, defined in stdio.h.  putchar writes its
argument to the standard output stream, after converting it from an
int to an unsigned char.

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

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

Portability:
ANSI C requires putchar; it suggests, but does not require, that
putchar be implemented as a macro.

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

 






Description:
'putchar_unlocked' is a non-thread-safe version of putchar declared
in stdio.h.  putchar_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
putchar_unlocked is equivalent to putchar.

Returns:
See putchar.

Portability:
POSIX 1003.1 requires putchar_unlocked.  putchar_unlocked may be
implemented as a macro.

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





Synopsys:
     #include <stdio.h>
     int puts(const char *S);

     int _puts_r(struct _reent *REENT, const char *S);
   
Description:
'puts' writes the string at S (followed by a newline, instead of the
trailing null) to the standard output stream.

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

Returns:
If successful, the result is a nonnegative integer; otherwise, the
result is EOF.

Portability:
ANSI C requires puts, 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>
     int putw(int W, FILE *FP);
   
Description:
'putw' is a function, defined in stdio.h.  You can use putw to
write a word to the file or stream identified by FP.  As a side effect,
putw advances the files current position indicator.

   RETURNS Zero on success, EOF on failure.

Portability:
putw is a remnant of K&R C, it is not part of any ISO C Standard.
fwrite should be used instead.  In fact, this implementation of
putw is based upon fwrite.

   Supporting OS subroutines required: fwrite.

 





Synopsys:
     #include <stdio.h>
     int remove(char *FILENAME);

     int _remove_r(struct _reent *REENT, char *FILENAME);
   
Description:
Use 'remove' to dissolve the association between a particular filename
(the string at FILENAME) and the file it represents.  After calling
remove with a particular filename, you will no longer be able to open
the file by that name.

   In this implementation, you may use remove on an open file without
error; existing file descriptors for the file will continue to access
the files data until the program using them closes the file.

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

Returns:
remove returns 0 if it succeeds, -1 if it fails.

Portability:
ANSI C requires remove, but only specifies that the result on failure
be nonzero.  The behavior of remove when you call it on an open file
may vary among implementations.

   Supporting OS subroutine required: unlink.

 





Synopsys:
     #include <stdio.h>
     int rename(const char *OLD, const char *NEW);

     int _rename_r(struct _reent *REENT,
         const char *OLD, const char *NEW);
   
Description:
Use 'rename' to establish a new name (the string at NEW) for a file now
known by the string at OLD.  After a successful rename, the file is
no longer accessible by the string at OLD.

   If rename fails, the file named *OLD is unaffected.  The
conditions for failure depend on the host operating system.

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

Returns:
The result is either 0 (when successful) or -1 (when the file could
not be renamed).

Portability:
ANSI C requires rename, but only specifies that the result on failure
be nonzero.  The effects of using the name of an existing file as
*NEW may vary from one implementation to another.

   Supporting OS subroutines required: link, unlink, or rename.

 





Synopsys:
     #include <stdio.h>
     void rewind(FILE *FP);
     void _rewind_r(struct _reent *PTR, FILE *FP);
   
Description:
'rewind'/'_rewind_r' returns the file position indicator (if any) for the file or
stream identified by FP to the beginning of the file.  It also clears
any error indicator and flushes any pending output.

Returns:
rewind does not return a result.

Portability:
ANSI C requires rewind.

   No supporting OS subroutines are required.

 





Synopsys:
     #include <stdio.h>
     void setbuf(FILE *FP, char *BUF);
   
Description:
'setbuf' specifies that output to the file or stream identified by FP
should be fully buffered.  All output for this file will go to a buffer
(of size BUFSIZ, specified in stdio.h).  Output will be passed on
to the host system only when the buffer is full, or when an input
operation intervenes.

   You may, if you wish, supply your own buffer by passing a pointer to
it as the argument BUF.  It must have size BUFSIZ.  You can also use
NULL as the value of BUF, to signal that the setbuf function is to
allocate the buffer.

*Warnings*
You may only use setbuf before performing any file operation other
than opening the file.

   If you supply a non-null BUF, you must ensure that the associated
storage continues to be available until you close the stream identified
by FP.

Returns:
setbuf does not return a result.

Portability:
Both ANSI C and the System V Interface Definition (Issue 2) require
setbuf.  However, they differ on the meaning of a NULL buffer
pointer: the SVID issue 2 specification says that a NULL buffer
pointer requests unbuffered output.  For maximum portability, avoid
NULL buffer pointers.

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

 





Synopsys:
     #include <stdio.h>
     void setbuffer(FILE *FP, char *BUF, int SIZE);
   
Description:
'setbuffer' specifies that output to the file or stream identified by
FP should be fully buffered.  All output for this file will go to a
buffer (of size SIZE).  Output will be passed on to the host system
only when the buffer is full, or when an input operation intervenes.

   You may, if you wish, supply your own buffer by passing a pointer to
it as the argument BUF.  It must have size SIZE.  You can also use
NULL as the value of BUF, to signal that the setbuffer function is
to allocate the buffer.

*Warnings*
You may only use setbuffer before performing any file operation other
than opening the file.

   If you supply a non-null BUF, you must ensure that the associated
storage continues to be available until you close the stream identified
by FP.

Returns:
setbuffer does not return a result.

Portability:
This function comes from BSD not ANSI or POSIX.

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

 





Synopsys:
     #include <stdio.h>
     void setlinebuf(FILE *FP);
   
Description:
'setlinebuf' specifies that output to the file or stream identified by
FP should be line buffered.  This causes the file or stream to pass on
output to the host system at every newline, as well as when the buffer
is full, or when an input operation intervenes.

*Warnings*
You may only use setlinebuf before performing any file operation
other than opening the file.

Returns:
setlinebuf returns as per setvbuf.

Portability:
This function comes from BSD not ANSI or POSIX.

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

 





Synopsys:
     #include <stdio.h>
     int setvbuf(FILE *FP, char *BUF,
         int MODE, size_t SIZE);
   
Description:
Use 'setvbuf' to specify what kind of buffering you want for the file
or stream identified by FP, by using one of the following values (from
stdio.h) as the MODE argument:

'_IONBF'
     Do not use a buffer: send output directly to the host system for
     the file or stream identified by FP.

'_IOFBF'
     Use full output buffering: output will be passed on to the host
     system only when the buffer is full, or when an input operation
     intervenes.

'_IOLBF'
     Use line buffering: pass on output to the host system at every
     newline, as well as when the buffer is full, or when an input
     operation intervenes.

   Use the SIZE argument to specify how large a buffer you wish.  You
can supply the buffer itself, if you wish, by passing a pointer to a
suitable area of memory as BUF.  Otherwise, you may pass NULL as the
BUF argument, and setvbuf will allocate the buffer.

*Warnings*
You may only use setvbuf before performing any file operation other
than opening the file.

   If you supply a non-null BUF, you must ensure that the associated
storage continues to be available until you close the stream identified
by FP.

Returns:
A 0 result indicates success, EOF failure (invalid MODE or SIZE can
cause failure).

Portability:
Both ANSI C and the System V Interface Definition (Issue 2) require
setvbuf. However, they differ on the meaning of a NULL buffer
pointer: the SVID issue 2 specification says that a NULL buffer
pointer requests unbuffered output.  For maximum portability, avoid
NULL buffer pointers.

   Both specifications describe the result on failure only as a nonzero
value.

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

 

