Lines Matching refs:code
27 * Formatted Output:: @code{printf} and related functions.
29 @code{printf} and friends.
30 * Formatted Input:: @code{scanf} and related functions.
47 a stream is called @code{FILE} rather than ``stream''. Since most of
48 the library functions deal with objects of type @code{FILE *}, sometimes
56 The @code{FILE} type is declared in the header file @file{stdio.h}.
60 This is the data type used to represent stream objects. A @code{FILE}
64 end-of-file status indicators that can be tested with the @code{ferror}
65 and @code{feof} functions; see @ref{EOF and Errors}.
68 @code{FILE} objects are allocated and managed internally by the
70 type @code{FILE}; let the library do it. Your programs should
71 deal only with pointers to these objects (that is, @code{FILE *} values)
80 When the @code{main} function of your program is invoked, it already has
115 In @theglibc{}, @code{stdin}, @code{stdout}, and @code{stderr} are
124 Note however, that in other systems @code{stdin}, @code{stdout}, and
125 @code{stderr} are macros that you cannot assign to in the normal way.
126 But you can use @code{freopen} to get the effect of closing one and
129 The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
136 Opening a file with the @code{fopen} function creates a new stream and
148 The @code{fopen} function opens a stream for I/O to the file
186 output. When using such a stream, you must call @code{fflush}
188 @code{fseek} (@pxref{File Positioning}) when switching from reading
204 @code{exec@dots{}} functions (@pxref{Executing a File}). (This is
205 equivalent to having set @code{FD_CLOEXEC} on that descriptor.
209 The file is opened and accessed using @code{mmap}. This is only
214 exists, @code{fopen} fails rather than opening it. If you use
216 file. This is equivalent to the @code{O_EXCL} option to the
217 @code{open} function (@pxref{Opening and Closing Files}).
221 equivalent of @code{O_EXCL}.
233 @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
234 coded character set and @code{fopen} will mark the stream as
242 on even if the locale selected for the @code{LC_CTYPE} category is
248 If the open fails, @code{fopen} returns a null pointer.
250 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
251 32 bit machine this function is in fact @code{fopen64} since the LFS
267 This function is similar to @code{fopen} but the stream it returns a
268 pointer for is opened using @code{open64}. Therefore this stream can be
271 Please note that the return type is still @code{FILE *}. There is no
272 special @code{FILE} type for the LFS interface.
274 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
275 bits machine this function is available under the name @code{fopen}
286 @code{stdin}, @code{stdout}, and @code{stderr}. In POSIX.1 systems this
287 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
288 Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
304 This function is like a combination of @code{fclose} and @code{fopen}.
307 you should not use @code{freopen} on an output stream if you have
309 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
313 @code{freopen} returns @var{stream}. On Linux, @code{freopen} may also
314 fail and set @code{errno} to @code{EBUSY} when the kernel structure for
315 the old file descriptor was not initialized completely before @code{freopen}
318 possibility of this race, do not use @code{close} to close the underlying
319 file descriptor for a @code{FILE}; either use @code{freopen} while the
320 file is still open, or use @code{open} and then @code{dup2} to install
323 @code{freopen} has traditionally been used to connect a standard stream
324 such as @code{stdin} with a file of your own choice. This is useful in
327 streams and open new ones with @code{fopen}. But other systems lack
328 this ability, so using @code{freopen} is more portable.
330 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
331 32 bit machine this function is in fact @code{freopen64} since the LFS
338 This function is similar to @code{freopen}. The only difference is that
342 using @code{fopen64} or @code{freopen64} since its mode is not important
345 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
346 bits machine this function is available under the name @code{freopen}
359 The @code{__freadable} function determines whether the stream
369 The @code{__fwritable} function determines whether the stream
382 The @code{__freading} function determines whether the stream
395 The @code{__fwriting} function determines whether the stream
407 When a stream is closed with @code{fclose}, the connection between the
430 and any buffered input is discarded. The @code{fclose} function returns
431 a value of @code{0} if the file was closed successfully, and @code{EOF}
434 It is important to check for errors when you call @code{fclose} to close
436 time. For example, when @code{fclose} writes the remaining buffered
441 The function @code{fclose} is declared in @file{stdio.h}.
457 is written and any buffered input is discarded. The @code{fcloseall}
458 function returns a value of @code{0} if all the files were closed
459 successfully, and @code{EOF} if an error was detected.
467 The function @code{fcloseall} is declared in @file{stdio.h}.
470 If the @code{main} function to your program returns, or if you call the
471 @code{exit} function (@pxref{Normal Termination}), all open streams are
473 manner, such as by calling the @code{abort} function (@pxref{Aborting a
506 perform the stream locking in the application code.
513 The @code{flockfile} function acquires the internal locking object
515 thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
518 @code{funlockfile} has to be used to release the lock.
524 The @code{ftrylockfile} function tries to acquire the internal locking
526 @code{flockfile}. But unlike @code{flockfile} this function does not
527 block if the lock is not available. @code{ftrylockfile} returns zero if
535 The @code{funlockfile} function releases the internal locking object of
537 call to @code{flockfile} or a successful call of @code{ftrylockfile}.
539 The @code{funlockfile} function does not return an error status and the
546 (yes, the same job could be done with one @code{fprintf} call but it is
561 use the stream @var{fp} after the @code{fputs} call returns and before
562 @code{fprintf} was called with the result that the number does not
569 of times the lock is acquired. The same number of @code{funlockfile}
584 It is important here that the @code{funlockfile} function is only called
585 if the @code{ftrylockfile} function succeeded in locking the stream. It
586 is therefore always wrong to ignore the result of @code{ftrylockfile}.
587 And it makes no sense since otherwise one would use @code{flockfile}.
588 The result of code like that above is that either @code{funlockfile}
590 frees the stream prematurely. The code should look like this:
611 completely if it is not needed -- because the code in question is never
613 This can be determined most of the time for application code; for
614 library code which can be used in many contexts one should default to be
618 the @code{_unlocked} variants of the stream operations. The POSIX
625 @code{putc} and @code{getc} are very simple and traditionally (before the
629 expand to too much code.
631 names @code{putc_unlocked} and @code{getc_unlocked}. This possibly huge
632 difference of speed also suggests the use of the @code{_unlocked}
647 If in this example the @code{putc} function would be used and the
648 explicit locking would be missing the @code{putc} function would have to
651 @code{putc_unlocked} macro to be used which means no locking and direct
669 The @code{__fsetlocking} function can be used to select whether the
675 @vtable @code
677 The stream @code{stream} will from now on use the default internal
678 locking. Every stream operation with exception of the @code{_unlocked}
682 After the @code{__fsetlocking} function returns, the user is responsible
685 @code{FSETLOCKING_INTERNAL}.
688 @code{__fsetlocking} only queries the current locking state of the
689 stream. The return value will be @code{FSETLOCKING_INTERNAL} or
690 @code{FSETLOCKING_BYCALLER} depending on the state.
693 The return value of @code{__fsetlocking} is either
694 @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
701 This function is especially useful when program code has to be used
702 which is written without knowledge about the @code{_unlocked} functions
708 @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
710 strings of @code{wchar_t} directly. One had to convert them into
711 multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
717 format specifiers for the @code{printf} and @code{scanf} families of
719 possible using the @code{%C} specifier and wide character strings can be
720 handled with @code{%S}. These modifiers behave just like @code{%c} and
721 @code{%s} only that they expect the corresponding argument to have the
726 desirable to use @code{printf} and @code{scanf}. The other, smaller and
728 possible to have a format string for @code{printf} and @code{scanf}
738 same streams (like @code{stdout}). This is different from the model of
747 call to @code{freopen} or @code{freopen64} can reset the
753 @code{fread} and @code{fwrite} functions) the stream is marked as not
761 The @code{fwide} function can be used to set the orientation either way.
767 @code{fwide} function can help avoid this.
776 The @code{fwide} function can be used to set and query the state of the
780 with @code{fwide}. I.e., if the stream @var{stream} was already
786 The @code{fwide} function returns a negative value, zero, or a positive
796 @code{stdin}, @code{stdout}, and @code{stderr}. If some library
805 When writing code which uses streams and which can be used in different
822 Note that in this case the function @code{print_f} decides about the
826 The encoding used for the @code{wchar_t} values is unspecified and the
827 user must not make any assumptions about it. For I/O of @code{wchar_t}
832 chosen by the implementation for @code{wchar_t}. The external encoding
833 is determined by the @code{LC_CTYPE} category of the current locale or
834 by the @samp{ccs} part of the mode specification given to @code{fopen},
835 @code{fopen64}, @code{freopen}, or @code{freopen64}. How and when the
840 determined by the @code{LC_CTYPE} category selected at the time the
844 possible, perhaps with a call to @code{fwide}.
870 The @code{fputc} function converts the character @var{c} to type
871 @code{unsigned char}, and writes it to the stream @var{stream}.
872 @code{EOF} is returned if a write error occurs; otherwise the
879 The @code{fputwc} function writes the wide character @var{wc} to the
880 stream @var{stream}. @code{WEOF} is returned if a write error occurs;
890 The @code{fputc_unlocked} function is equivalent to the @code{fputc}
897 The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
906 This is just like @code{fputc}, except that most systems implement it as
909 general rule for macros. @code{putc} is usually the best function to
916 This is just like @code{fputwc}, except that it can be implement as
919 general rule for macros. @code{putwc} is usually the best function to
926 The @code{putc_unlocked} function is equivalent to the @code{putc}
933 The @code{putwc_unlocked} function is equivalent to the @code{putwc}
942 The @code{putchar} function is equivalent to @code{putc} with
943 @code{stdout} as the value of the @var{stream} argument.
949 The @code{putwchar} function is equivalent to @code{putwc} with
950 @code{stdout} as the value of the @var{stream} argument.
956 The @code{putchar_unlocked} function is equivalent to the @code{putchar}
963 The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
972 The function @code{fputs} writes the string @var{s} to the stream
977 This function returns @code{EOF} if a write error occurs, and otherwise
995 The function @code{fputws} writes the wide character string @var{ws} to
1000 This function returns @code{WEOF} if a write error occurs, and otherwise
1007 The @code{fputs_unlocked} function is equivalent to the @code{fputs}
1016 The @code{fputws_unlocked} function is equivalent to the @code{fputws}
1025 The @code{puts} function writes the string @var{s} to the stream
1026 @code{stdout} followed by a newline. The terminating null character of
1027 the string is not written. (Note that @code{fputs} does @emph{not}
1030 @code{puts} is the most convenient function for printing simple
1044 This function writes the word @var{w} (that is, an @code{int}) to
1046 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
1060 These functions return an @code{int} or @code{wint_t} value (for narrow
1062 input, or the special value @code{EOF}/@code{WEOF} (usually -1). For
1064 functions in a variable of type @code{int} instead of @code{char}, even
1065 when you plan to use it only as a character. Storing @code{EOF} in a
1066 @code{char} variable truncates its value to the size of a character, so
1068 @samp{(char) -1}. So always use an @code{int} for the result of
1069 @code{getc} and friends, and check for @code{EOF} after the call; once
1070 you've verified that the result is not @code{EOF}, you can be sure that
1080 This function reads the next character as an @code{unsigned char} from
1082 @code{int}. If an end-of-file condition or read error occurs,
1083 @code{EOF} is returned instead.
1091 occurs, @code{WEOF} is returned instead.
1097 The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
1104 The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
1113 This is just like @code{fgetc}, except that it is permissible (and
1115 @var{stream} argument more than once. @code{getc} is often highly
1123 This is just like @code{fgetwc}, except that it is permissible for it to
1125 than once. @code{getwc} can be highly optimized, so it is usually the
1132 The @code{getc_unlocked} function is equivalent to the @code{getc}
1139 The @code{getwc_unlocked} function is equivalent to the @code{getwc}
1148 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
1155 The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
1162 The @code{getchar_unlocked} function is equivalent to the @code{getchar}
1169 The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
1175 Here is an example of a function that does input using @code{fgetc}. It
1176 would work just as well using @code{getc} instead, or using
1177 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}. The code would
1211 This function reads a word (that is, an @code{int}) from @var{stream}.
1213 @code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
1214 any @code{int} value could be a valid result. @code{getw} returns
1215 @code{EOF} when it encounters end-of-file or an error, but there is no
1226 characters and even (for @code{gets}) long lines can confuse them. So
1227 @theglibc{} provides the nonstandard @code{getline} function that
1230 Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
1246 and storing the buffer address in @code{*@var{lineptr}}.
1248 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
1249 the address of a buffer @code{*@var{n}} bytes long, allocated with
1250 @code{malloc}. If this buffer is long enough to hold the line,
1251 @code{getline} stores the line in this buffer. Otherwise,
1252 @code{getline} makes the buffer bigger using @code{realloc}, storing the
1253 new buffer address back in @code{*@var{lineptr}} and the increased size
1254 back in @code{*@var{n}}.
1257 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
1258 to zero, before the call, then @code{getline} allocates the initial
1259 buffer for you by calling @code{malloc}. This buffer remains allocated
1260 even if @code{getline} encounters errors and is unable to read any bytes.
1262 In either case, when @code{getline} returns, @code{*@var{lineptr}} is
1263 a @code{char *} which points to the text of the line.
1265 When @code{getline} is successful, it returns the number of characters
1274 @code{getline} returns @code{-1}.
1281 This function is like @code{getline} except that the character which
1283 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
1287 and a terminating null. Like @code{getline}, @code{getdelim} makes
1290 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1305 The @code{fgets} function reads characters from the stream @var{stream}
1313 If the system is already at end of file when you call @code{fgets}, then
1319 So don't use @code{fgets} unless you know the data cannot contain a null.
1322 error message. We recommend using @code{getline} instead of @code{fgets}.
1328 The @code{fgetws} function reads wide characters from the stream
1336 If the system is already at end of file when you call @code{fgetws}, then
1343 @code{fgetws} unless you know the data cannot contain a null. Don't use
1353 The @code{fgets_unlocked} function is equivalent to the @code{fgets}
1362 The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
1371 The function @code{gets} reads characters from the stream @code{stdin}
1374 behavior of @code{fgets}, which copies the newline character into the
1375 string). If @code{gets} encounters a read error or end-of-file, it
1378 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
1381 should @strong{always} use @code{fgets} or @code{getline} instead. To
1382 remind you of this, the linker (if using GNU @code{ld}) will issue a
1383 warning whenever you use @code{gets}.
1400 by the next call to @code{fgetc} or other input function on that stream.
1404 * How Unread:: How to call @code{ungetc} to do unreading.
1453 @subsection Using @code{ungetc} To Do Unreading
1455 The function to unread a character is called @code{ungetc}, because it
1456 reverses the action of @code{getc}.
1461 The @code{ungetc} function pushes back the character @var{c} onto the
1465 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
1466 @code{EOF}. This lets you call @code{ungetc} with the return value of
1467 @code{getc} without needing to check for an error from @code{getc}.
1472 unreading them with @code{ungetc}! But that is a strange way to write a
1473 program; usually @code{ungetc} is used only to unread a character that
1478 words, it does not work to call @code{ungetc} twice without doing input
1485 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
1498 The @code{ungetwc} function behaves just like @code{ungetc} just that it
1502 Here is an example showing the use of @code{getc} and @code{ungetc} to
1516 /* @r{No need to check for @code{EOF} because it is not}
1517 @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.} */
1563 If @code{fread} encounters end of file in the middle of an object, it
1571 The @code{fread_unlocked} function is equivalent to the @code{fread}
1589 The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
1598 @cindex format string, for @code{printf}
1599 @cindex template, for @code{printf}
1602 The functions described in this section (@code{printf} and related
1604 call @code{printf} with a @dfn{format string} or @dfn{template string}
1608 character-oriented processing, using @code{printf} or one of the other
1626 * Variable Arguments Output:: @code{vprintf} and friends.
1629 * Example of Parsing:: Sample program using @code{parse_printf_format}.
1635 The @code{printf} function can be used to print any number of arguments.
1644 @cindex conversion specifications (@code{printf})
1662 an @code{int} argument should be printed in decimal notation, the
1696 specifications that can appear in a @code{printf} template
1704 The conversion specifications in a @code{printf} template string have
1722 print a @code{long int} argument in decimal notation, with a minimum of
1731 Normally the parameters to the @code{printf} function are assigned to the
1742 The value of @code{NL_ARGMAX} is the maximum value allowed for the
1743 specification of a positional parameter in a @code{printf} call. The
1745 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
1759 @cindex flag character (@code{printf})
1768 @cindex minimum field width (@code{printf})
1772 printed) is used as the field width. The value must be an @code{int}.
1781 @cindex precision (@code{printf})
1785 used as the precision. The value must be an @code{int}, and is ignored
1793 type. (For example, the integer conversions assume a type of @code{int},
1796 @cindex type modifier character (@code{printf})
1808 @code{printf} and related functions. It examines the format string and
1811 write uses a @code{printf}-style format string.
1817 @cindex output conversions, for @code{printf}
1825 output, but are different when used with @code{scanf} for input
1891 Print the string corresponding to the value of @code{errno}.
1915 @code{int} argument as a signed decimal number; while @samp{b}, @samp{%o},
1948 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1949 Integers}) and @code{scanf} with the @samp{%i} conversion
1957 the @code{LC_NUMERIC} category; @pxref{General Numeric}. This flag is a
1973 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1974 @code{unsigned int} (for the unsigned conversions @samp{%b},
1976 @samp{%x}, and @samp{%X}). Recall that since @code{printf} and friends
1977 are variadic, any @code{char} and @code{short} arguments are
1978 automatically converted to @code{int} by the default argument
1984 Specifies that the argument is a @code{signed char} or @code{unsigned
1985 char}, as appropriate. A @code{char} argument is converted to an
1986 @code{int} or @code{unsigned int} by the default argument promotions
1988 @code{char} again.
1993 Specifies that the argument is a @code{short int} or @code{unsigned
1994 short int}, as appropriate. A @code{short} argument is converted to an
1995 @code{int} or @code{unsigned int} by the default argument promotions
1997 @code{short} again.
2000 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
2006 Specifies that the argument is a @code{long int} or @code{unsigned long
2017 Specifies that the argument is a @code{long long int}. (This type is
2019 support extra-long integers, this is the same as @code{long int}.)
2022 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
2023 @code{int}.
2026 Specifies that the argument is a @code{ptrdiff_t}.
2032 Specifies that the argument is a @code{size_t}.
2035 predating this addition and should not be used in new code.
2081 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
2087 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
2096 the @samp{%f} style. A precision of @code{0}, is taken as 1.
2104 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
2106 This character is only @code{0} if the number is denormalized.
2112 adjacent values if the @code{FLT_RADIX} is not a power of 2,
2115 the prefix and exponent sign are printed as @code{0x} and @code{p}
2116 respectively. Otherwise upper-case characters are used and @code{0X}
2117 and @code{P} are used for the representation of prefix and exponent
2123 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
2125 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
2128 NaN; ISO C2X defines a macro @code{_PRINTF_NAN_LEN_MAX} giving the
2155 specified by the locale specified for the @code{LC_NUMERIC} category;
2166 these conversions, the default precision is @code{6}. If the precision
2167 is explicitly @code{0}, this suppresses the decimal point character
2171 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
2172 it is treated like a value of @code{1}. If the value being printed
2177 of type @code{double}. (By the default argument promotions, any
2178 @code{float} arguments are automatically converted to @code{double}.)
2183 An uppercase @samp{L} specifies that the argument is a @code{long
2215 This section describes miscellaneous conversions for @code{printf}.
2218 @samp{l} modifier the @code{int} argument is first converted to an
2219 @code{unsigned char}. Then, if used in a wide stream function, the
2233 of type @code{wint_t}. If used in a multibyte function the wide
2238 present the corresponding argument must be of type @code{char *} (or
2239 @code{const char *}). If used in a wide stream function the string is
2256 be of type @code{wchar_t} (or @code{const wchar_t *}).
2264 code in @code{errno}. @xref{Error Messages}. Thus:
2278 error constant, as provided by @code{strerrorname_np}. Both @samp{%m}
2282 argument must be of type @code{void *}. In practice, you can use any
2297 string constant @code{"testing"}. It does not print the word
2305 It uses an argument which must be a pointer to an @code{int}, but
2309 @code{short int *} or @code{long int *} instead of @code{int *}, but no
2327 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2339 This section describes how to call @code{printf} and related functions.
2350 The @code{printf} function prints the optional arguments under the
2352 @code{stdout}. It returns the number of characters printed, or a
2359 The @code{wprintf} function prints the optional arguments under the
2361 @code{stdout}. It returns the number of wide characters printed, or a
2368 This function is just like @code{printf}, except that the output is
2369 written to the stream @var{stream} instead of @code{stdout}.
2375 This function is just like @code{wprintf}, except that the output is
2376 written to the stream @var{stream} instead of @code{stdout}.
2382 This is like @code{printf}, except that the output is stored in the character
2386 The @code{sprintf} function returns the number of characters stored in
2394 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
2399 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2406 This is like @code{wprintf}, except that the output is stored in the
2417 @code{snprintf} handles this situation.
2420 parameters. @code{swprintf} in fact corresponds to the @code{snprintf}
2421 function. Since the @code{sprintf} function can be dangerous and should
2424 @code{sprintf}.
2430 The @code{snprintf} function is similar to @code{sprintf}, except that
2480 In practice, it is often easier just to use @code{asprintf}, below.
2485 store the result in which case @code{-1} is returned. This was
2498 This function is similar to @code{sprintf}, except that it dynamically
2499 allocates a string (as with @code{malloc}; @pxref{Unconstrained
2502 address of a @code{char *} object, and a successful call to
2503 @code{asprintf} stores a pointer to the newly allocated string at that
2510 Here is how to use @code{asprintf} to get the same result as the
2511 @code{snprintf} example, but more easily:
2530 This function is similar to @code{asprintf}, except that it uses the
2534 To get at them, you must finish the object with @code{obstack_finish}
2541 The functions @code{vprintf} and friends are provided so that you can
2542 define your own variadic @code{printf}-like functions that make use of
2546 construct to say, ``Call @code{printf} and pass this template plus all
2552 @code{vprintf} series, which lets you pass a @code{va_list} to describe
2568 Before calling @code{vprintf} or the other functions listed in this
2569 section, you @emph{must} call @code{va_start} (@pxref{Variadic
2571 can call @code{va_arg} to fetch the arguments that you want to handle
2574 Once your @code{va_list} pointer is pointing at the argument of your
2575 choice, you are ready to call @code{vprintf}. That argument and all
2577 @code{vprintf} along with the template that you specified separately.
2579 @strong{Portability Note:} The value of the @code{va_list} pointer is
2580 undetermined after the call to @code{vprintf}, so you must not use
2581 @code{va_arg} after you call @code{vprintf}. Instead, you should call
2582 @code{va_end} to retire the pointer from service. You can call
2583 @code{va_start} again and begin fetching the arguments from the start of
2584 the variable argument list. (Alternatively, you can use @code{va_copy}
2585 to make a copy of the @code{va_list} pointer before calling
2586 @code{vfprintf}.) Calling @code{vprintf} does not destroy the argument
2596 This function is similar to @code{printf} except that, instead of taking
2604 This function is similar to @code{wprintf} except that, instead of taking
2652 This is the equivalent of @code{fprintf} with the variable argument list
2653 specified directly as for @code{vprintf}.
2659 This is the equivalent of @code{fwprintf} with the variable argument list
2660 specified directly as for @code{vwprintf}.
2666 This is the equivalent of @code{sprintf} with the variable argument list
2667 specified directly as for @code{vprintf}.
2673 This is the equivalent of @code{swprintf} with the variable argument list
2674 specified directly as for @code{vwprintf}.
2680 This is the equivalent of @code{snprintf} with the variable argument list
2681 specified directly as for @code{vprintf}.
2687 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
2688 variable argument list specified directly as for @code{vprintf}.
2697 The @code{obstack_vprintf} function is the equivalent of
2698 @code{obstack_printf} with the variable argument list specified directly
2699 as for @code{vprintf}.
2702 Here's an example showing how you might use @code{vfprintf}. This is a
2703 function that prints error messages to the stream @code{stderr}, along
2706 @code{program_invocation_short_name}).
2728 You could call @code{eprintf} like this:
2735 know that a function uses a @code{printf}-style format string. Then it
2738 For example, take this declaration of @code{eprintf}:
2746 This tells the compiler that @code{eprintf} uses a format string like
2747 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
2757 You can use the function @code{parse_printf_format} to obtain
2760 provide interfaces to @code{printf} to avoid passing along invalid
2770 arguments expected by the @code{printf} template string @var{template}.
2777 @code{parse_printf_format} will try to write.
2779 @code{parse_printf_format} returns the total number of arguments required
2783 array and call @code{parse_printf_format} again.
2792 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
2793 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
2794 extract just the basic type code.
2800 @vtable @code
2803 This specifies that the base type is @code{int}.
2807 This specifies that the base type is @code{int}, cast to @code{char}.
2811 This specifies that the base type is @code{char *}, a null-terminated string.
2815 This specifies that the base type is @code{void *}, an arbitrary pointer.
2819 This specifies that the base type is @code{float}.
2823 This specifies that the base type is @code{double}.
2828 from @code{PA_LAST}. For example, if you have data types @samp{foo}
2829 and @samp{bar} with their own specialized @code{printf} conversions,
2839 the code for the basic type using inclusive-or.
2841 @vtable @code
2851 @code{short}. (This corresponds to the @samp{h} type modifier.)
2856 @code{long}. (This corresponds to the @samp{l} type modifier.)
2861 @code{long long}. (This corresponds to the @samp{L} type modifier.)
2865 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
2866 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
2878 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
2946 @section Customizing @code{printf}
2947 @cindex customizing @code{printf}
2948 @cindex defining new @code{printf} conversions
2949 @cindex extending @code{printf}
2952 for @code{printf} template strings, to teach @code{printf} clever ways
2956 @code{register_printf_function}; see @ref{Registering New Conversions}.
2969 * Registering New Conversions:: Using @code{register_printf_function}
2976 to @code{register_printf_function}.
2977 * Printf Extension Example:: How to define a @code{printf}
2979 * Predefined Printf Handlers:: Predefined @code{printf} handlers.
2983 @code{printf} template strings is a GNU extension. ISO standard C has
2994 @code{register_printf_function}, declared in @file{printf.h}.
3006 Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
3009 used as conversions; calling @code{register_printf_function} for those
3014 The @var{handler-function} is the function called by @code{printf} and
3021 @code{parse_printf_format} when this conversion appears in a
3030 @c but if you are never going to call @code{parse_printf_format}, you do
3035 the user used the @code{parse_printf_format} function. This has changed.
3036 Now a call to any of the @code{printf} functions will call this
3039 The return value is @code{0} on success, and @code{-1} on failure
3060 argument that points to a @code{struct printf_info}, which contains
3069 in an instance of a conversion specifier in a @code{printf} template
3073 @table @code
3075 This is the precision specified. The value is @code{-1} if no precision
3077 @code{printf_info} structure passed to the handler function contains the
3079 to the arginfo function contains a value of @code{INT_MIN}, since the
3083 This is the minimum field width specified. The value is @code{0} if no
3085 @code{printf_info} structure passed to the handler function contains the
3087 to the arginfo function contains a value of @code{INT_MIN}, since the
3099 @code{long long int}, as opposed to @code{long double} for floating
3129 the @code{printf} function this variable always contains the value
3130 @code{0}.
3137 width. The value is @code{'0'} if the @samp{0} flag was specified, and
3138 @code{' '} otherwise.
3147 which are passed as arguments to @code{register_printf_function}.
3151 @code{va_list *}.
3171 @c The @code{ap_pointer} argument is used to pass the tail of the variable
3174 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
3175 @c the @code{va_list} itself. Thus, you should fetch arguments by
3176 @c means of @code{va_arg (*ap_pointer, @var{type})}.
3179 @c function to update its own @code{va_list} variable to account for the
3186 Your handler function should return a value just like @code{printf}
3195 If you are going to use @w{@code{parse_printf_format}} in your
3198 @code{register_printf_function}.
3212 calling convention @code{parse_printf_format} itself uses.)
3221 @subsection @code{printf} Extension Example
3223 Here is an example showing how to define a @code{printf} handler function.
3224 This program defines a data structure called a @code{Widget} and
3225 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
3243 @subsection Predefined @code{printf} Handlers
3246 @code{printf} handler extension. There are two functions available
3257 Print a given floating point number as for the format @code{%f} except
3306 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
3309 Due to the requirements of @code{register_printf_function} we must also
3316 used parameters in the way the @code{vfprintf} implementation expects
3327 the format character @code{'B'} is an upper-case character. If we
3328 would additionally use @code{'b'} in a line like
3337 @code{printf_size} function knows about the difference between lower and upper
3340 The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is
3349 @cindex format string, for @code{scanf}
3350 @cindex template, for @code{scanf}
3351 The functions described in this section (@code{scanf} and related
3363 * Dynamic String Input:: String conversions that @code{malloc} the buffer.
3366 * Variable Arguments Input:: @code{vscanf} and friends.
3372 Calls to @code{scanf} are superficially similar to calls to
3373 @code{printf} in that arbitrary arguments are read under the control of
3375 the template is very similar to that for @code{printf}, the
3378 For example, most @code{scanf} conversions skip over any amount of
3385 @cindex conversion specifications (@code{scanf})
3387 Another area of difference between @code{scanf} and @code{printf} is
3389 as the optional arguments to @code{scanf}; the values that are read are
3392 getting strange errors that seem to be related to @code{scanf}, you
3395 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
3397 read from the stream. The normal return value from @code{scanf} is the
3400 @cindex matching failure, in @code{scanf}
3402 The @code{scanf} function is typically used for things like reading in
3404 @code{scanf} to initialize an array of @code{double}:
3425 @code{scanf}. For more information about these tools, see @ref{Top, , ,
3432 A @code{scanf} template string is a string that contains ordinary
3436 Any whitespace character (as defined by the @code{isspace} function;
3448 The conversion specifications in a @code{scanf} template string
3461 read for this specification. When @code{scanf} finds a conversion
3466 @cindex flag character (@code{scanf})
3483 @cindex maximum field width (@code{scanf})
3488 @samp{%d} to specify that the argument is a pointer to a @code{long int}
3489 rather than a pointer to an @code{int}.
3490 @cindex type modifier character (@code{scanf})
3502 @code{scanf} and related functions. It examines the format string and
3505 write uses a @code{scanf}-style format string.
3511 @cindex input conversions, for @code{scanf}
3547 string is converted as with multiple calls to @code{wcrtomb} into a
3549 @code{MB_CUR_MAX} bytes for each wide character read. In case
3551 wide characters as with multiple calls of @code{mbrtowc} before being
3563 string is converted as with multiple calls to @code{wcrtomb} into a
3565 @code{MB_CUR_MAX} bytes for each wide character read. In case
3567 wide characters as with multiple calls of @code{mbrtowc} before being
3579 to @code{MB_CUR_MAX} bytes for each character. If @samp{%lc} is used in
3581 not bytes) and the result is converted as with calls to @code{mbrtowc}.
3589 by the @samp{%p} output conversion for @code{printf}. @xref{Other Input
3611 This section describes the @code{scanf} conversions for reading numeric
3616 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3617 @code{10} for the @var{base} argument.
3622 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3623 @code{0} for the @var{base} argument. (You can print integers in this
3624 syntax with @code{printf} by using the @samp{#} flag character with the
3629 these specifies a number with decimal value @code{10}.
3633 syntax that is recognized is the same as that for the @code{strtoul}
3635 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
3640 The default type of the corresponding argument for the @code{%d},
3641 @code{%i}, and @code{%n} conversions is @code{int *}, and
3642 @code{unsigned int *} for the other integer conversions. You can use
3647 Specifies that the argument is a @code{signed char *} or @code{unsigned
3653 Specifies that the argument is a @code{short int *} or @code{unsigned
3657 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3662 Specifies that the argument is a @code{long int *} or @code{unsigned
3674 Specifies that the argument is a @code{long long int *} or @code{unsigned long long int *}. (The @…
3676 is the same as @code{long int}.)
3679 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
3680 @code{int}.
3683 Specifies that the argument is a @code{ptrdiff_t *}.
3688 Specifies that the argument is a @code{size_t *}.
3696 @code{strtod} function (@pxref{Parsing of Floats}).
3699 @code{float *}. (This is different from the corresponding output
3700 conversions, where the default type is @code{double}; remember that
3701 @code{float} arguments to @code{printf} are converted to @code{double}
3702 by the default argument promotions, but @code{float *} arguments are
3703 not promoted to @code{double *}.) You can specify other sizes of float
3708 Specifies that the argument is of type @code{double *}.
3711 Specifies that the argument is of type @code{long double *}.
3715 flag @samp{'}. When this flag is given the @code{scanf} function
3720 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
3728 This section describes the @code{scanf} input conversions for reading
3738 provide an argument of type @code{char *} or @code{wchar_t *} (the
3749 Ask @code{scanf} to allocate a big enough buffer, by specifying the
3751 an argument of type @code{char **} for the buffer address to be stored
3769 bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
3784 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
3786 @code{"hello,"}.
3799 of the width or precision by @code{MB_CUR_MAX}.
3864 @code{scanf} allocates a buffer big enough to hold the data and gives
3869 type @code{char **}. The @code{scanf} function allocates a buffer and
3871 free the buffer with @code{free} when you no longer need it.
3899 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
3901 argument should be of type @code{void **}; that is, the address of a
3908 by this call. The corresponding argument should be of type @code{int *},
3911 @code{printf}; see @ref{Other Output Conversions}, for an example.
3916 is stored for it since @code{scanf} returns before processing the
3917 @samp{%n}. If you store @code{-1} in that argument slot before calling
3918 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
3936 The @code{scanf} function reads formatted input from the stream
3937 @code{stdin} under the control of the template string @var{template}.
3944 template, then @code{EOF} is returned.
3950 The @code{wscanf} function reads formatted input from the stream
3951 @code{stdin} under the control of the template string @var{template}.
3958 template, then @code{WEOF} is returned.
3964 This function is just like @code{scanf}, except that the input is read
3965 from the stream @var{stream} instead of @code{stdin}.
3971 This function is just like @code{wscanf}, except that the input is read
3972 from the stream @var{stream} instead of @code{stdin}.
3978 This is like @code{scanf}, except that the characters are taken from the
3991 This is like @code{wscanf}, except that the characters are taken from the
4004 The functions @code{vscanf} and friends are provided so that you can
4005 define your own variadic @code{scanf}-like functions that make use of
4007 These functions are analogous to the @code{vprintf} series of output
4017 This function is similar to @code{scanf}, but instead of taking
4019 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
4025 This function is similar to @code{wscanf}, but instead of taking
4027 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
4033 This is the equivalent of @code{fscanf} with the variable argument list
4034 specified directly as for @code{vscanf}.
4040 This is the equivalent of @code{fwscanf} with the variable argument list
4041 specified directly as for @code{vwscanf}.
4047 This is the equivalent of @code{sscanf} with the variable argument list
4048 specified directly as for @code{vscanf}.
4054 This is the equivalent of @code{swscanf} with the variable argument list
4055 specified directly as for @code{vwscanf}.
4059 know that a function uses a @code{scanf}-style format string. Then it
4070 macro @code{EOF} to indicate unsuccessful completion of the operation.
4071 Since @code{EOF} is used to report both end of file and random errors,
4072 it's often better to use the @code{feof} function to check explicitly
4073 for end of file and @code{ferror} to check for errors. These functions
4082 error situation. With @theglibc{}, @code{EOF} is @code{-1}. In
4092 error situation. With @theglibc{}, @code{WEOF} is @code{-1}. In
4101 The @code{feof} function returns nonzero if and only if the end-of-file
4112 The @code{feof_unlocked} function is equivalent to the @code{feof}
4123 The @code{ferror} function returns nonzero if and only if the error
4133 The @code{ferror_unlocked} function is equivalent to the @code{ferror}
4142 the functions that operate on streams also set @code{errno} in the same
4145 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
4146 implemented in terms of @code{write}, and all of the @code{errno} error
4147 conditions defined for @code{write} are meaningful for these functions.
4154 You may explicitly clear the error and EOF flags with the @code{clearerr}
4170 The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
4191 One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
4194 signals with the @code{SA_RESTART} flag.
4214 @code{fopen}; see @ref{Opening Streams}. Without this
4215 option, @code{fopen} opens the file as a text stream.
4222 terminated by newline (@code{'\n'}) characters, while a binary stream is
4287 or if the file position can't be represented in a @code{long int}, and
4289 @code{-1} is returned.
4295 The @code{ftello} function is similar to @code{ftell}, except that it
4296 returns a value of type @code{off_t}. Systems which support this type
4301 @code{ftello} is preferable whenever it is available.
4303 If this function fails it returns @code{(off_t) -1}. This can happen due
4310 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4311 32 bit system this function is in fact @code{ftello64}. I.e., the
4318 This function is similar to @code{ftello} with the only difference that
4319 the return value is of type @code{off64_t}. This also requires that the
4320 stream @var{stream} was opened using either @code{fopen64},
4321 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
4325 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4326 bits machine this function is available under the name @code{ftello}
4333 The @code{fseek} function is used to change the file position of the
4335 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
4342 that were ``pushed back'' by the use of @code{ungetc}.
4344 @code{fseek} either flushes any buffered output before setting the file
4352 This function is similar to @code{fseek} but it corrects a problem with
4353 @code{fseek} in a system with POSIX types. Using a value of type
4354 @code{long int} for the offset is not compatible with POSIX.
4355 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
4358 For this reason it is a good idea to prefer @code{ftello} whenever it is
4362 The functionality and return value are the same as for @code{fseek}.
4367 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4368 32 bit system this function is in fact @code{fseeko64}. I.e., the
4375 This function is similar to @code{fseeko} with the only difference that
4376 the @var{offset} parameter is of type @code{off64_t}. This also
4378 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
4382 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4383 bits machine this function is available under the name @code{fseeko}
4387 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
4388 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
4392 argument to @code{fseek}. They are also used with the @code{lseek}
4399 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4406 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4413 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4420 The @code{rewind} function positions the stream @var{stream} at the
4421 beginning of the file. It is equivalent to calling @code{fseek} or
4422 @code{fseeko} on the @var{stream} with an @var{offset} argument of
4423 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
4432 @vtable @code
4435 An alias for @code{SEEK_SET}.
4439 An alias for @code{SEEK_CUR}.
4443 An alias for @code{SEEK_END}.
4450 can specify any character count value as an argument to @code{fseek} or
4451 @code{fseeko} and get reliable results for any random access file.
4466 The value returned from @code{ftell} on a text stream has no predictable
4469 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
4473 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
4474 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
4475 the @var{offset} must be the result of an earlier call to @code{ftell}
4480 while there are characters that have been pushed back with @code{ungetc}
4485 files, because @code{ftell} and @code{fseek} use a @code{long int} value
4487 all the file positions in a large file. Using the @code{ftello} and
4488 @code{fseeko} functions might help here since the @code{off_t} type is
4494 file positions, it is better to use the functions @code{fgetpos} and
4495 @code{fsetpos} instead. These functions represent the file position
4496 using the data type @code{fpos_t}, whose internal representation varies
4505 file position of a stream, for use by the functions @code{fgetpos} and
4506 @code{fsetpos}.
4508 In @theglibc{}, @code{fpos_t} is an opaque data structure that
4513 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
4514 this type is in fact equivalent to @code{fpos64_t} since the LFS
4521 file position of a stream, for use by the functions @code{fgetpos64} and
4522 @code{fsetpos64}.
4524 In @theglibc{}, @code{fpos64_t} is an opaque data structure that
4534 stream @var{stream} in the @code{fpos_t} object pointed to by
4535 @var{position}. If successful, @code{fgetpos} returns zero; otherwise
4537 value in @code{errno}.
4539 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4540 32 bit system the function is in fact @code{fgetpos64}. I.e., the LFS
4547 This function is similar to @code{fgetpos} but the file position is
4548 returned in a variable of type @code{fpos64_t} to which @var{position}
4551 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4552 bits machine this function is available under the name @code{fgetpos}
4561 call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
4563 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
4564 of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores
4565 an implementation-defined positive value in @code{errno}.
4567 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4568 32 bit system the function is in fact @code{fsetpos64}. I.e., the LFS
4575 This function is similar to @code{fsetpos} but the file position used
4576 for positioning is provided in a variable of type @code{fpos64_t} to
4579 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4580 bits machine this function is available under the name @code{fsetpos}
4649 should flush buffered output explicitly with @code{fflush}, as described
4668 When the program terminates by calling @code{exit}.
4680 @code{fflush}, which is declared in the header file @file{stdio.h}.
4688 @code{fflush} causes buffered output on @emph{all} open output streams
4691 This function returns @code{EOF} if a write error occurs, or zero
4698 The @code{fflush_unlocked} function is equivalent to the @code{fflush}
4702 The @code{fflush} function can be used to flush all streams currently
4714 The @code{_flushlbf} function flushes all line buffered streams
4735 The @code{__fpurge} function causes the buffer of the stream
4749 want it to have using the @code{setvbuf} function.
4760 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
4761 (for full buffering), @code{_IOLBF} (for line buffering), or
4762 @code{_IONBF} (for unbuffered input/output).
4764 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
4765 allocates a buffer itself using @code{malloc}. This buffer will be freed
4771 should usually either allocate it statically, or @code{malloc}
4781 The @code{setvbuf} function returns zero on success, or a nonzero value
4789 used as the @var{mode} argument to the @code{setvbuf} function to
4796 used as the @var{mode} argument to the @code{setvbuf} function to
4803 used as the @var{mode} argument to the @code{setvbuf} function to
4810 to use for the @var{size} argument to @code{setvbuf}. This value is
4811 guaranteed to be at least @code{256}.
4813 The value of @code{BUFSIZ} is chosen on each system so as to make stream
4814 I/O efficient. So it is a good idea to use @code{BUFSIZ} as the size
4815 for the buffer when you call @code{setvbuf}.
4818 by means of the @code{fstat} system call: it is found in the
4819 @code{st_blksize} field of the file attributes. @xref{Attribute Meanings}.
4821 Sometimes people also use @code{BUFSIZ} as the allocation size of
4823 line of input with @code{fgets} (@pxref{Character Input}). There is no
4824 particular reason to use @code{BUFSIZ} for this instead of any other
4833 equivalent to calling @code{setvbuf} with a @var{mode} argument of
4834 @code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
4835 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
4836 argument of @code{BUFSIZ}.
4838 The @code{setbuf} function is provided for compatibility with old code;
4839 use @code{setvbuf} in all new programs.
4849 This function is provided for compatibility with old BSD code. Use
4850 @code{setvbuf} instead.
4859 This function is provided for compatibility with old BSD code. Use
4860 @code{setvbuf} instead.
4870 The @code{__flbf} function will return a nonzero value in case the
4883 The @code{__fbufsize} function return the size of the buffer in the
4893 The @code{__fpending}
4909 @code{sprintf} and @code{sscanf} functions. You can also create such a
4932 The @code{fmemopen} and @code{open_memstream} functions allow you to do
4947 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
4948 dynamically allocates an array @var{size} bytes long (as with @code{malloc};
4952 buffer (for this, try @code{open_memstream}, below). The buffer is
4955 The argument @var{opentype} is the same as in @code{fopen}
4974 Here is an example of using @code{fmemopen} to create a stream for
4996 allocated dynamically and grown as necessary, using @code{malloc}.
4998 clean up using @code{free} or @code{realloc}. @xref{Unconstrained Allocation}.
5000 When the stream is closed with @code{fclose} or flushed with
5001 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
5010 You can move the stream's file position with @code{fseek} or
5011 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
5016 Here is an example of using @code{open_memstream}:
5057 they record its address with type @code{void *}.
5069 @code{cookie_io_functions_t}.
5080 @table @code
5084 always return @code{EOF}.
5094 to @code{fseek} or @code{fseeko} on this stream can only seek to
5096 return an @code{ESPIPE} error.
5111 The @var{opentype} argument is interpreted as for @code{fopen};
5115 The @code{fopencookie} function returns the newly created stream, or a null
5132 This is very similar to the @code{read} function; see @ref{I/O
5135 indicate end-of-file. You can return a value of @code{-1} to indicate
5144 This is very similar to the @code{write} function; see @ref{I/O
5147 value of @code{0} to indicate an error. You must not return any
5158 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
5162 Your function should return a value of @code{0} on success and @code{-1}
5172 Your function should return @code{-1} to indicate an error, and @code{0}
5220 the system tools) are printed in a strict form using the @code{fmtmsg}
5222 and the strictness tests of the @code{fmtmsg} function ensure that the
5226 * Printing Formatted Messages:: The @code{fmtmsg} function.
5228 * Example:: How to use @code{fmtmsg} and @code{addseverity}.
5238 @code{fmtmsg}:
5240 @vtable @code
5249 @var{classification} parameter to @code{fmtmsg}:
5251 @vtable @code
5260 A third component of the @var{classification} parameter to @code{fmtmsg}
5264 @vtable @code
5276 @vtable @code
5300 @vtable @code
5324 @vtable @code
5326 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
5328 This value is printed as @code{HALT}.
5330 This value is printed as @code{ERROR}.
5332 This value is printed as @code{WARNING}.
5334 This value is printed as @code{INFO}.
5337 The numeric value of these five macros are between @code{0} and
5338 @code{4}. Using the environment variable @code{SEV_LEVEL} or using the
5339 @code{addseverity} function one can add more severity levels with their
5351 The colons, new line characters and the @code{TO FIX} string are
5358 The function returns the value @code{MM_OK} if no error occurred. If
5359 only the printing to standard error failed, it returns @code{MM_NOMSG}.
5360 If printing to the console fails, it returns @code{MM_NOCON}. If
5361 nothing is printed @code{MM_NOTOK} is returned. Among situations where
5367 @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
5370 this the user has to put the @code{MSGVERB} variable with a format like
5371 the following in the environment before calling the @code{fmtmsg} function
5378 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
5379 @code{action}, and @code{tag}. If the environment variable is not given
5384 @code{fmtmsg} is @code{SEV_LEVEL}. This variable and the change in the
5385 behavior of @code{fmtmsg} is not specified in the X/Open Portability
5389 @code{fmtmsg} print nothing.
5391 If the user puts @code{SEV_LEVEL} with a format like
5399 @code{fmtmsg}, where @var{description} has a value of the form
5405 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
5408 must be used in the @var{severity} parameter of @code{fmtmsg} to select
5411 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
5420 the environment variable @code{SEV_LEVEL}. This simplifies the task of
5422 @code{setenv} or @code{putenv} function to set the environment variable,
5428 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
5429 The @var{severity} parameter of @code{addseverity} must match the value
5430 for the parameter with the same name of @code{fmtmsg}, and @var{string}
5434 If @var{string} is @code{NULL} the severity class with the numeric value
5438 classes. All calls to @code{addseverity} with @var{severity} set to one
5441 The return value is @code{MM_OK} if the task was successfully performed.
5442 If the return value is @code{MM_NOTOK} something went wrong. This could
5447 the @code{fmtsmg} function is. It is available on System V systems.
5452 @subsection How to use @code{fmtmsg} and @code{addseverity}
5461 The second call to @code{fmtmsg} illustrates a use of this function as
5465 @var{label} field (@code{UX:cat}) says that the error occurred in the
5466 Unix program @code{cat}. The explanation of the error follows and the
5467 value for the @var{action} parameter is @code{"refer to manual"}. One
5470 parameter, and additionally a unique ID (@code{001} in this case). For
5475 Running this program without specifying the @code{MSGVERB} and
5476 @code{SEV_LEVEL} function produces the following output:
5484 colons and the @code{TO FIX} string) is printed. But only one of the
5485 three calls to @code{fmtmsg} produced output. The first call does not
5488 (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
5489 produced no output since the class with the numeric value @code{6} is
5490 not defined. Although a class with numeric value @code{5} is also not
5491 defined by default, the call to @code{addseverity} introduces it and
5492 the second call to @code{fmtmsg} produces the above output.
5495 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
5504 Now the third call to @code{fmtmsg} produced some output and we see how
5505 the string @code{NOTE} from the environment variable appears in the
5510 @code{MSGVERB} to the value @code{severity:label:action} we get the
5522 to @code{fmtmsg} vanished. Please also note that now there is no colon
5523 after the @code{NOTE} and @code{NOTE2} strings in the output. This is