diff options
Diffstat (limited to 'manual/stdio.texi')
-rw-r--r-- | manual/stdio.texi | 106 |
1 files changed, 82 insertions, 24 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi index f5e289d58a..c7a2b4a9a1 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -330,6 +330,14 @@ this ability, so using @code{freopen} is more portable. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine this function is in fact @code{freopen64} since the LFS interface replaces transparently the old interface. + +@Theglibc{} only supports use of @code{freopen} on streams opened with +@code{fopen} or @code{fopen64} and on the original values of the +standard streams @code{stdin}, @code{stdout}, and @code{stderr}; such +a stream may be reopened multiple times with @code{freopen}. If it is +called on another kind of stream (opened with functions such as +@code{popen}, @code{fmemopen}, @code{open_memstream}, and +@code{fopencookie}), @code{freopen} fails and returns a null pointer. @end deftypefun @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) @@ -903,21 +911,17 @@ This function is a GNU extension. @deftypefun int putc (int @var{c}, FILE *@var{stream}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -This is just like @code{fputc}, except that most systems implement it as -a macro, making it faster. One consequence is that it may evaluate the -@var{stream} argument more than once, which is an exception to the -general rule for macros. @code{putc} is usually the best function to -use for writing a single character. +This is just like @code{fputc}, except that it may be implemented as +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream}) @standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -This is just like @code{fputwc}, except that it can be implement as -a macro, making it faster. One consequence is that it may evaluate the -@var{stream} argument more than once, which is an exception to the -general rule for macros. @code{putwc} is usually the best function to -use for writing a single wide character. +This is just like @code{fputwc}, except that it may be implemented as +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream}) @@ -1110,20 +1114,17 @@ This function is a GNU extension. @deftypefun int getc (FILE *@var{stream}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This is just like @code{fgetc}, except that it is permissible (and -typical) for it to be implemented as a macro that evaluates the -@var{stream} argument more than once. @code{getc} is often highly -optimized, so it is usually the best function to use to read a single -character. +This is just like @code{fgetc}, except that it may be implemented as +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc (FILE *@var{stream}) @standards{ISO, wchar.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This is just like @code{fgetwc}, except that it is permissible for it to -be implemented as a macro that evaluates the @var{stream} argument more -than once. @code{getwc} can be highly optimized, so it is usually the -best function to use to read a single wide character. +This is just like @code{fgetwc}, except that it may be implemented as +a macro and may evaluate the @var{stream} argument more than once. +Therefore, @var{stream} should never be an expression with side-effects. @end deftypefun @deftypefun int getc_unlocked (FILE *@var{stream}) @@ -1474,11 +1475,9 @@ program; usually @code{ungetc} is used only to unread a character that was just read from the same stream. @Theglibc{} supports this even on files opened in binary mode, but other systems might not. -@Theglibc{} only supports one character of pushback---in other -words, it does not work to call @code{ungetc} twice without doing input -in between. Other systems might let you push back multiple characters; -then reading from the stream retrieves the characters in the reverse -order that they were pushed. +@Theglibc{} supports pushing back multiple characters; subsequently +reading from the stream retrieves the characters in the reverse order +that they were pushed. Pushing back characters doesn't alter the file; only the internal buffering for the stream is affected. If a file positioning function @@ -2363,6 +2362,29 @@ the easiest way to make sure you have all the right prototypes is to just include @file{stdio.h}. @pindex stdio.h +The @code{printf} family shares the error codes listed below. +Individual functions may report additional @code{errno} values if they +fail. + +@table @code +@item EOVERFLOW +The number of written bytes would have exceeded @code{INT_MAX}, and thus +could not be represented in the return type @code{int}. + +@item ENOMEM +The function could not allocate memory during processing. Long argument +lists and certain floating point conversions may require memory +allocation, as does initialization of an output stream upon first use. + +@item EILSEQ +POSIX specifies this error code should be used if a wide character is +encountered that does not have a matching valid character. @Theglibc{} +always performs transliteration, using a replacement character if +necessary, so this error condition cannot occur on output. However, +@theglibc{} uses @code{EILSEQ} to indicate that an input character +sequence (wide or multi-byte) could not be converted successfully. +@end table + @deftypefun int printf (const char *@var{template}, @dots{}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @@ -2509,6 +2531,26 @@ store the result in which case @code{-1} is returned. This was changed in order to comply with the @w{ISO C99} standard. @end deftypefun +@deftypefun dprintf (int @var{fd}, @var{template}, ...) +@standards{POSIX, stdio.h} +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +This function formats its arguments according to @var{template} and +writes the result to the file descriptor @var{fd}, using the +@code{write} function. It returns the number of bytes written, or a +negative value if there was an error. In the error case, @code{errno} +is set appropriately. The possible @code{errno} values depend on the +type of the file descriptor @var{fd}, in addition to the general +@code{printf} error codes. + +The number of calls to @code{write} is unspecified, and some @code{write} +calls may have happened even if @code{dprintf} returns with an error. + +@strong{Portability Note:} POSIX does not require that this function is +async-signal-safe, and @theglibc{} implementation is not. However, some +other systems offer this function as an async-signal-safe alternative to +@code{fprintf}. @xref{POSIX Safety Concepts}. +@end deftypefun + @node Dynamic Output @subsection Dynamically Allocating Formatted Output @@ -2722,6 +2764,13 @@ The @code{obstack_vprintf} function is the equivalent of as for @code{vprintf}. @end deftypefun +@deftypefun int vdprintf (int @var{fd}, const char *@var{template}, va_list @var{ap}) +@standards{POSIX, stdio.h} +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +The @code{vdprintf} is the equivalent of @code{dprintf}, but processes +an argument list. +@end deftypefun + Here's an example showing how you might use @code{vfprintf}. This is a function that prints error messages to the stream @code{stderr}, along with a prefix indicating the name of the program @@ -4119,6 +4168,15 @@ check indicators that are part of the internal state of the stream object, indicators set if the appropriate condition was detected by a previous I/O operation on that stream. +The end of file and error conditions are mutually exclusive. For a +narrow oriented stream, end of file is not considered an error. For +wide oriented streams, reaching the end of the underlying file can +result an error if the underlying file ends with an incomplete multibyte +sequence. This is reported as an error by @code{ferror}, and not as an +end of file by @code{feof}. End of file on wide oriented streams that +does not fall into the middle of a multibyte sequence is reported via +@code{feof}. + @deftypevr Macro int EOF @standards{ISO, stdio.h} This macro is an integer value that is returned by a number of narrow |