<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0057)http://www.acm.uiuc.edu/webmonkeys/book/c_guide/2.12.html -->
<HTML><HEAD><TITLE>C Guide--2.12 stdio.h</TITLE>
<META http-equiv=Content-Type content="text/html; charset=utf-8"><!-- Changed by: eric huss, 12-Mar-1997 -->
<META content="MSHTML 6.00.2900.2963" name=GENERATOR></HEAD>
<BODY text=#000000 bgColor=#ffffff>
<CENTER>
<TABLE width="100%" border=0>
  <TBODY>
  <TR>
    <TD vAlign=top align=left width="20%"><A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/2.11.html"><IMG 
      src="stdio_files/left.gif" border=0> Previous Section<BR>2.11 
    stddef.h</A></TD>
    <TD vAlign=top align=middle width="60%">| <A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/index.html">Table of 
      Contents</A> | <A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/index2.html">Index</A> 
      |</TD>
    <TD vAlign=top align=right width="20%"><A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/2.13.html">Next 
      Section <IMG src="stdio_files/right.gif" border=0><BR>2.13 
  stdlib.h</A></TD></TR></TBODY></TABLE></CENTER>
<HR>

<H1>2.12 stdio.h</H1>
<P>The stdio header provides functions for performing input and output. 
<P>Macros: 
<BLOCKQUOTE><B><CODE>NULL<BR>_IOFBF<BR>_IOLBF<BR>_IONBF<BR>BUFSIZ<BR>EOF<BR>FOPEN_MAX<BR>FILENAME_MAX<BR>L_tmpnam<BR>SEEK_CUR<BR>SEEK_END<BR>SEEK_SET<BR>TMP_MAX<BR>stderr<BR>stdin<BR>stdout<BR></CODE></B></BLOCKQUOTE>
<P>Functions: 
<BLOCKQUOTE><B><CODE>clearerr();<BR>fclose();<BR>feof();<BR>ferror();<BR>fflush();<BR>fgetpos();<BR>fopen();<BR>fread();<BR>freopen();<BR>fseek();<BR>fsetpos();<BR>ftell();<BR>fwrite();<BR>remove();<BR>rename();<BR>rewind();<BR>setbuf();<BR>setvbuf();<BR>tmpfile();<BR>tmpnam();<BR>fprintf();<BR>fscanf();<BR>printf();<BR>scanf();<BR>sprintf();<BR>sscanf();<BR>vfprintf();<BR>vprintf();<BR>vsprintf();<BR>fgetc();<BR>fgets();<BR>fputc();<BR>fputs();<BR>getc();<BR>getchar();<BR>gets();<BR>putc();<BR>putchar();<BR>puts();<BR>ungetc(); 
  <BR>perror(); <BR></CODE></B></BLOCKQUOTE>Variables: 
<BLOCKQUOTE><B><CODE>typedef size_t<BR>typedef FILE<BR>typedef 
  fpos_t<BR></CODE></B></BLOCKQUOTE><A name=variables></A>
<H2>2.12.1 Variables and Definitions</H2>
<P>
<BLOCKQUOTE><CODE><B>size_t</B></CODE> is the unsigned integer result of the 
  sizeof keyword.<BR><CODE><B>FILE</B></CODE> is a type suitable for storing 
  information for a file stream.<BR><CODE><B>fpos_t</B></CODE> is a type 
  suitable for storing any position in a file.<BR><BR><CODE><B>NULL</B></CODE> 
  is the value of a null pointer constant.<BR><CODE><B>_IOFBF</B></CODE>, 
  <CODE><B>_IOLBF</B></CODE>, and <CODE><B>_IONBF</B></CODE> are used in the 
  setvbuf function.<BR><CODE><B>BUFSIZ</B></CODE> is an integer which represents 
  the size of the buffer used by the setbuf function.<BR><CODE><B>EOF</B></CODE> 
  is a negative integer which indicates an end-of-file has been 
  reached.<BR><CODE><B>FOPEN_MAX</B></CODE> is an integer which represents the 
  maximum number of files that the system can guarantee that can be opened 
  simultaneously.<BR><CODE><B>FILENAME_MAX</B></CODE> is an integer which 
  represents the longest length of a char array suitable for holding the longest 
  possible filename. If the implementation imposes no limit, then this value 
  should be the recommended maximum value.<BR><CODE><B>L_tmpnam</B></CODE> is an 
  integer which represents the longest length of a char array suitable for 
  holding the longest possible temporary filename created by the tmpnam 
  function. <BR><CODE><B>SEEK_CUR</B></CODE>, <CODE><B>SEEK_END</B></CODE>, and 
  <CODE><B>SEEK_SET </B></CODE>are used in the fseek 
  function.<BR><CODE><B>TMP_MAX</B></CODE> is the maximum number of unique 
  filenames that the function tmpnam can 
  generate.<BR><CODE><B>stderr</B></CODE>, <CODE><B>stdin</B></CODE>, and 
  <CODE><B>stdout</B></CODE> are pointers to <CODE><B>FILE</B></CODE> types 
  which correspond to the standard error, standard input, and standard output 
  streams.<BR></BLOCKQUOTE><A name=streams></A>
<H2>2.12.2 Streams and Files</H2>
<P>Streams facilitate a way to create a level of abstraction between the program 
and an input/output device. This allows a common method of sending and receiving 
data amongst the various types of devices available. There are two types of 
streams: text and binary. 
<P>Text streams are composed of lines. Each line has zero or more characters and 
are terminated by a new-line character which is the last character in a line. 
Conversions may occur on text streams during input and output. Text streams 
consist of only printable characters, the tab character, and the new-line 
character. Spaces cannot appear before a newline character, although it is 
implementation-defined whether or not reading a text stream removes these 
spaces. An implementation must support lines of up to at least 254 characters 
including the new-line character. 
<P>Binary streams input and output data in an exactly 1:1 ratio. No conversion 
exists and all characters may be transferred. 
<P>When a program begins, there are already three available streams: standard 
input, standard output, and standard error. 
<P>Files are associated with streams and must be opened to be used. The point of 
I/O within a file is determined by the file position. When a file is opened, the 
file position points to the beginning of the file unless the file is opened for 
an append operation in which case the position points to the end of the file. 
The file position follows read and write operations to indicate where the next 
operation will occur. 
<P>When a file is closed, no more actions can be taken on it until it is opened 
again. Exiting from the main function causes all open files to be closed. 
<H2>2.12.3 File Functions</H2><A name=clearerr></A>
<H2>2.12.3.1 clearerr</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>void clearerr(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Clears the end-of-file and error indicators for the 
given stream. As long as the error indicator is set, all stream operations will 
return an error until <OCDE><B>clearerr</B></CODE> or <CODE><B>rewind</B></CODE> 
is called. 
<P><A name=fclose></A>
<H2>2.12.3.2 fclose</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fclose(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Closes the stream. All buffers are flushed. 
<P>If successful, it returns zero. On error it returns <CODE><B>EOF</B></CODE>. 
<A name=feof></A>
<H2>2.12.3.3 feof</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int feof(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Tests the end-of-file indicator for the given stream. If 
the stream is at the end-of-file, then it returns a nonzero value. If it is not 
at the end of the file, then it returns zero. <A name=ferror></A>
<H2>2.12.3.4 ferror</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int ferror(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Tests the error indicator for the given stream. If the 
error indicator is set, then it returns a nonzero value. If the error indicator 
is not set, then it returns zero. <A name=fflush></A>
<H2>2.12.3.5 fflush</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fflush(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Flushes the output buffer of a stream. If stream is a 
null pointer, then all output buffers are flushed. 
<P>If successful, it returns zero. On error it returns <CODE><B>EOF</B></CODE>. 
<A name=fgetpos></A>
<H2>2.12.3.6 fgetpos</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fgetpos(FILE *</B></CODE><I>stream</I><B><CODE>, 
  fpos_t *</B></CODE><I>pos</I><B><CODE>); </B></CODE></BLOCKQUOTE>Gets the 
current file position of the stream and writes it to <I>pos</I>. 
<P>If successful, it returns zero. On error it returns a nonzero value and 
stores the error number in the variable <CODE><B>errno</B></CODE>. <A 
name=fopen></A>
<H2>2.12.3.7 fopen</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>FILE *fopen(const char 
  *</B></CODE><I>filename</I><B><CODE>, const char 
  *</B></CODE><I>mode</I><B><CODE>); </B></CODE></BLOCKQUOTE>
<P>Opens the filename pointed to by filename. The mode argument may be one of 
the following constant strings: 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD><CODE><B>r</B></CODE></TD>
    <TD>read text mode</TD></TR>
  <TR>
    <TD><CODE><B>w</B></CODE></TD>
    <TD>write text mode (truncates file to zero length or creates new 
  file)</TD></TR>
  <TR>
    <TD><CODE><B>a </B></CODE></TD>
    <TD>append text mode for writing (opens or creates file and sets file 
      pointer to the end-of-file)</TD></TR>
  <TR>
    <TD><CODE><B>rb</B></CODE></TD>
    <TD>read binary mode</TD></TR>
  <TR>
    <TD><CODE><B>wb </B></CODE></TD>
    <TD>write binary mode (truncates file to zero length or creates new 
    file)</TD></TR>
  <TR>
    <TD><CODE><B>ab </B></CODE></TD>
    <TD>append binary mode for writing (opens or creates file and sets file 
      pointer to the end-of-file)</TD></TR>
  <TR>
    <TD><CODE><B>r+</B></CODE></TD>
    <TD>read and write text mode</TD></TR>
  <TR>
    <TD><CODE><B>w+</B></CODE></TD>
    <TD>read and write text mode (truncates file to zero length or creates new 
      file)</TD></TR>
  <TR>
    <TD><CODE><B>a+ </B></CODE></TD>
    <TD>read and write text mode (opens or creates file and sets file pointer 
      to the end-of-file)</TD></TR>
  <TR>
    <TD><CODE><B>r+b</B></CODE> or<CODE><B> rb+</B></CODE></TD>
    <TD>read and write binary mode</TD></TR>
  <TR>
    <TD><CODE><B>w+b</B></CODE> or<CODE><B> wb+</B></CODE></TD>
    <TD>read and write binary mode (truncates file to zero length or creates 
      new file)</TD></TR>
  <TR>
    <TD><CODE><B>a+b</B></CODE> or<CODE><B> ab+</B></CODE></TD>
    <TD>read and write binary mode (opens or creates file and sets file 
      pointer to the end-of-file)</TD></TR></TBODY></TABLE>
<P>If the file does not exist and it is opened with read mode 
(<CODE><B>r</B></CODE>), then the open fails. 
<P>If the file is opened with append mode (<CODE><B>a</B></CODE>), then all 
write operations occur at the end of the file regardless of the current file 
position. 
<P>If the file is opened in the update mode (<CODE><B>+</B></CODE>), then output 
cannot be directly followed by input and input cannot be directly followed by 
output without an intervening fseek, fsetpos, rewind, or fflush. 
<P>On success a pointer to the file stream is returned. On failure a null 
pointer is returned. <A name=fread></A>
<H2>2.12.3.8 fread</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>size_t fread(void *</B></CODE><I>ptr</I><B><CODE>, size_t 
  </B></CODE><I>size</I><B><CODE>, size_t</B></CODE><I> nmemb</I><B><CODE>, FILE 
  *</B></CODE><I>stream</I><B><CODE>); </B></CODE></BLOCKQUOTE>Reads data from the 
given stream into the array pointed to by <I>ptr</I>. It reads <I>nmemb</I> 
number of elements of size <I>size</I>. The total number of bytes read is 
(<CODE><B>size*nmemb</B></CODE>). 
<P>On success the number of elements read is returned. On error or end-of-file 
the total number of elements successfully read (which may be zero) is returned. 
<A name=freopen></A>
<H2>2.12.3.9 freopen</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>FILE *freopen(const char 
  *</B></CODE><I>filename</I><B><CODE>, const char 
  *</B></CODE><I>mode</I><B><CODE>, FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Associates a new filename with the given open stream. 
The old file in stream is closed. If an error occurs while closing the file, the 
error is ignored. The mode argument is the same as described in the fopen 
command. Normally used for reassociating stdin, stdout, or stderr. 
<P>On success the pointer to the stream is returned. On error a null pointer is 
returned. <A name=fseek></A>
<H2>2.12.3.10 fseek</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fseek(FILE *</B></CODE><I>stream</I><B><CODE>, long 
  int </B></CODE><I>offset</I><B><CODE>, int</B></CODE><I> whence</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Sets the file position of the stream to the given 
offset. The argument <I>offset</I> signifies the number of bytes to seek from 
the given whence position. The argument <I>whence</I> can be: 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD><CODE><B>SEEK_SET</B></CODE></TD>
    <TD>Seeks from the beginning of the file.</TD></TR>
  <TR>
    <TD><CODE><B>SEEK_CUR</B></CODE></TD>
    <TD>Seeks from the current position.</TD></TR>
  <TR>
    <TD><CODE><B>SEEK_END</B></CODE></TD>
    <TD>Seeks from the end of the file.</TD></TR></TBODY></TABLE>
<P>On a text stream, whence should be <CODE><B>SEEK_SET</B></CODE> and 
<I>offset</I> should be either zero or a value returned from 
<CODE><B>ftell</B></CODE>. 
<P>The end-of-file indicator is reset. The error indicator is NOT reset. 
<P>On success zero is returned. On error a nonzero value is returned. <A 
name=fsetpos></A>
<H2>2.12.3.11 fsetpos</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fsetpos(FILE *</B></CODE><I>stream</I><B><CODE>, 
  const fpos_t *</B></CODE><I>pos</I><B><CODE>); </B></CODE></BLOCKQUOTE>Sets the 
file position of the given stream to the given position. The argument <I>pos</I> 
is a position given by the function <CODE><B>fgetpos</B></CODE>. The end-of-file 
indicator is cleared. 
<P>On success zero is returned. On error a nonzero value is returned and the 
variable <CODE><B>errno</B></CODE> is set. <A name=ftell></A>
<H2>2.12.3.12 ftell</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>long int ftell(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Returns the current file position of the given stream. 
If it is a binary stream, then the value is the number of bytes from the 
beginning of the file. If it is a text stream, then the value is a value useable 
by the fseek function to return the file position to the current position. 
<P>On success the current file position is returned. On error a value of 
<CODE><B>-1L</B></CODE> is returned and <CODE><B>errno</B></CODE> is set. <A 
name=fwrite></A>
<H2>2.12.3.13 fwrite</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>size_t fwrite(const void *</B></CODE><I>ptr</I><B><CODE>, 
  size_t</B></CODE><I> size</I><B><CODE>, size_t</B></CODE><I> 
  nmemb</I><B><CODE>, FILE *</B></CODE><I>stream</I><B><CODE>); 
</B></CODE></BLOCKQUOTE>Writes data from the array pointed to by <I>ptr</I> to 
the given stream. It writes <I>nmemb</I> number of elements of size <I>size</I>. 
The total number of bytes written is (<CODE><B>size*nmemb</B></CODE>). 
<P>On success the number of elements writen is returned. On error the total 
number of elements successfully writen (which may be zero) is returned. <A 
name=remove></A>
<H2>2.12.3.14 remove</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int remove(const char 
  *</B></CODE><I>filename</I><B><CODE>); </B></CODE></BLOCKQUOTE>Deletes the given 
filename so that it is no longer accessible (unlinks the file). If the file is 
currently open, then the result is implementation-defined. 
<P>On success zero is returned. On failure a nonzero value is returned. <A 
name=rename></A>
<H2>2.12.3.15 rename</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int rename(const char 
  *</B></CODE><I>old_filename</I><B><CODE>, const char 
  *</B></CODE><I>new_filename</I><B><CODE>); </B></CODE></BLOCKQUOTE>Causes the 
filename referred to by <I>old_filename</I> to be changed to 
<I>new_filename</I>. If the filename pointed to by <I>new_filename</I> exists, 
the result is implementation-defined. 
<P>On success zero is returned. On error a nonzero value is returned and the 
file is still accessible by its old filename. <A name=rewind></A>
<H2>2.12.3.16 rewind</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>void rewind(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Sets the file position to the beginning of the file of 
the given stream. The error and end-of-file indicators are reset. <A 
name=setbuf></A>
<H2>2.12.3.17 setbuf</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>void setbuf(FILE *</B></CODE><I>stream</I><B><CODE>, char 
  *</B></CODE><I>buffer</I><B><CODE>); </B></CODE></BLOCKQUOTE>Defines how a 
stream should be buffered. This should be called after the stream has been 
opened but before any operation has been done on the stream. Input and output is 
fully buffered. The default <B><CODE>BUFSIZ</CODE></B> is the size of the 
buffer. The argument <I>buffer</I> points to an array to be used as the buffer. 
If <I>buffer</I> is a null pointer, then the stream is unbuffered. <A 
name=setvbuf></A>
<H2>2.12.3.18 setvbuf</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int setvbuf(FILE *</B></CODE><I>stream</I><B><CODE>, char 
  *</B></CODE><I>buffer</I><B><CODE>, int</B></CODE><I> mode</I><B><CODE>, 
  size_t </B></CODE><I>size</I><B><CODE>); </B></CODE></BLOCKQUOTE>Defines how a 
stream should be buffered. This should be called after the stream has been 
opened but before any operation has been done on the stream. The argument 
<I>mode</I> defines how the stream should be buffered as follows: 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD vAlign=top><CODE><B>_IOFBF</B></CODE></TD>
    <TD>Input and output is fully buffered. If the buffer is empty, an input 
      operation attempts to fill the buffer. On output the buffer will be 
      completely filled before any information is written to the file (or the 
      stream is closed). </TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>_IOLBF</B></CODE></TD>
    <TD>Input and output is line buffered. If the buffer is empty, an input 
      operation attempts to fill the buffer. On output the buffer will be 
      flushed whenever a newline character is written.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>_IONBF</B></CODE></TD>
    <TD>Input and output is not buffered. No buffering is 
  performed.</TD></TR></TBODY></TABLE>
<P>The argument <I>buffer</I> points to an array to be used as the buffer. If 
<I>buffer</I> is a null pointer, then <CODE><B>setvbuf</B></CODE> uses 
<CODE><B>malloc</B></CODE> to create its own buffer. 
<P>The argument <I>size</I> determines the size of the array. 
<P>On success zero is returned. On error a nonzero value is returned. <A 
name=tmpfile></A>
<H2>2.12.3.19 tmpfile</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>FILE *tmpfile(void); </B></CODE></BLOCKQUOTE>Creates a 
temporary file in binary update mode (wb+). The tempfile is removed when the 
program terminates or the stream is closed. 
<P>On success a pointer to a file stream is returned. On error a null pointer is 
returned. <A name=tmpnam></A>
<H2>2.12.3.20 tmpnam</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>char *tmpnam(char *</B></CODE><I>str</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Generates and returns a valid temporary filename which 
does not exist. Up to <CODE><B>TMP_MAX</B></CODE> different filenames can be 
generated. 
<P>If the argument <I>str</I> is a null pointer, then the function returns a 
pointer to a valid filename. If the argument <I>str</I> is a valid pointer to an 
array, then the filename is written to the array and a pointer to the same array 
is returned. The filename may be up to <CODE><B>L_tmpnam</B></CODE> characters 
long. 
<H2>2.12.4 Formatted I/O Functions</H2><A name=fprintf></A><A name=printf></A><A 
name=sprintf></A><A name=vfprintf></A><A name=vprintf></A><A name=vsprintf></A>
<H2>2.12.4.1 ..printf Functions</H2>
<P>Declarations: 
<BLOCKQUOTE><CODE><B>int fprintf(FILE *</B></CODE><I>stream</I><B><CODE>, 
  const char *</B></CODE><I>format</I><B><CODE>, ...);<BR>int printf(const char 
  *</B></CODE><I>format</I><B><CODE>, ...);<BR>int sprintf(char 
  *</B></CODE><I>st</I><B><CODE>r, const char 
  *</B></CODE><I>format</I><B><CODE>, ...);<BR>int vfprintf(FILE 
  *</B></CODE><I>stream</I><B><CODE>, const char 
  *</B></CODE><I>format</I><B><CODE>, va_list 
  </B></CODE><I>arg</I><B><CODE>);<BR>int vprintf(const char 
  *</B></CODE><I>format</I><B><CODE>, va_list</B></CODE><I> 
  arg</I><B><CODE>);<BR>int vsprintf(char *</B></CODE><I>str</I><B><CODE>, const 
  char *</B></CODE><I>format</I><B><CODE>, va_list</B></CODE><I> 
  arg</I><B><CODE>);<BR></B></CODE></BLOCKQUOTE>
<P>The ..printf functions provide a means to output formatted information to a 
stream. 
<P>
<TABLE border=0>
  <TBODY>
  <TR>
    <TD><CODE><B>fprintf</B></CODE></TD>
    <TD>sends formatted output to a stream</TD></TR>
  <TR>
    <TD><CODE><B>printf</B></CODE></TD>
    <TD>sends formatted output to stdout</TD></TR>
  <TR>
    <TD><CODE><B>sprintf</B></CODE></TD>
    <TD>sends formatted output to a string</TD></TR>
  <TR>
    <TD><CODE><B>vfprintf</B></CODE></TD>
    <TD>sends formatted output to a stream using an argument list</TD></TR>
  <TR>
    <TD><CODE><B>vprintf</B></CODE></TD>
    <TD>sends formatted output to stdout using an argument list</TD></TR>
  <TR>
    <TD><CODE><B>vsprintf </B></CODE></TD>
    <TD>sends formatted output to a string using an argument 
list</TD></TR></TBODY></TABLE>
<P>These functions take the format string specified by the <I>format</I> 
argument and apply each following argument to the format specifiers in the 
string in a left to right fashion. Each character in the format string is copied 
to the stream except for conversion characters which specify a format specifier. 

<P>The string commands (<CODE><B>sprintf</B></CODE> and 
<CODE><B>vsprintf</B></CODE>) append a null character to the end of the string. 
This null character is not counted in the character count. 
<P>The argument list commands (<CODE><B>vfprintf</B></CODE>, 
<CODE><B>vprintf</B></CODE>, and <CODE><B>vsprintf</B></CODE>) use an argument 
list which is prepared by <CODE><B>va_start</B></CODE>. These commands do not 
call <CODE><B>va_end</B></CODE> (the caller must call it). 
<P>A conversion specifier begins with the <CODE><B>%</B></CODE> character. After 
the <CODE><B>%</B></CODE> character come the following in this order: 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD>[<B>flags</B>]</TD>
    <TD>Control the conversion (optional).</TD></TR>
  <TR>
    <TD>[<B>width</B>]</TD>
    <TD>Defines the number of characters to print (optional).</TD></TR>
  <TR>
    <TD>[<B>.precision</B>]</TD>
    <TD>Defines the amount of precision to print for a number type 
    (optional).</TD></TR>
  <TR>
    <TD>[<B>modifier</B>]</TD>
    <TD>Overrides the size (type) of the argument (optional).</TD></TR>
  <TR>
    <TD>[<B>type</B>]</TD>
    <TD>The type of conversion to be applied (required).</TD></TR></TBODY></TABLE>
<P><B>Flags</B>:<BR>
<TABLE border=0>
  <TBODY>
  <TR>
    <TD vAlign=top><CODE><B>-</B></CODE></TD>
    <TD>Value is left justified (default is right justified). Overrides the 0 
      flag.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>+</B></CODE></TD>
    <TD>Forces the sign (+ or -) to always be shown. Default is to just show 
      the - sign. Overrides the space flag.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>space</B></CODE></TD>
    <TD>Causes a positive value to display a space for the sign. Negative 
      values still show the - sign.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>#</B></CODE></TD>
    <TD>Alternate form: 
      <TABLE border=0>
        <TBODY>
        <TR>
          <TH>Conversion Character</TH>
          <TH>Result</TH>
        <TR>
        <TR>
          <TD><CODE><B>o</B></CODE></TD>
          <TD>Precision is increased to make the first digit a zero.</TD></TR>
        <TR>
          <TD><CODE><B>X or x </B></CODE></TD>
          <TD>Nonzero value will have 0x or 0X prefixed to it.</TD></TR>
        <TR>
          <TD><CODE><B>E, e, f, g, or G </B></CODE></TD>
          <TD>Result will always have a decimal point.</TD></TR>
        <TR>
          <TD><CODE><B>G or g </B></CODE></TD>
          <TD>Trailing zeros will not be removed.</TD></TR></TBODY></TABLE></TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>0 </B></CODE></TD>
    <TD>For d, i, o, u, x, X, e, E, f, g, and G leading zeros are used to pad 
      the field width instead of spaces. This is useful only with a width 
      specifier. Precision overrides this flag.</TD></TR></TBODY></TABLE>
<P><B>Width</B>:<BR>The width of the field is specified here with a decimal 
value. If the value is not large enough to fill the width, then the rest of the 
field is padded with spaces (unless the 0 flag is specified). If the value 
overflows the width of the field, then the field is expanded to fit the value. 
If a <CODE><B>*</B></CODE> is used in place of the width specifer, then the next 
argument (which must be an <CODE><B>int</B></CODE> type) specifies the width of 
the field. Note: when using the <CODE><B>*</B></CODE> with the width and/or 
precision specifier, the width argument comes first, then the precision 
argument, then the value to be converted. 
<P><B>Precision</B>:<BR>The precision begins with a dot (.) to distinguish 
itself from the width specifier. The precision can be given as a decimal value 
or as an asterisk (<CODE><B>*</B></CODE>). If a <CODE><B>*</B></CODE> is used, 
then the next argument (which is an <CODE><B>int</B></CODE> type) specifies the 
precision. Note: when using the <CODE><B>*</B></CODE> with the width and/or 
precision specifier, the width argument comes first, then the precision 
argument, then the value to be converted. Precision does not affect the c type. 
<TABLE border=0>
  <TBODY>
  <TR>
    <TH>[.precision]</TH>
    <TH>Result</TH></TR>
  <TR>
    <TD vAlign=top>(<I>none</I>)</TD>
    <TD>Default precision values:<BR>1 for <CODE><B>d</B></CODE>, 
      <CODE><B>i</B></CODE>, <CODE><B>o</B></CODE>, <CODE><B>u</B></CODE>, 
      <CODE><B>x</B></CODE>, <CODE><B>X</B></CODE> types. The minimum number of 
      digits to appear.<BR>6 for <CODE><B>f</B></CODE>, <CODE><B>e</B></CODE>, 
      <CODE><B>E</B></CODE> types. Specifies the number of digits after the 
      decimal point.<BR>For <CODE><B>g</B></CODE> or <CODE><B>G</B></CODE> types 
      all significant digits are shown.<BR>For <CODE><B>s</B></CODE> type all 
      characters in string are print up to but not including the null 
    character.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>.</B></CODE> <I>or</I> <CODE><B>.0</B></CODE></TD>
    <TD>For <CODE><B>d</B></CODE>, <CODE><B>i</B></CODE>, 
      <CODE><B>o</B></CODE>, <CODE><B>u</B></CODE>, <CODE><B>x</B></CODE>, 
      <CODE><B>X</B></CODE> types the default precis ion value is used unless 
      the value is zero in which case no characters are printed.<BR>For 
      <CODE><B>f</B></CODE>, <CODE><B>e</B></CODE>, <CODE><B>E</B></CODE> types 
      no decimal point character or digits are printed.<BR>For 
      <CODE><B>g</B></CODE> or <CODE><B>G</B></CODE> types the precision is 
      assumed to be 1.<BR></TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>.</B></CODE><I>n</I> </TD>
    <TD>For <CODE><B>d</B></CODE>, <CODE><B>i</B></CODE>, 
      <CODE><B>o</B></CODE>, <CODE><B>u</B></CODE>, <CODE><B>x</B></CODE>, 
      <CODE><B>X</B></CODE> types then at least n digits are printed (padding 
      with zeros if necessary).<BR>For <CODE><B>f</B></CODE>, 
      <CODE><B>e</B></CODE>, <CODE><B>E</B></CODE> types specifies the number of 
      digits after the decimal point.<BR>For <CODE><B>g</B></CODE> or 
      <CODE><B>G</B></CODE> types specifies the number of significant digits to 
      print.<BR>For<CODE><B> s</B></CODE> type specifies the maximum number of 
      characters to print.<BR></TD></TR></TBODY></TABLE>
<P><B>Modifier</B>:<BR>A modifier changes the way a conversion specifier type is 
interpreted. 
<TABLE broder="0">
  <TBODY>
  <TR>
    <TD><B>[modifier]</B></TD>
    <TD><B>[type]</B></TD>
    <TD><B>Effect</B></TD></TR>
  <TR>
    <TD><CODE><B>h</B></CODE></TD>
    <TD><CODE><B>d</B></CODE>, <CODE><B>i</B></CODE>, <CODE><B>o</B></CODE>, 
      <CODE><B>u</B></CODE>, <CODE><B>x</B></CODE>, <CODE><B>X</B></CODE></TD>
    <TD>Value is first converted to a short int or unsigned short i nt.</TD></TR>
  <TR>
    <TD><CODE><B>h</B></CODE></TD>
    <TD><CODE><B>n</B></CODE> </TD>
    <TD>Specifies that the pointer points to a short int.</TD></TR>
  <TR>
    <TD><CODE><B>l</B></CODE></TD>
    <TD><CODE><B>d</B></CODE>, <CODE><B>i</B></CODE>, <CODE><B>o</B></CODE>, 
      <CODE><B>u</B></CODE>, <CODE><B>x</B></CODE>, <CODE><B>X</B></CODE> </TD>
    <TD>Value is first converted to a long int or unsigned long int .</TD></TR>
  <TR>
    <TD><CODE><B>l</B></CODE></TD>
    <TD><CODE><B>n</B></CODE></TD>
    <TD>Specifies that the pointer points to a long int.</TD></TR>
  <TR>
    <TD><CODE><B>L</B></CODE></TD>
    <TD><CODE><B>e</B></CODE>, <CODE><B>E</B></CODE>, <CODE><B>f</B></CODE>, 
      <CODE><B>g</B></CODE>, <CODE><B>G</B></CODE></TD>
    <TD>Value is first converted to a long double.</TD></TR></TBODY></TABLE>
<P><B>Conversion specifier type</B>:<BR>The conversion specifier specifies what 
type the argument is to be treated as. 
<TABLE border=0>
  <TBODY>
  <TR>
    <TH>[type] </TH>
    <TH>Output</TH></TR>
  <TR>
    <TD vAlign=top><CODE><B>d</B></CODE>, <CODE><B>i</B></CODE></TD>
    <TD>Type <CODE><B>signed int</B></CODE>.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>o</B></CODE></TD>
    <TD>Type <CODE><B>unsigned int</B></CODE> printed in octal.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>u</B></CODE> </TD>
    <TD>Type <CODE><B>unsigned int</B></CODE> printed in decimal.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>x</B></CODE> </TD>
    <TD>Type <CODE><B>unsigned int</B></CODE> printed in hexadecimal as dddd 
      using a, b, c, d, e, f.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>X</B></CODE> </TD>
    <TD>Type <CODE><B>unsigned int</B></CODE> printed in hexadecimal as dddd 
      using A, B, C, D, E, F.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>f</B></CODE> </TD>
    <TD>Type <CODE><B>double</B></CODE> printed as [-]ddd.ddd.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>e</B></CODE>, <CODE><B>E</B></CODE> </TD>
    <TD>Type <CODE><B>double</B></CODE> printed as [-]d.ddde񤤠where there is 
      one digit printed before the decimal (zero only if the value is zero). The 
      exponent contains at least two digits. If type is E then the exponent is 
      printed with a capital E.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>g</B></CODE>, <CODE><B>G</B></CODE> </TD>
    <TD>Type <CODE><B>double</B></CODE> printed as type e or E if the exponent 
      is less than -4 or greater than or equal to the precision. Otherwise 
      printed as type f. Trailing zeros are removed. Decimal point character 
      appears only if there is a nonzero decimal digit.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>c</B></CODE></TD>
    <TD>Type <CODE><B>char</B></CODE>. Single character is printed.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>s</B></CODE></TD>
    <TD>Type pointer to array. String is printed according to precision (no 
      precision prints entire string).</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>p</B></CODE> </TD>
    <TD>Prints the value of a pointer (the memory location it holds).</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>n</B></CODE> </TD>
    <TD>The argument must be a pointer to an <CODE><B>int</B></CODE>. Stores 
      the number of characters printed thus far in the int. No characters are 
      printed.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>%</B></CODE> </TD>
    <TD>A <CODE><B>%</B></CODE> sign is printed.</TD></TR></TBODY></TABLE>
<P>The number of characters printed are returned. If an error occurred, -1 is 
returned. <A name=fscanf></A><A name=scanf></A><A name=sscanf></A>
<H2>2.12.4.2 ..scanf Functions</H2>
<P>Declarations: 
<BLOCKQUOTE><CODE><B>int fscanf(FILE *</B></CODE><I>stream</I><B><CODE>, const 
  char *</B></CODE><I>format</I><B><CODE>, ...);<BR>int scanf(const char 
  *</B></CODE><I>format</I><B><CODE>, ...);<BR>int sscanf(const char 
  *</B></CODE><I>str</I><B><CODE>, const char 
  *</B></CODE><I>format</I><B><CODE>, ...);<BR></B></CODE></BLOCKQUOTE>
<P>The ..scanf functions provide a means to input formatted information from a 
stream. 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD><CODE><B>fscanf</B></CODE></TD>
    <TD>reads formatted input from a stream</TD></TR>
  <TR>
    <TD><CODE><B>scanf</B></CODE></TD>
    <TD>reads formatted input from stdin</TD></TR>
  <TR>
    <TD><CODE><B>sscanf</B></CODE></TD>
    <TD>reads formatted input from a string</TD></TR></TBODY></TABLE>
<P>These functions take input in a manner that is specified by the format 
argument and store each input field into the following arguments in a left to 
right fashion. 
<P>Each input field is specified in the format string with a conversion 
specifier which specifies how the input is to be stored in the appropriate 
variable. Other characters in the format string specify characters that must be 
matched from the input, but are not stored in any of the following arguments. If 
the input does not match then the function stops scanning and returns. A 
whitespace character may match with any whitespace character (space, tab, 
carriage return, new line, vertical tab, or formfeed) or the next incompatible 
character. 
<P>An input field is specified with a conversion specifer which begins with the 
<CODE><B>%</B></CODE> character. After the <CODE><B>%</B></CODE> character come 
the following in this order: 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD><B>[*]</B></TD>
    <TD>Assignment suppressor (optional).</TD></TR>
  <TR>
    <TD><B>[width]</B></TD>
    <TD>Defines the maximum number of characters to read (optional).</TD></TR>
  <TR>
    <TD><B>[modifier]</B></TD>
    <TD>Overrides the size (type) of the argument (optional).</TD></TR>
  <TR>
    <TD><B>[type] </B></TD>
    <TD>The type of conversion to be applied (required).</TD></TR></TBODY></TABLE>
<P><B>Assignment suppressor:</B><BR>Causes the input field to be scanned but not 
stored in a variable. 
<P><B>Width:</B><BR>The maximum width of the field is specified here with a 
decimal value. If the input is smaller than the width specifier (i.e. it reaches 
a nonconvertible character), then what was read thus far is converted and stored 
in the variable. 
<P><B>Modifier:</B><BR>A modifier changes the way a conversion specifier type is 
interpreted. 
<TABLE border=0>
  <TBODY>
  <TR>
    <TD><B>[modifier]</B></TD>
    <TD><B>[type]</B></TD>
    <TD><B>Effect</B>
    <TD></TD>
  <TR>
    <TD><B><CODE>h</CODE></B></TD>
    <TD><B><CODE>d</CODE></B>, <B><CODE>i</CODE></B>, <B><CODE>o</CODE></B>, 
      <B><CODE>u</CODE></B>, <B><CODE>x</CODE></B> </TD>
    <TD>The argument is a <B><CODE>short int</CODE></B> or <B><CODE>unsigned 
      short int</CODE></B>.&lt; /td&gt;</TD>
  <TR>
    <TD><B><CODE>h</CODE></B></TD>
    <TD><B><CODE>n</CODE></B> </TD>
    <TD>Specifies that the pointer points to a <B><CODE>short 
    int</CODE></B>.</TD></TR>
  <TR>
    <TD><B><CODE>l</CODE></B></TD>
    <TD><B><CODE>d</CODE></B>, <B><CODE>i</CODE></B>, <B><CODE>o</CODE></B>, 
      <B><CODE>u</CODE></B>, <B><CODE>x</CODE></B> </TD>
    <TD>The argument is a <B><CODE>long int</CODE></B> or <B><CODE>unsigned 
      long int</CODE> </B>.</TD></TR>
  <TR>
    <TD><B><CODE>l</CODE></B></TD>
    <TD><B><CODE>n</CODE></B> </TD>
    <TD>Specifies that the pointer points to a <B><CODE>long 
  int</CODE></B>.</TD></TR>
  <TR>
    <TD><B><CODE>l</CODE></B></TD>
    <TD><B><CODE>e</CODE></B>, <B><CODE>f</CODE></B>, <B><CODE>g</CODE></B> 
</TD>
    <TD>The argument is a <B><CODE>double</CODE></B>.</TD></TR>
  <TR>
    <TD><B><CODE>L</CODE></B></TD>
    <TD><B><CODE>e</CODE></B>, <B><CODE>f</CODE></B>, <B><CODE>g</CODE></B> 
</TD>
    <TD>The argument is a <B><CODE>long double</CODE></B>.</TD></TR></TBODY></TABLE>
<P><B>Conversion specifier type:</B><BR>The conversion specifier specifies what 
type the argument is. It also controls what a valid convertible character is 
(what kind of characters it can read so it can convert to something compatible). 

<TABLE border=0>
  <TBODY>
  <TR>
    <TD><B>[type]</B></TD>
    <TD><B>Input</B></TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>d</B></CODE></TD>
    <TD>Type <CODE><B>signed int</B></CODE> represented in base 10. Digits 0 
      through 9 and the sign (+ or -).</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>i</B></CODE></TD>
    <TD>Type <CODE><B>signed int</B></CODE>. The base (radix) is dependent on 
      the first two characters. If the first character is a digit from 1 to 9, 
      then it is base 10. If the first digit is a zero and the second digit is a 
      digit from 1 to 7, then it is base 8 (octal). If the first digit is a zero 
      and the second character is an x or X, then it is base 16 
  (hexadecimal).</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>o</B></CODE></TD>
    <TD>Type <CODE><B>unsigned int</B></CODE>. The input must be in base 8 
      (octal). Digits 0 through 7 only.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>u</B></CODE></TD>
    <TD>Type <CODE><B>unsigned int</B></CODE>. The input must be in base 10 
      (decimal). Digits 0 through 9 only.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>x, X</B></CODE></TD>
    <TD>Type <CODE><B>unsigned int</B></CODE>. The input must be in base 16 
      (hexadecimal). Digits 0 through 9 or A through Z or a through z. The 
      characters 0x or 0X may be optionally prefixed to the value.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>e</B></CODE>, <CODE><B>E</B></CODE>, 
      <CODE><B>f</B></CODE>, <CODE><B>g</B></CODE>,<CODE><B> 
      G</B></CODE></B></CODE></TD>
    <TD>Type <CODE><B>float</B></CODE>. Begins with an optional sign. Then one 
      or more digits, followed by an optional decimal-point and decimal value. 
      Finally ended with an optional signed exponent value designated with an e 
      or E.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>s</B></CODE></TD>
    <TD>Type character array. Inputs a sequence of non-whitespace characters 
      (space, tab, carriage return, new line, vertical tab, or formfeed). The 
      array must be large enough to hold the sequence plus a null character 
      appended to the end.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>[...]</B></CODE></TD>
    <TD>Type character array. Allows a search set of characters. Allows input 
      of only those character encapsulated in the brackets (the scanset). If the 
      first character is a carrot (^), then the scanset is inverted and allows 
      any ASCII character except those specified between the brackets. On some 
      systems a range can be specified with the dash character (-). By 
      specifying the beginning character, a dash, and an ending character a 
      range of characters can be included in the scanset. A null character is 
      appended to the end of the array.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>c</B></CODE></TD>
    <TD>Type character array. Inputs the number of characters specified in the 
      width field. If no width field is specified, then 1 is assumed. No null 
      character is appended to the array.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>p</B></CODE></TD>
    <TD>Pointer to a pointer. Inputs a memory address in the same fashion of 
      the <CODE><B>%p</B></CODE> type produced by the printf function.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>n </B></CODE></TD>
    <TD>The argument must be a pointer to an <CODE><B>int</B></CODE>. Stores 
      the number of characters read thus far in the <CODE><B>int</B></CODE>. No 
      characters are read from the input stream.</TD></TR>
  <TR>
    <TD vAlign=top><CODE><B>% </B></CODE></TD>
    <TD>Requires a matching <CODE><B>%</B></CODE> sign from the 
  input.</TD></TR></TBODY></TABLE>
<P>Reading an input field (designated with a conversion specifier) ends when an 
incompatible character is met, or the width field is satisfied. 
<P>On success the number of input fields converted and stored are returned. If 
an input failure occurred, then EOF is returned. 
<H2>2.12.5 Character I/O Functions</H2><A name=fgetc></A>
<H2>2.12.5.1 fgetc</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fgetc(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Gets the next character (an <CODE><B>unsigned 
char</B></CODE>) from the specified stream and advances the position indicator 
for the stream. 
<P>On success the character is returned. If the end-of-file is encountered, then 
<CODE><B>EOF</B></CODE> is returned and the end-of-file indicator is set. If an 
error occurs then the error indicator for the stream is set and 
<CODE><B>EOF</B></CODE> is returned. <A name=fgets></A>
<H2>2.12.5.2 fgets</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>char *fgets(char *</B></CODE><I>str</I><B><CODE>, int 
  </B></CODE><I>n</I><B><CODE>, FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Reads a line from the specified stream and stores it 
into the string pointed to by <I>str</I>. It stops when either (n-1) characters 
are read, the newline character is read, or the end-of-file is reached, 
whichever comes first. The newline character is copied to the string. A null 
character is appended to the end of the string. 
<P>On success a pointer to the string is returned. On error a null pointer is 
returned. If the end-of-file occurs before any characters have been read, the 
string remains unchanged. <A name=fputc></A>
<H2>2.12.5.3 fputc</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fputc(int</B></CODE><I> char</I><B><CODE>, FILE 
  *</B></CODE><I>stream</I><B><CODE>); </B></CODE></BLOCKQUOTE>Writes a character 
(an <CODE><B>unsigned char</B></CODE>) specified by the argument <I>char</I> to 
the specified stream and advances the position indicator for the stream. 
<P>On success the character is returned. If an error occurs, the error indicator 
for the stream is set and <CODE><B>EOF</B></CODE> is returned. <A 
name=fputs></A>
<H2>2.12.5.4 fputs</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int fputs(const char *</B></CODE><I>str</I><B><CODE>, 
  FILE *</B></CODE><I>stream</I><B><CODE>); </B></CODE></BLOCKQUOTE>Writes a 
string to the specified stream up to but not including the null character. 
<P>On success a nonnegative value is returned. On error <CODE><B>EOF</B></CODE> 
is returned. <A name=getc></A>
<H2>2.12.5.5 getc</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int getc(FILE *</B></CODE><I>stream</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Gets the next character (an <CODE><B>unsigned 
char</B></CODE>) from the specified stream and advances the position indicator 
for the stream. 
<P>This may be a macro version of <CODE><B>fgetc</B></CODE>. 
<P>On success the character is returned. If the end-of-file is encountered, then 
<CODE><B>EOF</B></CODE> is returned and the end-of-file indicator is set. If an 
error occurs then the error indicator for the stream is set and 
<CODE><B>EOF</B></CODE> is returned. <A name=getchar></A>
<H2>2.12.5.6 getchar</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int getchar(void); </B></CODE></BLOCKQUOTE>Gets a character 
(an <CODE><B>unsigned char</B></CODE>) from <CODE><B>stdin</B></CODE>. 
<P>On success the character is returned. If the end-of-file is encountered, then 
<CODE><B>EOF</B></CODE> is returned and the end-of-file indicator is set. If an 
error occurs then the error indicator for the stream is set and 
<CODE><B>EOF</B></CODE> is returned. <A name=gets></A>
<H2>2.12.5.7 gets</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>char *gets(char *</B></CODE><I>str</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Reads a line from <CODE><B>stdin</B></CODE> and stores 
it into the string pointed to by <I>str</I>. It stops when either the newline 
character is read or when the end-of-file is reached, whichever comes first. The 
newline character is not copied to the string. A null character is appended to 
the end of the string. 
<P>On success a pointer to the string is returned. On error a null pointer is 
returned. If the end-of-file occurs before any characters have been read, the 
string remains unchanged. <A name=putc></A>
<H2>2.12.5.8 putc</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int putc(int</B></CODE><I> char</I><B><CODE>, FILE 
  *</B></CODE><I>stream</I><B><CODE>); </B></CODE></BLOCKQUOTE>Writes a character 
(an<CODE><B> unsigned char</B></CODE>) specified by the argument <I>char</I> to 
the specified stream and advances the position indicator for the stream. 
<P>This may be a macro version of<CODE><B> fputc</B></CODE>. 
<P>On success the character is returned. If an error occurs, the error indicator 
for the stream is set and<CODE><B> EOF</B></CODE> is returned. <A 
name=putchar></A>
<H2>2.12.5.9 putchar</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int putchar(int</B></CODE><I> char</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Writes a character (an <CODE><B>unsigned 
char</B></CODE>) specified by the argument <I>char</I> to 
<CODE><B>stdout</B></CODE>. 
<P>On success the character is returned. If an error occurs, the error indicator 
for the stream is set and <CODE><B>EOF</B></CODE> is returned. <A name=puts></A>
<H2>2.12.5.10 puts</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int puts(const char *</B></CODE><I>str</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Writes a string to <CODE><B>stdout</B></CODE> up to but 
not including the null character. A newline character is appended to the output. 

<P>On success a nonnegative value is returned. On error <CODE><B>EOF</B></CODE> 
is returned. <A name=ungetc></A>
<H2>2.12.5.11 ungetc</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>int ungetc(int </B></CODE><I>char</I><B><CODE>, FILE 
  *</B></CODE><I>stream</I><B><CODE>); </B></CODE></BLOCKQUOTE>Pushes the 
character <I>char</I> (an <CODE><B>unsigned char</B></CODE>) onto the specified 
stream so that the this is the next character read. The functions 
<CODE><B>fseek</B></CODE>, <CODE><B>fsetpos</B></CODE>, and 
<CODE><B>rewind</B></CODE> discard any characters pushed onto the stream. 
<P>Multiple characters pushed onto the stream are read in a FIFO manner (first 
in, first out). 
<P>On success the character pushed is returned. On error <CODE><B>EOF</B></CODE> 
is returned. 
<H2>2.12.7 Error Functions</H2><A name=perror></A>
<H2>2.12.7.1 perror</H2>
<P>Declaration: 
<BLOCKQUOTE><CODE><B>void perror(const char *</B></CODE><I>str</I><B><CODE>); 
  </B></CODE></BLOCKQUOTE>Prints a descriptive error message to stderr. First the 
string <I>str</I> is printed followed by a colon then a space. Then an error 
message based on the current setting of the variable <CODE><B>errno</B></CODE> 
is printed. 
<HR>

<CENTER>
<TABLE width="100%" border=0>
  <TBODY>
  <TR>
    <TD vAlign=top align=left width="20%"><A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/2.11.html"><IMG 
      src="stdio_files/left.gif" border=0> Previous Section<BR>2.11 
    stddef.h</A></TD>
    <TD vAlign=top align=middle width="60%">| <A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/index.html">Table of 
      Contents</A> | <A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/index2.html">Index</A> 
      |</TD>
    <TD vAlign=top align=right width="20%"><A 
      href="http://www.acm.uiuc.edu/webmonkeys/book/c_guide/2.13.html">Next 
      Section <IMG src="stdio_files/right.gif" border=0><BR>2.13 
  stdlib.h</A></TD></TR></TBODY></TABLE></CENTER></BODY></HTML>