diff --git a/newlib/ChangeLog b/newlib/ChangeLog index 484c0e08b..5f0b3b499 100644 --- a/newlib/ChangeLog +++ b/newlib/ChangeLog @@ -1,3 +1,12 @@ +2007-07-13 Eric Blake + + 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. + 2007-07-11 Jeff Johnston * libc/include/math.h: Fix so C99 functions/macros are accessible diff --git a/newlib/libc/stdio/Makefile.am b/newlib/libc/stdio/Makefile.am index 39617d2bd..2b7cb62d9 100644 --- a/newlib/libc/stdio/Makefile.am +++ b/newlib/libc/stdio/Makefile.am @@ -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 \ diff --git a/newlib/libc/stdio/Makefile.in b/newlib/libc/stdio/Makefile.in index 27fbd9a68..32dfae2a2 100644 --- a/newlib/libc/stdio/Makefile.in +++ b/newlib/libc/stdio/Makefile.in @@ -463,7 +463,6 @@ CHEWOUT_FILES = \ fgetpos.def \ fgets.def \ fileno.def \ - fiprintf.def \ fopen.def \ fopencookie.def \ fputc.def \ @@ -476,8 +475,8 @@ CHEWOUT_FILES = \ funopen.def \ fwrite.def \ getc.def \ - getchar.def \ getc_u.def \ + getchar.def \ getchar_u.def \ getdelim.def \ getline.def \ @@ -486,8 +485,8 @@ CHEWOUT_FILES = \ mktemp.def \ perror.def \ putc.def \ - putchar.def \ putc_u.def \ + putchar.def \ putchar_u.def \ puts.def \ putw.def \ @@ -504,6 +503,7 @@ CHEWOUT_FILES = \ sscanf.def \ tmpfile.def \ tmpnam.def \ + ungetc.def \ vfprintf.def \ vfscanf.def \ viprintf.def \ diff --git a/newlib/libc/stdio/stdio.tex b/newlib/libc/stdio/stdio.tex index 9c2ca0f5d..a3846eaed 100644 --- a/newlib/libc/stdio/stdio.tex +++ b/newlib/libc/stdio/stdio.tex @@ -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,21 +71,25 @@ 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 @@ -92,6 +99,9 @@ structure. @page @include stdio/fcloseall.def +@page +@include stdio/fdopen.def + @page @include stdio/feof.def @@ -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/vfprintf.def @page @include stdio/vfscanf.def -@page -@include stdio/viprintf.def - -@page -@include stdio/viscanf.def +@page +@include stdio/viprintf.def +@page +@include stdio/viscanf.def diff --git a/newlib/libc/stdio/ungetc.c b/newlib/libc/stdio/ungetc.c index 333baa278..59834ded7 100644 --- a/newlib/libc/stdio/ungetc.c +++ b/newlib/libc/stdio/ungetc.c @@ -14,6 +14,48 @@ * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. */ +/* +FUNCTION +<>---push data back into a stream + +INDEX + ungetc +INDEX + _ungetc_r + +ANSI_SYNOPSIS + #include + int ungetc(int <[c]>, FILE *<[stream]>); + + int _ungetc_r(struct _reent *<[reent]>, int <[c]>, FILE *<[stream]>); + +DESCRIPTION +<> 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 <>, <>, or +<>. + +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 <> on error. + +PORTABILITY +ANSI C requires <>, 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: <>. +*/ #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 */ -