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