stdio.texi

一个C源代码分析器

@comment stdio.h
@comment ANSI
@deftypefun int puts (const char *@var{s})
The @code{puts} function writes the string @var{s} to the stream
@code{stdout} followed by a newline.  The terminating null character of
the string is not written.

@code{puts} is the most convenient function for printing simple
messages.  For example:

@smallexample
puts ("This is a message.");
@end smallexample
@end deftypefun

@comment stdio.h
@comment SVID
@deftypefun int putw (int @var{w}, FILE *@var{stream})
This function writes the word @var{w} (that is, an @code{int}) to
@var{stream}.  It is provided for compatibility with SVID, but we
recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
@end deftypefun

@node Character Input
@section Character Input

@cindex reading from a stream, by characters
This section describes functions for performing character- and
line-oriented input.
These functions are declared in the header file @file{stdio.h}.
@pindex stdio.h

@comment stdio.h
@comment ANSI
@deftypefun int fgetc (FILE *@var{stream})
This function reads the next character as an @code{unsigned char} from
the stream @var{stream} and returns its value, converted to an
@code{int}.  If an end-of-file condition or read error occurs,
@code{EOF} is returned instead.
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefun int getc (FILE *@var{stream})
This is just like @code{fgetc}, except that it is permissible (and
typical) for it to be implemented as a macro that evaluates the
@var{stream} argument more than once.  @code{getc} is often highly
optimized, so it is usually the best function to use to read a single
character.
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefun int getchar (void)
The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
as the value of the @var{stream} argument.
@end deftypefun

Here is an example of a function that does input using @code{fgetc}.  It
would work just as well using @code{getc} instead, or using
@code{getchar ()} instead of @w{@code{fgetc (stdin)}}.

@smallexample
int
y_or_n_p (const char *question)
@{
  fputs (question, stdout);
  while (1)
    @{
      int c, answer;
      /* @r{Write a space to separate answer from question.} */
      fputc (' ', stdout);
      /* @r{Read the first character of the line.}
         @r{This should be the answer character, but might not be.} */
      c = tolower (fgetc (stdin));
      answer = c;
      /* @r{Discard rest of input line.} */
      while (c != '\n')
        c = fgetc (stdin);
      /* @r{Obey the answer if it was valid.} */
      if (answer == 'y')
        return 1;
      if (answer == 'n')
        return 0;
      /* @r{Answer was invalid: ask for valid answer.} */
      fputs ("Please answer y or n:", stdout);
    @}
@}
@end smallexample

@comment stdio.h
@comment SVID
@deftypefun int getw (FILE *@var{stream})
This function reads a word (that is, an @code{int}) from @var{stream}.
It's provided for compatibility with SVID.  We recommend you use
@code{fread} instead (@pxref{Block Input/Output}).
@end deftypefun

@node Line Input
@section Line-Oriented Input

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.

Standard C has functions to do this, but they aren't very safe: null
characters and even (for @code{gets}) long lines can confuse them.  So
the GNU library provides the nonstandard @code{getline} function that
makes it easy to read lines reliably.

Another GNU extension, @code{getdelim}, generalizes @code{getline}.  It
reads a delimited record, defined as everything through the next
occurrence of a specified delimiter character.

All these functions are declared in @file{stdio.h}.

@comment stdio.h
@comment GNU
@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
This function reads an entire line from @var{stream}, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in @code{*@var{lineptr}}.

Before calling @code{getline}, you should place in @code{*@var{lineptr}}
the address of a buffer @code{*@var{n}} bytes long, allocated with
@code{malloc}.  If this buffer is long enough to hold the line,
@code{getline} stores the line in this buffer.  Otherwise,
@code{getline} makes the buffer bigger using @code{realloc}, storing the
new buffer address back in @code{*@var{lineptr}} and the increased size
back in @code{*@var{n}}.
@xref{Unconstrained Allocation}.

If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
to zero, before the call, then @code{getline} allocates the initial
buffer for you by calling @code{malloc}.

In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
a @code{char *} which points to the text of the line.

When @code{getline} 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.

This function is a GNU extension, but it is the recommended way to read
lines from a stream.  The alternative standard functions are unreliable.

If an error occurs or end of file is reached, @code{getline} returns
@code{-1}.
@end deftypefun

@comment stdio.h
@comment GNU
@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
This function is like @code{getline} except that the character which
tells it to stop reading is not necessarily newline.  The argument
@var{delimiter} specifies the delimiter character; @code{getdelim} keeps
reading until it sees that character (or end of file).

The text is stored in @var{lineptr}, including the delimiter character
and a terminating null.  Like @code{getline}, @code{getdelim} makes
@var{lineptr} bigger if it isn't big enough.

@code{getline} is in fact implemented in terms of @code{getdelim}, just
like this:

@smallexample
ssize_t
getline (char **lineptr, size_t *n, FILE *stream)
@{
  return getdelim (lineptr, n, '\n', stream);
@}
@end smallexample
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
The @code{fgets} function reads characters from the stream @var{stream}
up to and including a newline character and stores them in the string
@var{s}, adding a null character to mark the end of the string.  You
must supply @var{count} characters worth of space in @var{s}, but the
number of characters read is at most @var{count} @minus{} 1.  The extra
character space is used to hold the null character at the end of the
string.

If the system is already at end of file when you call @code{fgets}, then
the contents of the array @var{s} 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}.

@strong{Warning:}  If the input data has a null character, you can't tell.
So don't use @code{fgets} 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} instead of @code{fgets}.
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefn {Deprecated function} {char *} gets (char *@var{s})
The function @code{gets} reads characters from the stream @code{stdin}
up to the next newline character, and stores them in the string @var{s}.
The newline character is discarded (note that this differs from the
behavior of @code{fgets}, which copies the newline character into the
string).  If @code{gets} encounters a read error or end-of-file, it
returns a null pointer; otherwise it returns @var{s}.

@strong{Warning:} The @code{gets} function is @strong{very dangerous}
because it provides no protection against overflowing the string
@var{s}.  The GNU library includes it for compatibility only.  You
should @strong{always} use @code{fgets} or @code{getline} instead.  To
remind you of this, the linker (if using GNU @code{ld}) will issue a
warning whenever you use @code{gets}.
@end deftypefn

@node Unreading
@section Unreading
@cindex peeking at input
@cindex unreading characters
@cindex pushing input back

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.

Using stream I/O, you can peek ahead at input by first reading it and
then @dfn{unreading} it (also called  @dfn{pushing it back} on the stream).  
Unreading a character makes it available to be input again from the stream,
by  the next call to @code{fgetc} or other input function on that stream.

@menu
* Unreading Idea::              An explanation of unreading with pictures.
* How Unread::                  How to call @code{ungetc} to do unreading.
@end menu

@node Unreading Idea
@subsection What Unreading Means

Here is a pictorial explanation of unreading.  Suppose you have a
stream reading a file that contains just six characters, the letters
@samp{foobar}.  Suppose you have read three characters so far.  The
situation looks like this:

@smallexample
f  o  o  b  a  r
         ^
@end smallexample

@noindent
so the next input character will be @samp{b}.

@c @group   Invalid outside @example
If instead of reading @samp{b} you unread the letter @samp{o}, you get a
situation like this:

@smallexample
f  o  o  b  a  r
         |
      o--
      ^
@end smallexample

@noindent
so that the next input characters will be @samp{o} and @samp{b}.
@c @end group

@c @group
If you unread @samp{9} instead of @samp{o}, you get this situation:

@smallexample
f  o  o  b  a  r
         |
      9--
      ^
@end smallexample

@noindent
so that the next input characters will be @samp{9} and @samp{b}.
@c @end group

@node How Unread
@subsection Using @code{ungetc} To Do Unreading
 
The function to unread a character is called @code{ungetc}, because it
reverses the action of @code{getc}.

@comment stdio.h
@comment ANSI
@deftypefun int ungetc (int @var{c}, FILE *@var{stream})
The @code{ungetc} function pushes back the character @var{c} onto the
input stream @var{stream}.  So the next input from @var{stream} will
read @var{c} before anything else.

If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
@code{EOF}.  This lets you call @code{ungetc} with the return value of
@code{getc} without needing to check for an error from @code{getc}.

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}!  But that is a strange way to write
a program; usually @code{ungetc} is used only to unread a character
that was just read from the same stream.

The GNU C library only supports one character of pushback---in other
words, it does not work to call @code{ungetc} twice without doing input
in between.  Other systems might let you push back multiple characters;
then reading from the stream retrieves the characters in the reverse
order that they were pushed.

Pushing back characters doesn't alter the file; only the internal
buffering for the stream is affected.  If a file positioning function
(such as @code{fseek} or @code{rewind}; @pxref{File Positioning}) is
called, any pending pushed-back characters are discarded.

Unreading a character on a stream that is at end of file clears the
end-of-file indicator for the stream, because it makes the character of
input available.  After you read that character, trying to read again
will encounter end of file.
@end deftypefun

Here is an example showing the use of @code{getc} and @code{ungetc} to
skip over whitespace characters.  When this function reaches a
non-whitespace character, it unreads that character to be seen again on
the next read operation on the stream.

@smallexample
#include <stdio.h>
#include <ctype.h>

void
skip_whitespace (FILE *stream)
@{
  int c;
  do
    /* @r{No need to check for @code{EOF} because it is not}
       @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
    c = getc (stream);
  while (isspace (c));
  ungetc (c, stream);
@}
@end smallexample