<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE apiOperation PUBLIC "-//IBM//DTD DITA API Operation Reference Type//EN"
 "../dtd/apiOperation.dtd">
<apiOperation id="gets">
<apiName>gets</apiName>
<shortdesc>fgetc,  fgets,  getc,  getchar,	gets, ungetc - input of characters
and strings.</shortdesc>
<apiOperationDetail>
<apiSyntax>
<apiSyntaxText>#include &lt;stdio.h&gt;

int <apiItemName>fgetc</apiItemName>(FILE *stream);
char *<apiItemName>fgets</apiItemName>(char *s, int size, FILE *stream);
int <apiItemName>getc</apiItemName>(FILE *stream);
int <apiItemName>getchar</apiItemName>(void);
char *<apiItemName>gets</apiItemName>(char *s);
int <apiItemName>ungetc</apiItemName>(int c, FILE *stream);</apiSyntaxText>
<apiSyntaxItem>
<apiItemName>fgetc()</apiItemName>
<apiDefNote>Reads the next character from stream and returns it as an unsigned
char cast to an int, or EOF on end of file or error.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>getc()</apiItemName>
<apiDefNote>Is equivalent to <apioperation>fgetc()</apioperation> except that
it may be implemented as a macro which evaluates stream more than once.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>getchar()</apiItemName>
<apiDefNote>Is equivalent to <apioperation>getc(stdin)</apioperation>.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>gets()</apiItemName>
<apiDefNote>Reads a line from stdin into the buffer pointed to by <codeph>s</codeph> until
either a terminating newline or EOF, which it replaces with '\0'.  No check
for buffer overrun is performed (see BUGS below).</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>fgets()</apiItemName>
<apiDefNote>Reads in at most one less than size characters from stream and
stores them into the buffer pointed to by <codeph>s</codeph>. Reading stops
after an EOF or a newline. If a newline is read, it is stored into the buffer.
A '\0' is stored after the last character in the buffer.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>ungetc()</apiItemName>
<apiDefNote>Pushes <codeph>c</codeph> back to stream, cast to unsigned char,
where it is available for subsequent read operations.   Pushed-back characters
will be returned in reverse order; only one pushback is guaranteed.</apiDefNote>
</apiSyntaxItem>
</apiSyntax>
<apiDesc>Calls to the functions described here can be mixed with each other
and with calls to other input functions from the stdio library for the same
input stream.<p>For non-locking counterparts, see unlocked_stdio(3).</p></apiDesc>
<section><title>Return value</title><sl>
<sli><apioperation>fgetc()</apioperation>, <apioperation>getc()</apioperation> and <apioperation>getchar()</apioperation> return
the character read as an unsigned char cast to an int or EOF on end of file
or error. </sli>
<sli><apioperation>gets()</apioperation> and <apioperation>fgets()</apioperation> return <codeph>s</codeph> on
success, and NULL on error or  when  end of file occurs while no characters
have been read. </sli>
<sli><apioperation>ungetc()</apioperation> returns <codeph>c</codeph> on success,
or EOF on error.</sli>
</sl></section>
<section><title>Conforming to</title>ANSI - C, POSIX.1</section>
<section><title>Bugs</title>Never use <apioperation>gets()</apioperation>.
 Because it is impossible to tell without knowing the data in advance how
many characters <apioperation>gets()</apioperation>  will  read, and because <apioperation>gets()</apioperation> will
continue to store characters past the end of the buffer, it is extremely dangerous
to use.  It has been used to break computer security. Use <apioperation>fgets()</apioperation> instead. <p>It
 is not advisable to mix calls to input functions from the stdio library with
low-level calls to <apioperation>read()</apioperation> for the file descriptor
associated with the input stream; the results will be undefined and very probably
not what you want.</p></section>
</apiOperationDetail>
</apiOperation>