initial import

1 files changed, 3635 insertions, 0 deletions

diff --git a/manual/stdio.texi b/manual/stdio.texi
new file mode 100644
index 0000000000..411d94a242
--- /dev/null
+++ b/manual/stdio.texi
@@ -0,0 +1,3635 @@
+@node I/O on Streams, Low-Level I/O, I/O Overview, Top
+@chapter Input/Output on Streams
+
+This chapter describes the functions for creating streams and performing
+input and output operations on them.  As discussed in @ref{I/O
+Overview}, a stream is a fairly abstract, high-level concept
+representing a communications channel to a file, device, or process.
+
+@menu
+* Streams::                     About the data type representing a stream.
+* Standard Streams::            Streams to the standard input and output 
+                                 devices are created for you.
+* Opening Streams::             How to create a stream to talk to a file.
+* Closing Streams::             Close a stream when you are finished with it.
+* Simple Output::               Unformatted output by characters and lines.
+* Character Input::             Unformatted input by characters and words.
+* Line Input::                  Reading a line or a record from a stream.
+* Unreading::                   Peeking ahead/pushing back input just read.
+* Block Input/Output::          Input and output operations on blocks of data.
+* Formatted Output::            @code{printf} and related functions.
+* Customizing Printf::          You can define new conversion specifiers for
+                                 @code{printf} and friends.
+* Formatted Input::             @code{scanf} and related functions.
+* EOF and Errors::              How you can tell if an I/O error happens.
+* Binary Streams::              Some systems distinguish between text files
+                                 and binary files.
+* File Positioning::            About random-access streams.
+* Portable Positioning::        Random access on peculiar ANSI C systems.
+* Stream Buffering::            How to control buffering of streams.
+* Other Kinds of Streams::      Streams that do not necessarily correspond
+                                 to an open file. 
+@end menu
+
+@node Streams
+@section Streams
+
+For historical reasons, the type of the C data structure that represents
+a stream is called @code{FILE} rather than ``stream''.  Since most of
+the library functions deal with objects of type @code{FILE *}, sometimes
+the term @dfn{file pointer} is also used to mean ``stream''.  This leads
+to unfortunate confusion over terminology in many books on C.  This
+manual, however, is careful to use the terms ``file'' and ``stream''
+only in the technical sense.
+@cindex file pointer
+
+@pindex stdio.h
+The @code{FILE} type is declared in the header file @file{stdio.h}.
+
+@comment stdio.h
+@comment ANSI
+@deftp {Data Type} FILE
+This is the data type used to represent stream objects.  A @code{FILE}
+object holds all of the internal state information about the connection
+to the associated file, including such things as the file position
+indicator and buffering information.  Each stream also has error and
+end-of-file status indicators that can be tested with the @code{ferror}
+and @code{feof} functions; see @ref{EOF and Errors}.
+@end deftp
+
+@code{FILE} objects are allocated and managed internally by the
+input/output library functions.  Don't try to create your own objects of
+type @code{FILE}; let the library do it.  Your programs should
+deal only with pointers to these objects (that is, @code{FILE *} values)
+rather than the objects themselves.
+@c !!! should say that FILE's have "No user-servicable parts inside."
+
+@node Standard Streams
+@section Standard Streams
+@cindex standard streams
+@cindex streams, standard
+
+When the @code{main} function of your program is invoked, it already has
+three predefined streams open and available for use.  These represent
+the ``standard'' input and output channels that have been established
+for the process.
+
+These streams are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ANSI
+@deftypevar {FILE *} stdin
+The @dfn{standard input} stream, which is the normal source of input for the
+program.
+@end deftypevar
+@cindex standard input stream
+
+@comment stdio.h
+@comment ANSI
+@deftypevar {FILE *} stdout
+The @dfn{standard output} stream, which is used for normal output from
+the program.
+@end deftypevar
+@cindex standard output stream
+
+@comment stdio.h
+@comment ANSI
+@deftypevar {FILE *} stderr
+The @dfn{standard error} stream, which is used for error messages and
+diagnostics issued by the program.
+@end deftypevar
+@cindex standard error stream
+
+In the GNU system, you can specify what files or processes correspond to
+these streams using the pipe and redirection facilities provided by the
+shell.  (The primitives shells use to implement these facilities are
+described in @ref{File System Interface}.)  Most other operating systems
+provide similar mechanisms, but the details of how to use them can vary.
+
+In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
+normal variables which you can set just like any others.  For example, to redirect
+the standard output to a file, you could do:
+
+@smallexample
+fclose (stdout);
+stdout = fopen ("standard-output-file", "w");
+@end smallexample
+
+Note however, that in other systems @code{stdin}, @code{stdout}, and
+@code{stderr} are macros that you cannot assign to in the normal way.
+But you can use @code{freopen} to get the effect of closing one and
+reopening it.  @xref{Opening Streams}.
+
+@node Opening Streams
+@section Opening Streams
+
+@cindex opening a stream
+Opening a file with the @code{fopen} function creates a new stream and
+establishes a connection between the stream and a file.  This may
+involve creating a new file.  
+
+@pindex stdio.h
+Everything described in this section is declared in the header file
+@file{stdio.h}.
+
+@comment stdio.h
+@comment ANSI
+@deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
+The @code{fopen} function opens a stream for I/O to the file
+@var{filename}, and returns a pointer to the stream.
+
+The @var{opentype} argument is a string that controls how the file is
+opened and specifies attributes of the resulting stream.  It must begin
+with one of the following sequences of characters:
+
+@table @samp
+@item r
+Open an existing file for reading only.
+
+@item w
+Open the file for writing only.  If the file already exists, it is
+truncated to zero length.  Otherwise a new file is created.
+
+@item a
+Open a file for append access; that is, writing at the end of file only.
+If the file already exists, its initial contents are unchanged and
+output to the stream is appended to the end of the file.
+Otherwise, a new, empty file is created.
+
+@item r+
+Open an existing file for both reading and writing.  The initial contents
+of the file are unchanged and the initial file position is at the
+beginning of the file.
+
+@item w+
+Open a file for both reading and writing.  If the file already exists, it
+is truncated to zero length.  Otherwise, a new file is created.
+
+@item a+
+Open or create file for both reading and appending.  If the file exists,
+its initial contents are unchanged.  Otherwise, a new file is created.
+The initial file position for reading is at the beginning of the file,
+but output is always appended to the end of the file.
+@end table
+
+As you can see, @samp{+} requests a stream that can do both input and
+output.  The ANSI standard says that when using such a stream, you must
+call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
+function such as @code{fseek} (@pxref{File Positioning}) when switching
+from reading to writing or vice versa.  Otherwise, internal buffers
+might not be emptied properly.  The GNU C library does not have this
+limitation; you can do arbitrary reading and writing operations on a
+stream in whatever order.
+
+Additional characters may appear after these to specify flags for the
+call.  Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
+the only part you are guaranteed will be understood by all systems.
+
+The GNU C library defines one additional character for use in
+@var{opentype}: the character @samp{x} insists on creating a new
+file---if a file @var{filename} already exists, @code{fopen} fails
+rather than opening it.  If you use @samp{x} you can are guaranteed that
+you will not clobber an existing file.  This is equivalent to the
+@code{O_EXCL} option to the @code{open} function (@pxref{Opening and
+Closing Files}).
+
+The character @samp{b} in @var{opentype} has a standard meaning; it
+requests a binary stream rather than a text stream.  But this makes no
+difference in POSIX systems (including the GNU system).  If both
+@samp{+} and @samp{b} are specified, they can appear in either order.
+@xref{Binary Streams}.
+
+Any other characters in @var{opentype} are simply ignored.  They may be
+meaningful in other systems.
+
+If the open fails, @code{fopen} returns a null pointer.
+@end deftypefun
+
+You can have multiple streams (or file descriptors) pointing to the same
+file open at the same time.  If you do only input, this works
+straightforwardly, but you must be careful if any output streams are
+included.  @xref{Stream/Descriptor Precautions}.  This is equally true
+whether the streams are in one program (not usual) or in several
+programs (which can easily happen).  It may be advantageous to use the
+file locking facilities to avoid simultaneous access.  @xref{File
+Locks}.
+
+@comment stdio.h
+@comment ANSI
+@deftypevr Macro int FOPEN_MAX
+The value of this macro is an integer constant expression that
+represents the minimum number of streams that the implementation
+guarantees can be open simultaneously.  You might be able to open more
+than this many streams, but that is not guaranteed.  The value of this
+constant is at least eight, which includes the three standard streams
+@code{stdin}, @code{stdout}, and @code{stderr}.  In POSIX.1 systems this
+value is determined by the @code{OPEN_MAX} parameter; @pxref{General
+Limits}.  In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
+resource limit; @pxref{Limits on Resources}.
+@end deftypevr
+
+@comment stdio.h
+@comment ANSI
+@deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+This function is like a combination of @code{fclose} and @code{fopen}.
+It first closes the stream referred to by @var{stream}, ignoring any
+errors that are detected in the process.  (Because errors are ignored,
+you should not use @code{freopen} on an output stream if you have
+actually done any output using the stream.)  Then the file named by
+@var{filename} is opened with mode @var{opentype} as for @code{fopen},
+and associated with the same stream object @var{stream}.
+
+If the operation fails, a null pointer is returned; otherwise,
+@code{freopen} returns @var{stream}.
+
+@code{freopen} has traditionally been used to connect a standard stream
+such as @code{stdin} with a file of your own choice.  This is useful in
+programs in which use of a standard stream for certain purposes is
+hard-coded.  In the GNU C library, you can simply close the standard
+streams and open new ones with @code{fopen}.  But other systems lack
+this ability, so using @code{freopen} is more portable.
+@end deftypefun
+
+
+@node Closing Streams
+@section Closing Streams
+
+@cindex closing a stream
+When a stream is closed with @code{fclose}, the connection between the
+stream and the file is cancelled.  After you have closed a stream, you
+cannot perform any additional operations on it.
+
+@comment stdio.h
+@comment ANSI
+@deftypefun int fclose (FILE *@var{stream})
+This function causes @var{stream} to be closed and the connection to
+the corresponding file to be broken.  Any buffered output is written
+and any buffered input is discarded.  The @code{fclose} function returns
+a value of @code{0} if the file was closed successfully, and @code{EOF}
+if an error was detected. 
+
+It is important to check for errors when you call @code{fclose} to close
+an output stream, because real, everyday errors can be detected at this
+time.  For example, when @code{fclose} writes the remaining buffered
+output, it might get an error because the disk is full.  Even if you
+know the buffer is empty, errors can still occur when closing a file if
+you are using NFS.
+
+The function @code{fclose} is declared in @file{stdio.h}.
+@end deftypefun
+
+If the @code{main} function to your program returns, or if you call the
+@code{exit} function (@pxref{Normal Termination}), all open streams are
+automatically closed properly.  If your program terminates in any other
+manner, such as by calling the @code{abort} function (@pxref{Aborting a
+Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
+might not be closed properly.  Buffered output might not be flushed and
+files may be incomplete.  For more information on buffering of streams,
+see @ref{Stream Buffering}.
+
+@node Simple Output
+@section Simple Output by Characters or Lines
+
+@cindex writing to a stream, by characters
+This section describes functions for performing character- and
+line-oriented output.
+
+These functions are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ANSI
+@deftypefun int fputc (int @var{c}, FILE *@var{stream})
+The @code{fputc} function converts the character @var{c} to type
+@code{unsigned char}, and writes it to the stream @var{stream}.  
+@code{EOF} is returned if a write error occurs; otherwise the
+character @var{c} is returned.
+@end deftypefun
+
+@comment stdio.h
+@comment ANSI
+@deftypefun int putc (int @var{c}, FILE *@var{stream})
+This is just like @code{fputc}, except that most systems implement it as
+a macro, making it faster.  One consequence is that it may evaluate the
+@var{stream} argument more than once, which is an exception to the
+general rule for macros.  @code{putc} is usually the best function to
+use for writing a single character.
+@end deftypefun
+
+@comment stdio.h
+@comment ANSI
+@deftypefun int putchar (int @var{c})
+The @code{putchar} function is equivalent to @code{putc} with
+@code{stdout} as the value of the @var{stream} argument.
+@end deftypefun
+
+@comment stdio.h
+@comment ANSI
+@deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
+The function @code{fputs} writes the string @var{s} to the stream
+@var{stream}.  The terminating null character is not written.
+This function does @emph{not} add a newline character, either.
+It outputs only the characters in the string.
+
+This function returns @code{EOF} if a write error occurs, and otherwise
+a non-negative value.
+
+For example:
+
+@smallexample
+fputs ("Are ", stdout);
+fputs ("you ", stdout);
+fputs ("hungry?\n", stdout);
+@end smallexample
+
+@noindent
+outputs the text @samp{Are you hungry?} followed by a newline.
+@end deftypefun
+
+@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.  (Note that @code{fputs} does @emph{not}
+write a newline as this function does.)
+
+@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-oriented input.
+These functions are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+These functions return an @code{int} value that is either a character of
+input, or the special value @code{EOF} (usually -1).  It is important to
+store the result of these functions in a variable of type @code{int}
+instead of @code{char}, even when you plan to use it only as a
+character.  Storing @code{EOF} in a @code{char} variable truncates its
+value to the size of a character, so that it is no longer
+distinguishable from the valid character @samp{(char) -1}.  So always
+use an @code{int} for the result of @code{getc} and friends, and check
+for @code{EOF} after the call; once you've verified that the result is
+not @code{EOF}, you can be sure that it will fit in a @samp{char}
+variable without loss of information.
+
+@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 != EOF)
+        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}).  Unlike @code{getc},
+any @code{int} value could be a valid result.  @code{getw} returns
+@code{EOF} when it encounters end-of-file or an error, but there is no
+way to distinguish this from an input word with value -1.
+@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
+         ^