stdio doc patch

[Eric Blake <ebb9 at byu dot net>]

-----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 */
-