stdio doc patch

[Jeff Johnston]

Thanks Eric.  Please go ahead.

-- Jeff J.

Eric Blake wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> OK to apply?  I noticed that I failed to properly document fopencookie,
> and in the process of fixing that, discovered ungetc was undocumented.
> 
> 2007-07-13  Eric Blake  <ebb9@byu.net>
> 
> 	Documentation updates.
> 	* libc/stdio/ungetc.c: Document ungetc.
> 	* libc/stdio/Makefile.am (CHEWOUT_FILES): Sort, match current list
> 	of files with documentation.
> 	* libc/stdio/Makefile.in: Regenerate.
> 	* libc/stdio/stdio.tex: Sort and update stdio documentation index.
> 
> - --
> Don't work too hard, make some time for fun as well!
> 
> Eric Blake             ebb9@byu.net
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.5 (Cygwin)
> Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
> 
> iD8DBQFGl4d384KuGfSFAYARAiIlAJ9EQGTKDePB9xp4SjYyit2cbo+8tQCeKto+
> QRTjO3TNHbUw1YXdM3C8KKY=
> =0aW8
> -----END PGP SIGNATURE-----
> 
> 
> ------------------------------------------------------------------------
> 
> Index: libc/stdio/Makefile.am
> ===================================================================
> RCS file: /cvs/src/src/newlib/libc/stdio/Makefile.am,v
> retrieving revision 1.25
> diff -u -p -r1.25 Makefile.am
> --- libc/stdio/Makefile.am	4 Jun 2007 18:10:16 -0000	1.25
> +++ libc/stdio/Makefile.am	13 Jul 2007 14:02:42 -0000
> @@ -179,7 +179,6 @@ CHEWOUT_FILES = \
>  	fgetpos.def		\
>  	fgets.def		\
>  	fileno.def		\
> -	fiprintf.def		\
>  	fopen.def		\
>  	fopencookie.def		\
>  	fputc.def		\
> @@ -192,8 +191,8 @@ CHEWOUT_FILES = \
>  	funopen.def		\
>  	fwrite.def		\
>  	getc.def		\
> -	getchar.def		\
>  	getc_u.def		\
> +	getchar.def		\
>  	getchar_u.def		\
>  	getdelim.def		\
>  	getline.def		\
> @@ -202,8 +201,8 @@ CHEWOUT_FILES = \
>  	mktemp.def		\
>  	perror.def		\
>  	putc.def		\
> -	putchar.def		\
>  	putc_u.def		\
> +	putchar.def		\
>  	putchar_u.def		\
>  	puts.def		\
>  	putw.def		\
> @@ -220,6 +219,7 @@ CHEWOUT_FILES = \
>  	sscanf.def		\
>  	tmpfile.def		\
>  	tmpnam.def		\
> +	ungetc.def		\
>  	vfprintf.def		\
>  	vfscanf.def		\
>  	viprintf.def		\
> Index: libc/stdio/stdio.tex
> ===================================================================
> RCS file: /cvs/src/src/newlib/libc/stdio/stdio.tex,v
> retrieving revision 1.7
> diff -u -p -r1.7 stdio.tex
> --- libc/stdio/stdio.tex	11 Oct 2005 23:59:32 -0000	1.7
> +++ libc/stdio/stdio.tex	13 Jul 2007 14:02:42 -0000
> @@ -1,9 +1,9 @@
>  @node Stdio
> -@chapter Input and Output (@file{stdio.h}) 
> +@chapter Input and Output (@file{stdio.h})
>  
>  This chapter comprises functions to manage files
>  or other input/output streams. Among these functions are subroutines
> -to generate or scan strings according to specifications from a format string. 
> +to generate or scan strings according to specifications from a format string.
>  
>  The underlying facilities for input and output depend on the host
>  system, but these functions provide a uniform interface.
> @@ -22,12 +22,14 @@ _stderr_r(@var{reent})
>  instead of the globals @code{stdin}, @code{stdout}, and
>  @code{stderr}.  The argument <[reent]> is a pointer to a reentrancy
>  structure.
> - 
> -@menu  
> +
> +@menu
>  * clearerr::    Clear file or stream error indicator
> +* diprintf::    Print to a file descriptor (integer only)
>  * dprintf::     Print to a file descriptor
>  * fclose::      Close a file
>  * fcloseall::   Close all files
> +* fdopen::      Turn an open file into a stream
>  * feof::        Test for end of file
>  * ferror::      Test whether read/write error has occurred
>  * fflush::      Flush buffered file output
> @@ -36,7 +38,7 @@ structure.
>  * fgets::       Get character string from a file or stream
>  * fileno::      Get file descriptor associated with stream
>  * fopen::       Open a file
> -* fdopen::	Turn an open file into a stream
> +* fopencookie:: Open a stream with custom callbacks
>  * fputc::       Write a character on a stream or file
>  * fputs::       Write a character string in a file or stream
>  * fread::       Read array elements from a file
> @@ -44,6 +46,7 @@ structure.
>  * fseek::       Set file position
>  * fsetpos::     Restore position of a stream or file
>  * ftell::       Return position in a stream or file
> +* funopen::     Open a stream with custom callbacks
>  * fwrite::      Write array elements from memory to a file or stream
>  * getc::        Get a character from a file or stream (macro)
>  * getc_unlocked::	Get a character from a file or stream (macro)
> @@ -68,22 +71,26 @@ structure.
>  * setbuffer::   Specify full buffering for a file or stream with size
>  * setlinebuf::  Specify line buffering for a file or stream
>  * setvbuf::     Specify buffering for a file or stream
> -* printf::      Write formatted output
> -* scanf::       Scan and format input
> -* iprintf::     Write formatted output (integer only)
> -* iscanf::      Scan and format input (integer only)
> +* siprintf::    Write formatted output (integer only)
> +* siscanf::     Scan and format input (integer only)
> +* sprintf::     Write formatted output
> +* sscanf::      Scan and format input
>  * tmpfile::     Create a temporary file
>  * tmpnam::      Generate name for a temporary file
> -* viprintf::    Format variable argument list for non-floating-point output
> -* viscanf::     Scan variable format list for non-floating-point input
> -* vprintf::     Format variable argument list
> -* vscanf::      Format variable argument list
> -@end menu 
> +* ungetc::      Push data back into a stream
> +* vfprintf::    Format variable argument list
> +* vfscanf::     Scan variable argument list
> +* viprintf::    Format variable argument list (integer only)
> +* viscanf::     Scan variable format list (integer only)
> +@end menu
>  
>  @page
>  @include stdio/clearerr.def
>  
>  @page
> +@include stdio/diprintf.def
> +
> +@page
>  @include stdio/dprintf.def
>  
>  @page
> @@ -93,6 +100,9 @@ structure.
>  @include stdio/fcloseall.def
>  
>  @page
> +@include stdio/fdopen.def
> +
> +@page
>  @include stdio/feof.def
>  
>  @page
> @@ -101,14 +111,14 @@ structure.
>  @page
>  @include stdio/fflush.def
>  
> -@page 
> -@include stdio/fgetc.def 
> +@page
> +@include stdio/fgetc.def
>  
>  @page
>  @include stdio/fgetpos.def
>  
> -@page 
> -@include stdio/fgets.def 
> +@page
> +@include stdio/fgets.def
>  
>  @page
>  @include stdio/fileno.def
> @@ -117,7 +127,7 @@ structure.
>  @include stdio/fopen.def
>  
>  @page
> -@include stdio/fdopen.def
> +@include stdio/fopencookie.def
>  
>  @page
>  @include stdio/fputc.def
> @@ -143,14 +153,14 @@ structure.
>  @page
>  @include stdio/fwrite.def
>  
> -@page 
> -@include stdio/getc.def 
> +@page
> +@include stdio/getc.def
>  
>  @page
>  @include stdio/getc_u.def
>  
>  @page
> -@include stdio/getchar.def 
> +@include stdio/getchar.def
>  
>  @page
>  @include stdio/getchar_u.def
> @@ -161,11 +171,11 @@ structure.
>  @page
>  @include stdio/getline.def
>  
> -@page 
> +@page
>  @include stdio/gets.def
>  
> -@page 
> -@include stdio/getw.def 
> +@page
> +@include stdio/getw.def
>  
>  @page
>  @include stdio/mktemp.def
> @@ -188,8 +198,8 @@ structure.
>  @page
>  @include stdio/puts.def
>  
> -@page 
> -@include stdio/putw.def 
> +@page
> +@include stdio/putw.def
>  
>  @page
>  @include stdio/remove.def
> @@ -212,17 +222,17 @@ structure.
>  @page
>  @include stdio/setvbuf.def
>  
> -@page 
> -@include stdio/sprintf.def 
> +@page
> +@include stdio/siprintf.def
>  
>  @page
> -@include stdio/sscanf.def 
> +@include stdio/siscanf.def
>  
> -@page 
> -@include stdio/siprintf.def 
> +@page
> +@include stdio/sprintf.def
>  
> -@page 
> -@include stdio/siscanf.def 
> +@page
> +@include stdio/sscanf.def
>  
>  @page
>  @include stdio/tmpfile.def
> @@ -230,15 +240,17 @@ structure.
>  @page
>  @include stdio/tmpnam.def
>  
> -@page 
> -@include stdio/vfprintf.def 
> +@page
> +@include stdio/ungetc.def
>  
>  @page
> -@include stdio/vfscanf.def
> +@include stdio/vfprintf.def
>  
> -@page 
> -@include stdio/viprintf.def 
> +@page
> +@include stdio/vfscanf.def
>  
> -@page 
> -@include stdio/viscanf.def 
> +@page
> +@include stdio/viprintf.def
>  
> +@page
> +@include stdio/viscanf.def
> Index: libc/stdio/ungetc.c
> ===================================================================
> RCS file: /cvs/src/src/newlib/libc/stdio/ungetc.c,v
> retrieving revision 1.7
> diff -u -p -r1.7 ungetc.c
> --- libc/stdio/ungetc.c	26 Sep 2006 21:22:19 -0000	1.7
> +++ libc/stdio/ungetc.c	13 Jul 2007 14:02:42 -0000
> @@ -14,6 +14,48 @@
>   * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
>   * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
>   */
> +/*
> +FUNCTION
> +<<ungetc>>---push data back into a stream
> +
> +INDEX
> +	ungetc
> +INDEX
> +	_ungetc_r
> +
> +ANSI_SYNOPSIS
> +	#include <stdio.h>
> +	int ungetc(int <[c]>, FILE *<[stream]>);
> +
> +	int _ungetc_r(struct _reent *<[reent]>, int <[c]>, FILE *<[stream]>);
> +
> +DESCRIPTION
> +<<ungetc>> is used to return bytes back to <[stream]> to be read again.
> +If <[c]> is EOF, the stream is unchanged.  Otherwise, the unsigned
> +char <[c]> is put back on the stream, and subsequent reads will see
> +the bytes pushed back in reverse order.  Pushed byes are lost if the
> +stream is repositioned, such as by <<fseek>>, <<fsetpos>>, or
> +<<rewind>>.
> +
> +The underlying file is not changed, but it is possible to push back
> +something different than what was originally read.  Ungetting a
> +character will clear the end-of-stream marker, and decrement the file
> +position indicator.  Pushing back beyond the beginning of a file gives
> +unspecified behavior.
> +
> +The alternate function <<_ungetc_r>> is a reentrant version.  The
> +extra argument <[reent]> is a pointer to a reentrancy structure.
> +
> +RETURNS
> +The character pushed back, or <<EOF>> on error.
> +
> +PORTABILITY
> +ANSI C requires <<ungetc>>, but only requires a pushback buffer of one
> +byte; although this implementation can handle multiple bytes, not all
> +can.  Pushing back a signed char is a common application bug.
> +
> +Supporting OS subroutines required: <<sbrk>>.
> +*/
>  
>  #if defined(LIBC_SCCS) && !defined(lint)
>  static char sccsid[] = "%W% (Berkeley) %G%";
> @@ -84,7 +126,7 @@ _DEFUN(_ungetc_r, (rptr, c, fp),
>    CHECK_INIT (rptr, fp);
>  
>    _flockfile (fp);
> -  
> +
>    /* After ungetc, we won't be at eof anymore */
>    fp->_flags &= ~__SEOF;
>  
> @@ -171,4 +213,3 @@ _DEFUN(ungetc, (c, fp),
>    return _ungetc_r (_REENT, c, fp);
>  }
>  #endif /* !_REENT_ONLY */
> -