library_11.html

Glibc的中文手册

<VAR>stream</VAR>.  The terminating null character is not written.
This function does <EM>not</EM> add a newline character, either.
It outputs only the chars in the string.
<P>
This function returns <CODE>EOF</CODE> if a write error occurs, and otherwise
a non-negative value.
<P>
For example:
<P>
<PRE>
fputs ("Are ", stdout);
fputs ("you ", stdout);
fputs ("hungry?\n", stdout);
</PRE>
<P>
outputs the text <SAMP>`Are you hungry?'</SAMP> followed by a newline.
<P>
<A NAME="IDX462"></A>
<U>Function:</U> int <B>puts</B> <I>(const char *<VAR>s</VAR>)</I><P>
The <CODE>puts</CODE> function writes the string <VAR>s</VAR> to the stream
<CODE>stdout</CODE> followed by a newline.  The terminating null character of
the string is not written.
<P>
<A NAME="IDX463"></A>
<U>Function:</U> int <B>putw</B> <I>(int <VAR>w</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function writes the word <VAR>w</VAR> (that is, an <CODE>int</CODE>) to
<VAR>stream</VAR>.  It is provided for compatibility with SVID, but we
recommend you use <CODE>fwrite</CODE> instead (see section <A HREF="library_11.html#SEC155" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC155">Block Input/Output</A>).
<P>
<H2><A NAME="SEC123" HREF="library_toc.html#SEC123" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC123">Character Input</A></H2>
<A NAME="IDX464"></A>
<P>
This section describes functions for performing character- and
line-oriented input.  Again, there are several variants of these
functions, some of which are considered obsolete stylistically.  It's
suggested that you stick with <CODE>fgetc</CODE>, <CODE>getline</CODE>, and maybe
<CODE>getc</CODE>, <CODE>getchar</CODE> and <CODE>fgets</CODE>.
<P>
These functions are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX465"></A>
<P>
<A NAME="IDX466"></A>
<U>Function:</U> int <B>fgetc</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function reads the next character as an <CODE>unsigned char</CODE> from
the stream <VAR>stream</VAR> and returns its value, converted to an
<CODE>int</CODE>.  If an end-of-file condition or read error occurs,
<CODE>EOF</CODE> is returned instead.
<P>
<A NAME="IDX467"></A>
<U>Function:</U> int <B>getc</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This is just like <CODE>fgetc</CODE>, except that it is permissible (and typical)
for it to be implemented as a macro that evaluates the <VAR>stream</VAR>
argument more than once.
<P>
<A NAME="IDX468"></A>
<U>Function:</U> int <B>getchar</B> <I>(void)</I><P>
The <CODE>getchar</CODE> function is equivalent to <CODE>fgetc</CODE> with <CODE>stdin</CODE>
as the value of the <VAR>stream</VAR> argument.
<P>
Here is an example of a function that does input using <CODE>fgetc</CODE>.  It
would work just as well using <CODE>getc</CODE> instead, or using
<CODE>getchar ()</CODE> instead of <CODE>fgetc (stdin)</CODE>.
<P>
<PRE>
int
y_or_n_p (const char *question)
{
  fputs (question, stdout);
  while (1) {
    int c, answer;
    /* Write a space to separate answer from question. */
    fputc (' ', stdout);
    /* Read the first character of the line.
       This should be the answer character, but might not be. */
    c = tolower (fgetc (stdin));
    answer = c;
    /* Discard rest of input line. */
    while (c != '\n')
      c = fgetc (stdin);
    /* Obey the answer if it was valid. */
    if (answer == 'y')
      return 1;
    if (answer == 'n')
      return 0;
    /* Answer was invalid: ask for valid answer. */
    fputs ("Please answer y or n:", stdout);
  }
}
</PRE>
<P>
<A NAME="IDX469"></A>
<U>Function:</U> int <B>getw</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function reads a word (that is, an <CODE>int</CODE>) from <VAR>stream</VAR>.
It's provided for compatibility with SVID.  We recommend you use
<CODE>fread</CODE> instead (see section <A HREF="library_11.html#SEC155" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC155">Block Input/Output</A>).
<P>
<H2><A NAME="SEC124" HREF="library_toc.html#SEC124" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC124">Line-Oriented Input</A></H2>
<P>
Since many programs interpret input on the basis of lines, it's
convenient to have functions to read a line of text from a stream.
<P>
Standard C has functions to do this, but they aren't very safe: null
characters and even (for <CODE>gets</CODE>) long lines can confuse them.  So
the GNU library provides the nonstandard <CODE>getline</CODE> function that
makes it easy to read lines reliably.
<P>
Another GNU extension, <CODE>getdelim</CODE>, generalizes <CODE>getline</CODE>.  It
reads a delimited record, defined as everything through the next
occurrence of a specified delimeter character.
<P>
All these functions are declared in <TT>`stdio.h'</TT>.
<P>
<A NAME="IDX470"></A>
<U>Function:</U> ssize_t <B>getline</B> <I>(char **<VAR>lineptr</VAR>, size_t *<VAR>n</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function reads an entire line from <VAR>stream</VAR>, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in <CODE>*<VAR>lineptr</VAR></CODE>.
<P>
Before calling <CODE>getline</CODE>, you should place in <CODE>*<VAR>lineptr</VAR></CODE>
the address of a buffer <CODE>*<VAR>n</VAR></CODE> bytes long.  If this buffer is
long enough to hold the line, <CODE>getline</CODE> stores the line in this
buffer.  Otherwise, <CODE>getline</CODE> makes the buffer bigger using
<CODE>realloc</CODE>, storing the new buffer address back in
<CODE>*<VAR>lineptr</VAR></CODE> and the increased size back in <CODE>*<VAR>n</VAR></CODE>.
<P>
In either case, when <CODE>getline</CODE> returns,  <CODE>*<VAR>lineptr</VAR></CODE> is
a <CODE>char *</CODE> which points to the text of the line.
<P>
When <CODE>getline</CODE> is successful, it returns the number of characters
read (including the newline, but not including the terminating null).
This value enables you to distinguish null characters that are part of
the line from the null character inserted as a terminator.
<P>
This function is a GNU extension, but it is the recommended way to read
lines from a stream.  The alternative standard functions are unreliable.
<P>
If an error occurs or end of file is reached, <CODE>getline</CODE> returns
<CODE>-1</CODE>.
<P>
<A NAME="IDX471"></A>
<U>Function:</U> ssize_t <B>getdelim</B> <I>(char **<VAR>lineptr</VAR>, size_t *<VAR>n</VAR>, int <VAR>delimiter</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function is like <CODE>getline</CODE> except that the character which
tells it to stop reading is not necessarily newline.  The argument
<VAR>delimeter</VAR> specifies the delimeter character; <CODE>getdelim</CODE> keeps
reading until it sees that character (or end of file).
<P>
The text is stored in <VAR>lineptr</VAR>, including the delimeter character
and a terminating null.  Like <CODE>getline</CODE>, <CODE>getdelim</CODE> makes
<VAR>lineptr</VAR> bigger if it isn't big enough.
<P>
<A NAME="IDX472"></A>
<U>Function:</U> char * <B>fgets</B> <I>(char *<VAR>s</VAR>, int <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</I><P>
The <CODE>fgets</CODE> function reads characters from the stream <VAR>stream</VAR>
up to and including a newline character and stores them in the string
<VAR>s</VAR>, adding a null character to mark the end of the string.  You
must supply <VAR>count</VAR> characters worth of space in <VAR>s</VAR>, but the
number of characters read is at most <VAR>count</VAR> - 1.  The extra
character space is used to hold the null character at the end of the
string.
<P>
If the system is already at end of file when you call <CODE>fgets</CODE>, then
the contents of the array <VAR>s</VAR> are unchanged and a null pointer is
returned.  A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer <VAR>s</VAR>.
<P>
<STRONG>Warning:</STRONG>  If the input data has a null character, you can't tell.
So don't use <CODE>fgets</CODE> unless you know the data cannot contain a null.
Don't use it to read files edited by the user because, if the user inserts
a null character, you should either handle it properly or print a clear
error message.  We recommend using <CODE>getline</CODE> instead of <CODE>fgets</CODE>.
<P>
<A NAME="IDX473"></A>
<U>Deprecated function:</U> char * <B>gets</B> <I>(char *<VAR>s</VAR>)</I><P>
The function <CODE>gets</CODE> reads characters from the stream <CODE>stdin</CODE>
up to the next newline character, and stores them in the string <VAR>s</VAR>.
The newline character is discarded (note that this differs from the
behavior of <CODE>fgets</CODE>, which copies the newline character into the
string).
<P>
<STRONG>Warning:</STRONG>  The <CODE>gets</CODE> function is <STRONG>very dangerous</STRONG> 
because it provides no protection against overflowing the string <VAR>s</VAR>.
The GNU library includes it for compatibility only.  You should 
<STRONG>always</STRONG> use <CODE>fgets</CODE> or <CODE>getline</CODE> instead.
<P>
<A NAME="IDX474"></A>
<A NAME="IDX475"></A>
<A NAME="IDX476"></A>
<H2><A NAME="SEC125" HREF="library_toc.html#SEC125" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC125">Unreading</A></H2>
<P>
In parser programs it is often useful to examine the next character in
the input stream without removing it from the stream.  This is called
"peeking ahead" at the input because your program gets a glimpse of
the input it will read next.
<P>
Using stream I/O, you can peek ahead at input by first reading it and
then <DFN>unreading</DFN> it (also called  <DFN>pushing it back</DFN> on the stream).  
Unreading a character makes it available to be input again from the stream,
by  the next call to <CODE>fgetc</CODE> or other input function on that stream.
<P>
<H3><A NAME="SEC126" HREF="library_toc.html#SEC126" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC126">What Unreading Means</A></H3>
<P>
Here is a pictorial explanation of unreading.  Suppose you have a
stream reading a file that contains just six characters, the letters
<SAMP>`foobar'</SAMP>.  Suppose you have read three characters so far.  The
situation looks like this:
<P>
<PRE>
f  o  o  b  a  r
         ^
</PRE>
<P>
so the next input character will be <SAMP>`b'</SAMP>.
<P>
If instead of reading <SAMP>`b'</SAMP> you unread the letter <SAMP>`o'</SAMP>, you get a
situation like this:
<P>
<PRE>
f  o  o  b  a  r
         |
      o--
      ^
</PRE>
<P>
so that the next input characters will be <SAMP>`o'</SAMP> and <SAMP>`b'</SAMP>.
<P>
If you unread <SAMP>`9'</SAMP> instead of <SAMP>`o'</SAMP>, you get this situation:
<P>
<PRE>
f  o  o  b  a  r
         |
      9--
      ^
</PRE>
<P>
so that the next input characters will be <SAMP>`9'</SAMP> and <SAMP>`b'</SAMP>.
<P>
<H3><A NAME="SEC127" HREF="library_toc.html#SEC127" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC127">Using <CODE>ungetc</CODE> To Do Unreading</A></H3>
 
The function to unread a character is called <CODE>ungetc</CODE>, because it
reverses the action of <CODE>fgetc</CODE>.
<P>
<A NAME="IDX477"></A>
<U>Function:</U> int <B>ungetc</B> <I>(int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</I><P>
The <CODE>ungetc</CODE> function pushes back the character <VAR>c</VAR> onto the
input stream <VAR>stream</VAR>.  So the next input from <VAR>stream</VAR> will
read <VAR>c</VAR> before anything else.
<P>
The character that you push back doesn't have to be the same as the last
character that was actually read from the stream.  In fact, it isn't
necessary to actually read any characters from the stream before
unreading them with <CODE>ungetc</CODE>!  But that is a strange way to write
a program; usually <CODE>ungetc</CODE> is used only to unread a character
that was just read from the same stream.