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.
2025-02-21 00:07:36 +08:00 · 2007-07-13 17:07:28 +00:00 · 2007-07-13 17:07:28 +00:00 · 88c8888127
commit 88c8888127
parent 254860bcfd
5 changed files with 111 additions and 49 deletions
--- a/newlib/ChangeLog
+++ b/newlib/ChangeLog
@ -1,3 +1,12 @@
+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.
+
 2007-07-11  Jeff Johnston  <jjohnstn@redhat.com>

 	* libc/include/math.h: Fix so C99 functions/macros are accessible
--- 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		\
--- 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		\
--- 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
--- 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
+<<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 */
-