<?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>