diff options
Diffstat (limited to 'manual/stdio.texi')
| -rw-r--r-- | manual/stdio.texi | 140 |
1 files changed, 117 insertions, 23 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi index 8517653..29ed720 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}) @@ -921,6 +929,9 @@ Therefore, @var{stream} should never be an expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putc_unlocked} function is equivalent to the @code{putc} function except that it does not implicitly lock the stream. +Like @code{putc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) @@ -1124,6 +1135,9 @@ Therefore, @var{stream} should never be an expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getc_unlocked} function is equivalent to the @code{getc} function except that it does not implicitly lock the stream. +Like @code{getc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) @@ -1217,17 +1231,18 @@ convenient to have functions to read a line of text from a stream. Standard C has functions to do this, but they aren't very safe: null characters and even (for @code{gets}) long lines can confuse them. So -@theglibc{} provides the nonstandard @code{getline} function that -makes it easy to read lines reliably. +@theglibc{} provides the @code{getline} function that makes it easy to +read lines reliably. -Another GNU extension, @code{getdelim}, generalizes @code{getline}. It -reads a delimited record, defined as everything through the next -occurrence of a specified delimiter character. +The @code{getdelim} function is a generalized version of @code{getline}. +It reads a delimited record, defined as everything through the next +occurrence of a specified delimiter character. These functions were +both GNU extensions until standardized by POSIX.1-2008. All these functions are declared in @file{stdio.h}. -@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream}) -@standards{GNU, stdio.h} +@deftypefun ssize_t getline (char **restrict @var{lineptr}, size_t *restrict @var{n}, FILE *restrict @var{stream}) +@standards{POSIX.1-2008, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c Besides the usual possibility of getting an inconsistent stream in a @c signal handler or leaving it inconsistent in case of cancellation, @@ -1260,15 +1275,15 @@ read (including the newline, but not including the terminating null). This value enables you to distinguish null characters that are part of the line from the null character inserted as a terminator. -This function is a GNU extension, but it is the recommended way to read -lines from a stream. The alternative standard functions are unreliable. +This function was originally a GNU extension, but was added in +POSIX.1-2008. If an error occurs or end of file is reached without any bytes read, @code{getline} returns @code{-1}. @end deftypefun -@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream}) -@standards{GNU, stdio.h} +@deftypefun ssize_t getdelim (char **restrict @var{lineptr}, size_t *restrict @var{n}, int @var{delimiter}, FILE *restrict @var{stream}) +@standards{POSIX.1-2008, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} @c See the getline @acucorrupt note. This function is like @code{getline} except that the character which @@ -1280,6 +1295,9 @@ The text is stored in @var{lineptr}, including the delimiter character and a terminating null. Like @code{getline}, @code{getdelim} makes @var{lineptr} bigger if it isn't big enough. +This function was originally a GNU extension, but was added in +POSIX.1-2008. + @code{getline} is in fact implemented in terms of @code{getdelim}, just like this: @@ -1467,11 +1485,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 @@ -1565,6 +1581,9 @@ The @code{fread_unlocked} function is equivalent to the @code{fread} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) @@ -1583,6 +1602,9 @@ The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @node Formatted Output @@ -2356,6 +2378,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{}}} @@ -2502,6 +2547,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 int 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 @@ -2517,7 +2582,14 @@ Allocation}) to hold the output, instead of putting the output in a buffer you allocate in advance. The @var{ptr} argument should be the address of a @code{char *} object, and a successful call to @code{asprintf} stores a pointer to the newly allocated string at that -location. +location. Current and future versions of @theglibc{} write a null +pointer to @samp{*@var{ptr}} upon failure. To achieve similar +behavior with previous versions, initialize @samp{*@var{ptr}} to a +null pointer before calling @code{asprintf}. (Specifications for +@code{asprintf} only require a valid pointer value in +@samp{*@var{ptr}} if @code{asprintf} succeeds, but no implementations +are known which overwrite a null pointer with a pointer that cannot be +freed on failure.) The return value is the number of characters allocated for the buffer, or less than zero if an error occurred. Usually this means that the buffer @@ -2715,6 +2787,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 @@ -4112,6 +4191,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 @@ -4263,6 +4351,18 @@ terminating newline character). @cindex lines (in a text file) @item +If the system does not use POSIX-style in-band signalling to indicate +line termination, it can be impossibe to write anything to a text stream +without adding a line terminator. As a result, flushing a text stream +(by calling @code{fflush}, for example) may produce a logical line +terminator even if no @code{'\n'} character was written by the program. + +@item +Text files may contain lines that embed @code{'\n'} characters that are +not treated as line terminators by the system. C programs cannot read +such text files reliably using the @file{stdio.h} facilities. + +@item On some systems, text files can contain only printing characters, horizontal tab characters, and newlines, and so text streams may not support other characters. However, binary streams can handle any @@ -4754,12 +4854,6 @@ currently opened. This function is declared in the @file{stdio_ext.h} header. @end deftypefun -@strong{Compatibility Note:} Some brain-damaged operating systems have -been known to be so thoroughly fixated on line-oriented input and output -that flushing a line buffered stream causes a newline to be written! -Fortunately, this ``feature'' seems to be becoming less common. You do -not need to worry about this with @theglibc{}. - In some situations it might be useful to not flush the output pending for a stream but instead simply forget it. If transmission is costly and the output is not needed anymore this is valid reasoning. In this |