<refentry id="getc">
<refnamediv>
<refname>Getc</refname>
<refname>Getchar</refname>
<refname>Getw</refname>
<refpurpose>return next character to be read from a file</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;stdio.h&gt;
</funcsynopsisinfo>

<funcprototype>
  <funcdef>int <function>getc</function></funcdef>
  <paramdef>FILE *<parameter>fp</parameter></paramdef>
</funcprototype>
<funcprototype>
  <funcdef>int <function>getchar</function></funcdef>
  <void/>
</funcprototype>
<funcprototype>
  <funcdef>int <function>getw</function></funcdef>
  <paramdef>FILE *<parameter>fp</parameter></paramdef>
</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
Getc returns the next character from the file pointed to by
"fp".
</para>
<para>
Getchar is equivalent to "getc(stdin)".
</para>
<para>
Getw returns the next two bytes from the file as an integer.
</para>
<para>
Under OS-9 there is a choice of service requests to use when
reading from a file. "Read()" will get characters up to a
specified number in "raw" mode i.e. no editing will take
place on the input stream and the characters will appear to the
program exactly as in the file. "Readln()", on the other
hand, will honor the various mappings of characters
associated with a Serial Character device such as a terminal
and in any case will return to the caller as soon as a carriage
return is seen on the input.
</para>
<para>
In the vast majority of cases, it is preferable to use
"readln()" for accessing Serial Character devices and "read()"
for any other file input. "Getc()" uses this strategy and, as
all file input using the Standard Library functions is routed
through "getc()", so do all the other input functions. The
choice is made when the first call to "getc()" is made after
the file has been opened. The system is consulted for the
status of the file and a flag bit is set in the file structure
accordingly. The choice may be forced by the programmer by
setting the relevant bit before a call to "getc()". The flag
bits are defined in "&lt;stdio.h&gt;" and "_SCF" and "_RBF" and the
method is as follows: assuming that the file pointer for the
file, as returned by "fopen()" is f,
<programlisting>
         f->_flag |= _SCF;
</programlisting>
will force the use of "readln()" on input and
<programlisting>
         f->_flag |= _RBF;
</programlisting>
will force the use of "read()". This trick may be played on
the standard streams "stdin", "stdout" and "stderr" without the
need for calling "fopen()" but before any input is requested
from the stream.
</para>
</refsect1>

<refsect1><title>Diagnostics</title>
<para>
EOF(-1) is returned for end of file or error.
</para>
</refsect1>

<refsect1><title>See Also</title>
<para>
<link linkend="putc">Putc()</link>,
<link linkend="fread">fread()</link>,
<link linkend="fopen">fopen()</link>,
<link linkend="gets">gets()</link>,
<link linkend="ungetc">ungetc()</link>
</para>
</refsect1>

</refentry>