| .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) |
| .\" |
| .\" Earlier versions of this page influenced the present text. |
| .\" It was derived from a Berkeley page with version |
| .\" @(#)printf.3 6.14 (Berkeley) 7/30/91 |
| .\" converted for Linux by faith@cs.unc.edu, updated by |
| .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. |
| .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes |
| .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes |
| .\" |
| .TH PRINTF 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, |
| vsprintf, vsnprintf \- formatted output conversion |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdio.h> |
| .PP |
| .BI "int printf(const char *" format ", ...);" |
| .BI "int fprintf(FILE *" stream ", const char *" format ", ...);" |
| .BI "int dprintf(int " fd ", const char *" format ", ...);" |
| .BI "int sprintf(char *" str ", const char *" format ", ...);" |
| .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);" |
| |
| .B #include <stdarg.h> |
| .PP |
| .BI "int vprintf(const char *" format ", va_list " ap ); |
| .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap ); |
| .BI "int vdprintf(int " fd ", const char *" format ", va_list " ap ); |
| .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap ); |
| .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \ |
| ", va_list " ap ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .ad l |
| .BR snprintf (), |
| .BR vsnprintf (): |
| .RS 4 |
| _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE || |
| || /* Glibc versions <= 2.19: */ _BSD_SOURCE |
| .RE |
| .PP |
| .BR dprintf (), |
| .BR vdprintf (): |
| .PD 0 |
| .RS 4 |
| .TP 4 |
| Since glibc 2.10: |
| _POSIX_C_SOURCE\ >=\ 200809L |
| .TP |
| Before glibc 2.10: |
| _GNU_SOURCE |
| .RE |
| .ad |
| .PD |
| .SH DESCRIPTION |
| The functions in the |
| .BR printf () |
| family produce output according to a |
| .I format |
| as described below. |
| The functions |
| .BR printf () |
| and |
| .BR vprintf () |
| write output to |
| .IR stdout , |
| the standard output stream; |
| .BR fprintf () |
| and |
| .BR vfprintf () |
| write output to the given output |
| .IR stream ; |
| .BR sprintf (), |
| .BR snprintf (), |
| .BR vsprintf () |
| and |
| .BR vsnprintf () |
| write to the character string |
| .IR str . |
| .PP |
| The function |
| .BR dprintf () |
| is the same as |
| .BR fprintf () |
| except that it outputs to a file descriptor, |
| .IR fd , |
| instead of to a |
| .I stdio |
| stream. |
| .PP |
| The functions |
| .BR snprintf () |
| and |
| .BR vsnprintf () |
| write at most |
| .I size |
| bytes (including the terminating null byte (\(aq\e0\(aq)) to |
| .IR str . |
| .PP |
| The functions |
| .BR vprintf (), |
| .BR vfprintf (), |
| .BR vdprintf (), |
| .BR vsprintf (), |
| .BR vsnprintf () |
| are equivalent to the functions |
| .BR printf (), |
| .BR fprintf (), |
| .BR dprintf (), |
| .BR sprintf (), |
| .BR snprintf (), |
| respectively, except that they are called with a |
| .I va_list |
| instead of a variable number of arguments. |
| These functions do not call the |
| .I va_end |
| macro. |
| Because they invoke the |
| .I va_arg |
| macro, the value of |
| .I ap |
| is undefined after the call. |
| See |
| .BR stdarg (3). |
| .PP |
| All of these functions write the output under the control of a |
| .I format |
| string that specifies how subsequent arguments (or arguments accessed via |
| the variable-length argument facilities of |
| .BR stdarg (3)) |
| are converted for output. |
| .PP |
| C99 and POSIX.1-2001 specify that the results are undefined if a call to |
| .BR sprintf (), |
| .BR snprintf (), |
| .BR vsprintf (), |
| or |
| .BR vsnprintf () |
| would cause copying to take place between objects that overlap |
| (e.g., if the target string array and one of the supplied input arguments |
| refer to the same buffer). |
| See NOTES. |
| .SS Format of the format string |
| The format string is a character string, beginning and ending |
| in its initial shift state, if any. |
| The format string is composed of zero or more directives: ordinary |
| characters (not |
| .BR % ), |
| which are copied unchanged to the output stream; |
| and conversion specifications, each of which results in fetching zero or |
| more subsequent arguments. |
| Each conversion specification is introduced by |
| the character |
| .BR % , |
| and ends with a |
| .IR "conversion specifier" . |
| In between there may be (in this order) zero or more |
| .IR flags , |
| an optional minimum |
| .IR "field width" , |
| an optional |
| .I precision |
| and an optional |
| .IR "length modifier" . |
| .PP |
| The arguments must correspond properly (after type promotion) with the |
| conversion specifier. |
| By default, the arguments are used in the order |
| given, where each \(aq*\(aq (see |
| .I "Field width" |
| and |
| .I Precision |
| below) and each conversion specifier asks for the next |
| argument (and it is an error if insufficiently many arguments are given). |
| One can also specify explicitly which argument is taken, |
| at each place where an argument is required, by writing "%m$" instead |
| of \(aq%\(aq and "*m$" instead of \(aq*\(aq, |
| where the decimal integer \fIm\fP denotes |
| the position in the argument list of the desired argument, indexed starting |
| from 1. |
| Thus, |
| .PP |
| .in +4n |
| .EX |
| printf("%*d", width, num); |
| .EE |
| .in |
| .PP |
| and |
| .PP |
| .in +4n |
| .EX |
| printf("%2$*1$d", width, num); |
| .EE |
| .in |
| .PP |
| are equivalent. |
| The second style allows repeated references to the |
| same argument. |
| The C99 standard does not include the style using \(aq$\(aq, |
| which comes from the Single UNIX Specification. |
| If the style using |
| \(aq$\(aq is used, it must be used throughout for all conversions taking an |
| argument and all width and precision arguments, but it may be mixed |
| with "%%" formats, which do not consume an argument. |
| There may be no |
| gaps in the numbers of arguments specified using \(aq$\(aq; for example, if |
| arguments 1 and 3 are specified, argument 2 must also be specified |
| somewhere in the format string. |
| .PP |
| For some numeric conversions a radix character ("decimal point") or |
| thousands' grouping character is used. |
| The actual character used |
| depends on the |
| .B LC_NUMERIC |
| part of the locale. |
| (See |
| .BR setlocale (3).) |
| The POSIX locale |
| uses \(aq.\(aq as radix character, and does not have a grouping character. |
| Thus, |
| .PP |
| .in +4n |
| .EX |
| printf("%\(aq.2f", 1234567.89); |
| .EE |
| .in |
| .PP |
| results in "1234567.89" in the POSIX locale, in "1234567,89" in the |
| nl_NL locale, and in "1.234.567,89" in the da_DK locale. |
| .SS Flag characters |
| The character % is followed by zero or more of the following flags: |
| .TP |
| .B # |
| The value should be converted to an "alternate form". |
| For |
| .B o |
| conversions, the first character of the output string is made zero |
| (by prefixing a 0 if it was not zero already). |
| For |
| .B x |
| and |
| .B X |
| conversions, a nonzero result has the string "0x" (or "0X" for |
| .B X |
| conversions) prepended to it. |
| For |
| .BR a , |
| .BR A , |
| .BR e , |
| .BR E , |
| .BR f , |
| .BR F , |
| .BR g , |
| and |
| .B G |
| conversions, the result will always contain a decimal point, even if no |
| digits follow it (normally, a decimal point appears in the results of those |
| conversions only if a digit follows). |
| For |
| .B g |
| and |
| .B G |
| conversions, trailing zeros are not removed from the result as they would |
| otherwise be. |
| For other conversions, the result is undefined. |
| .TP |
| .B \&0 |
| The value should be zero padded. |
| For |
| .BR d , |
| .BR i , |
| .BR o , |
| .BR u , |
| .BR x , |
| .BR X , |
| .BR a , |
| .BR A , |
| .BR e , |
| .BR E , |
| .BR f , |
| .BR F , |
| .BR g , |
| and |
| .B G |
| conversions, the converted value is padded on the left with zeros rather |
| than blanks. |
| If the |
| .B \&0 |
| and |
| .B \- |
| flags both appear, the |
| .B \&0 |
| flag is ignored. |
| If a precision is given with a numeric conversion |
| .RB ( d , |
| .BR i , |
| .BR o , |
| .BR u , |
| .BR x , |
| and |
| .BR X ), |
| the |
| .B \&0 |
| flag is ignored. |
| For other conversions, the behavior is undefined. |
| .TP |
| .B \- |
| The converted value is to be left adjusted on the field boundary. |
| (The default is right justification.) |
| The converted value is padded on the right with blanks, rather |
| than on the left with blanks or zeros. |
| A |
| .B \- |
| overrides a |
| .B \&0 |
| if both are given. |
| .TP |
| .B \(aq \(aq |
| (a space) A blank should be left before a positive number |
| (or empty string) produced by a signed conversion. |
| .TP |
| .B + |
| A sign (+ or \-) should always be placed before a number produced by a signed |
| conversion. |
| By default, a sign is used only for negative numbers. |
| A |
| .B + |
| overrides a space if both are used. |
| .PP |
| The five flag characters above are defined in the C99 standard. |
| The Single UNIX Specification specifies one further flag character. |
| .TP |
| .B \(aq |
| For decimal conversion |
| .RB ( i , |
| .BR d , |
| .BR u , |
| .BR f , |
| .BR F , |
| .BR g , |
| .BR G ) |
| the output is to be grouped with thousands' grouping characters |
| if the locale information indicates any. |
| (See |
| .BR setlocale (3).) |
| Note that many versions of |
| .BR gcc (1) |
| cannot parse this option and will issue a warning. |
| (SUSv2 did not |
| include \fI%\(aqF\fP, but SUSv3 added it.) |
| .PP |
| glibc 2.2 adds one further flag character. |
| .TP |
| .B I |
| For decimal integer conversion |
| .RB ( i , |
| .BR d , |
| .BR u ) |
| the output uses the locale's alternative output digits, if any. |
| For example, since glibc 2.2.3 this will give Arabic-Indic digits |
| in the Persian ("fa_IR") locale. |
| .\" outdigits keyword in locale file |
| .SS Field width |
| An optional decimal digit string (with nonzero first digit) specifying |
| a minimum field width. |
| If the converted value has fewer characters |
| than the field width, it will be padded with spaces on the left |
| (or right, if the left-adjustment flag has been given). |
| Instead of a decimal digit string one may write "*" or "*m$" |
| (for some decimal integer \fIm\fP) to specify that the field width |
| is given in the next argument, or in the \fIm\fP-th argument, respectively, |
| which must be of type |
| .IR int . |
| A negative field width is taken as a \(aq\-\(aq flag followed by a |
| positive field width. |
| In no case does a nonexistent or small field width cause truncation of a |
| field; if the result of a conversion is wider than the field width, the |
| field is expanded to contain the conversion result. |
| .SS Precision |
| An optional precision, in the form of a period (\(aq.\(aq) followed by an |
| optional decimal digit string. |
| Instead of a decimal digit string one may write "*" or "*m$" |
| (for some decimal integer \fIm\fP) to specify that the precision |
| is given in the next argument, or in the \fIm\fP-th argument, respectively, |
| which must be of type |
| .IR int . |
| If the precision is given as just \(aq.\(aq, the precision is taken to |
| be zero. |
| A negative precision is taken as if the precision were omitted. |
| This gives the minimum number of digits to appear for |
| .BR d , |
| .BR i , |
| .BR o , |
| .BR u , |
| .BR x , |
| and |
| .B X |
| conversions, the number of digits to appear after the radix character for |
| .BR a , |
| .BR A , |
| .BR e , |
| .BR E , |
| .BR f , |
| and |
| .B F |
| conversions, the maximum number of significant digits for |
| .B g |
| and |
| .B G |
| conversions, or the maximum number of characters to be printed from a |
| string for |
| .B s |
| and |
| .B S |
| conversions. |
| .SS Length modifier |
| Here, "integer conversion" stands for |
| .BR d , |
| .BR i , |
| .BR o , |
| .BR u , |
| .BR x , |
| or |
| .B X |
| conversion. |
| .TP |
| .B hh |
| A following integer conversion corresponds to a |
| .I signed char |
| or |
| .I unsigned char |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to a |
| .I signed char |
| argument. |
| .TP |
| .B h |
| A following integer conversion corresponds to a |
| .I short int |
| or |
| .I unsigned short int |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to a |
| .I short int |
| argument. |
| .TP |
| .B l |
| (ell) A following integer conversion corresponds to a |
| .I long int |
| or |
| .I unsigned long int |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to a |
| .I long int |
| argument, or a following |
| .B c |
| conversion corresponds to a |
| .I wint_t |
| argument, or a following |
| .B s |
| conversion corresponds to a pointer to |
| .I wchar_t |
| argument. |
| .TP |
| .B ll |
| (ell-ell). |
| A following integer conversion corresponds to a |
| .I long long int |
| or |
| .I unsigned long long int |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to a |
| .I long long int |
| argument. |
| .TP |
| .B q |
| A synonym for |
| .BR ll . |
| This is a nonstandard extension, derived from BSD; |
| avoid its use in new code. |
| .TP |
| .B L |
| A following |
| .BR a , |
| .BR A , |
| .BR e , |
| .BR E , |
| .BR f , |
| .BR F , |
| .BR g , |
| or |
| .B G |
| conversion corresponds to a |
| .I long double |
| argument. |
| (C99 allows %LF, but SUSv2 does not.) |
| .TP |
| .B j |
| A following integer conversion corresponds to an |
| .I intmax_t |
| or |
| .I uintmax_t |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to an |
| .I intmax_t |
| argument. |
| .TP |
| .B z |
| A following integer conversion corresponds to a |
| .I size_t |
| or |
| .I ssize_t |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to a |
| .I size_t |
| argument. |
| .TP |
| .B Z |
| A nonstandard synonym for |
| .BR z |
| that predates the appearance of |
| .BR z . |
| Do not use in new code. |
| .TP |
| .B t |
| A following integer conversion corresponds to a |
| .I ptrdiff_t |
| argument, or a following |
| .B n |
| conversion corresponds to a pointer to a |
| .I ptrdiff_t |
| argument. |
| .PP |
| SUSv3 specifies all of the above, |
| except for those modifiers explicitly noted as being nonstandard extensions. |
| SUSv2 specified only the length modifiers |
| .B h |
| (in |
| .BR hd , |
| .BR hi , |
| .BR ho , |
| .BR hx , |
| .BR hX , |
| .BR hn ) |
| and |
| .B l |
| (in |
| .BR ld , |
| .BR li , |
| .BR lo , |
| .BR lx , |
| .BR lX , |
| .BR ln , |
| .BR lc , |
| .BR ls ) |
| and |
| .B L |
| (in |
| .BR Le , |
| .BR LE , |
| .BR Lf , |
| .BR Lg , |
| .BR LG ). |
| .PP |
| As a nonstandard extension, the GNU implementations treats |
| .B ll |
| and |
| .B L |
| as synonyms, so that one can, for example, write |
| .BR llg |
| (as a synonym for the standards-compliant |
| .RB Lg ) |
| and |
| .BR Ld |
| (as a synonym for the standards compliant |
| .BR lld ). |
| Such usage is nonportable. |
| .\" |
| .SS Conversion specifiers |
| A character that specifies the type of conversion to be applied. |
| The conversion specifiers and their meanings are: |
| .TP |
| .BR d ", " i |
| The |
| .I int |
| argument is converted to signed decimal notation. |
| The precision, if any, gives the minimum number of digits |
| that must appear; if the converted value requires fewer digits, it is |
| padded on the left with zeros. |
| The default precision is 1. |
| When 0 is printed with an explicit precision 0, the output is empty. |
| .TP |
| .BR o ", " u ", " x ", " X |
| The |
| .I "unsigned int" |
| argument is converted to unsigned octal |
| .RB ( o ), |
| unsigned decimal |
| .RB ( u ), |
| or unsigned hexadecimal |
| .RB ( x |
| and |
| .BR X ) |
| notation. |
| The letters |
| .B abcdef |
| are used for |
| .B x |
| conversions; the letters |
| .B ABCDEF |
| are used for |
| .B X |
| conversions. |
| The precision, if any, gives the minimum number of digits |
| that must appear; if the converted value requires fewer digits, it is |
| padded on the left with zeros. |
| The default precision is 1. |
| When 0 is printed with an explicit precision 0, the output is empty. |
| .TP |
| .BR e ", " E |
| The |
| .I double |
| argument is rounded and converted in the style |
| .RB [\-]d \&. ddd e \(+-dd |
| where there is one digit before the decimal-point character and the number |
| of digits after it is equal to the precision; if the precision is missing, |
| it is taken as 6; if the precision is zero, no decimal-point character |
| appears. |
| An |
| .B E |
| conversion uses the letter |
| .B E |
| (rather than |
| .BR e ) |
| to introduce the exponent. |
| The exponent always contains at least two |
| digits; if the value is zero, the exponent is 00. |
| .TP |
| .BR f ", " F |
| The |
| .I double |
| argument is rounded and converted to decimal notation in the style |
| .RB [\-]ddd \&. ddd, |
| where the number of digits after the decimal-point character is equal to |
| the precision specification. |
| If the precision is missing, it is taken as |
| 6; if the precision is explicitly zero, no decimal-point character appears. |
| If a decimal point appears, at least one digit appears before it. |
| .IP |
| (SUSv2 does not know about |
| .B F |
| and says that character string representations for infinity and NaN |
| may be made available. |
| SUSv3 adds a specification for |
| .BR F . |
| The C99 standard specifies "[\-]inf" or "[\-]infinity" |
| for infinity, and a string starting with "nan" for NaN, in the case of |
| .B f |
| conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of |
| .B F |
| conversion.) |
| .TP |
| .BR g ", " G |
| The |
| .I double |
| argument is converted in style |
| .B f |
| or |
| .B e |
| (or |
| .B F |
| or |
| .B E |
| for |
| .B G |
| conversions). |
| The precision specifies the number of significant digits. |
| If the precision is missing, 6 digits are given; if the precision is zero, |
| it is treated as 1. |
| Style |
| .B e |
| is used if the exponent from its conversion is less than \-4 or greater |
| than or equal to the precision. |
| Trailing zeros are removed from the |
| fractional part of the result; a decimal point appears only if it is |
| followed by at least one digit. |
| .TP |
| .BR a ", " A |
| (C99; not in SUSv2, but added in SUSv3) |
| For |
| .B a |
| conversion, the |
| .I double |
| argument is converted to hexadecimal notation (using the letters abcdef) |
| in the style |
| .RB [\-] 0x h \&. hhhh p \(+-; |
| for |
| .B A |
| conversion the prefix |
| .BR 0X , |
| the letters ABCDEF, and the exponent separator |
| .B P |
| is used. |
| There is one hexadecimal digit before the decimal point, |
| and the number of digits after it is equal to the precision. |
| The default precision suffices for an exact representation of the value |
| if an exact representation in base 2 exists |
| and otherwise is sufficiently large to distinguish values of type |
| .IR double . |
| The digit before the decimal point is unspecified for nonnormalized |
| numbers, and nonzero but otherwise unspecified for normalized numbers. |
| .TP |
| .B c |
| If no |
| .B l |
| modifier is present, the |
| .I int |
| argument is converted to an |
| .IR "unsigned char" , |
| and the resulting character is written. |
| If an |
| .B l |
| modifier is present, the |
| .I wint_t |
| (wide character) argument is converted to a multibyte sequence by a call |
| to the |
| .BR wcrtomb (3) |
| function, with a conversion state starting in the initial state, and the |
| resulting multibyte string is written. |
| .TP |
| .B s |
| If no |
| .B l |
| modifier is present: the |
| .I "const char\ *" |
| argument is expected to be a pointer to an array of character type (pointer |
| to a string). |
| Characters from the array are written up to (but not |
| including) a terminating null byte (\(aq\e0\(aq); |
| if a precision is specified, no more than the number specified |
| are written. |
| If a precision is given, no null byte need be present; |
| if the precision is not specified, or is greater than the size of the |
| array, the array must contain a terminating null byte. |
| .IP |
| If an |
| .B l |
| modifier is present: the |
| .I "const wchar_t\ *" |
| argument is expected to be a pointer to an array of wide characters. |
| Wide characters from the array are converted to multibyte characters |
| (each by a call to the |
| .BR wcrtomb (3) |
| function, with a conversion state starting in the initial state before |
| the first wide character), up to and including a terminating null |
| wide character. |
| The resulting multibyte characters are written up to |
| (but not including) the terminating null byte. |
| If a precision is |
| specified, no more bytes than the number specified are written, but |
| no partial multibyte characters are written. |
| Note that the precision |
| determines the number of |
| .I bytes |
| written, not the number of |
| .I wide characters |
| or |
| .IR "screen positions" . |
| The array must contain a terminating null wide character, unless a |
| precision is given and it is so small that the number of bytes written |
| exceeds it before the end of the array is reached. |
| .TP |
| .B C |
| (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) |
| Synonym for |
| .BR lc . |
| Don't use. |
| .TP |
| .B S |
| (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) |
| Synonym for |
| .BR ls . |
| Don't use. |
| .TP |
| .B p |
| The |
| .I "void\ *" |
| pointer argument is printed in hexadecimal (as if by |
| .B %#x |
| or |
| .BR %#lx ). |
| .TP |
| .B n |
| The number of characters written so far is stored into the integer |
| pointed to by the corresponding argument. |
| That argument shall be an |
| .IR "int\ *" , |
| or variant whose size matches the (optionally) |
| supplied integer length modifier. |
| No argument is converted. |
| (This specifier is not supported by the bionic C library.) |
| The behavior is undefined if the conversion specification includes |
| any flags, a field width, or a precision. |
| .TP |
| .B m |
| (Glibc extension; supported by uClibc and musl.) |
| Print output of |
| .IR strerror(errno) . |
| No argument is required. |
| .TP |
| .B % |
| A \(aq%\(aq is written. |
| No argument is converted. |
| The complete conversion |
| specification is \(aq%%\(aq. |
| .SH RETURN VALUE |
| Upon successful return, these functions return the number of characters |
| printed (excluding the null byte used to end output to strings). |
| .PP |
| The functions |
| .BR snprintf () |
| and |
| .BR vsnprintf () |
| do not write more than |
| .I size |
| bytes (including the terminating null byte (\(aq\e0\(aq)). |
| If the output was truncated due to this limit, then the return value |
| is the number of characters (excluding the terminating null byte) |
| which would have been written to the final string if enough space |
| had been available. |
| Thus, a return value of |
| .I size |
| or more means that the output was truncated. |
| (See also below under NOTES.) |
| .PP |
| If an output error is encountered, a negative value is returned. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw23 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR printf (), |
| .BR fprintf (), |
| .br |
| .BR sprintf (), |
| .BR snprintf (), |
| .br |
| .BR vprintf (), |
| .BR vfprintf (), |
| .br |
| .BR vsprintf (), |
| .BR vsnprintf () |
| T} Thread safety MT-Safe locale |
| .TE |
| .sp 1 |
| .SH CONFORMING TO |
| .BR fprintf (), |
| .BR printf (), |
| .BR sprintf (), |
| .BR vprintf (), |
| .BR vfprintf (), |
| .BR vsprintf (): |
| POSIX.1-2001, POSIX.1-2008, C89, C99. |
| .PP |
| .BR snprintf (), |
| .BR vsnprintf (): |
| POSIX.1-2001, POSIX.1-2008, C99. |
| .PP |
| The |
| .BR dprintf () |
| and |
| .BR vdprintf () |
| functions were originally GNU extensions that were later standardized |
| in POSIX.1-2008. |
| .PP |
| Concerning the return value of |
| .BR snprintf (), |
| SUSv2 and C99 contradict each other: when |
| .BR snprintf () |
| is called with |
| .IR size =0 |
| then SUSv2 stipulates an unspecified return value less than 1, |
| while C99 allows |
| .I str |
| to be NULL in this case, and gives the return value (as always) |
| as the number of characters that would have been written in case |
| the output string has been large enough. |
| POSIX.1-2001 and later align their specification of |
| .BR snprintf () |
| with C99. |
| .\" .PP |
| .\" Linux libc4 knows about the five C standard flags. |
| .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, |
| .\" and the conversions |
| .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, |
| .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP, |
| .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP, |
| .\" where \fBF\fP is a synonym for \fBf\fP. |
| .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms |
| .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP. |
| .\" (This is bad, and caused serious bugs later, when |
| .\" support for \fB%D\fP disappeared.) |
| .\" No locale-dependent radix character, |
| .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$". |
| .\" .PP |
| .\" Linux libc5 knows about the five C standard flags and the \(aq flag, |
| .\" locale, "%m$" and "*m$". |
| .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, |
| .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP |
| .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug). |
| .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP, |
| .\" but adds the conversion character |
| .\" .BR m , |
| .\" which outputs |
| .\" .IR strerror(errno) . |
| .\" .PP |
| .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. |
| .PP |
| glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP |
| and conversion characters \fBa\fP and \fBA\fP. |
| .PP |
| glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, |
| and the flag character \fBI\fP. |
| .SH NOTES |
| Some programs imprudently rely on code such as the following |
| .PP |
| sprintf(buf, "%s some further text", buf); |
| .PP |
| to append text to |
| .IR buf . |
| However, the standards explicitly note that the results are undefined |
| if source and destination buffers overlap when calling |
| .BR sprintf (), |
| .BR snprintf (), |
| .BR vsprintf (), |
| and |
| .BR vsnprintf (). |
| .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075 |
| Depending on the version of |
| .BR gcc (1) |
| used, and the compiler options employed, calls such as the above will |
| .B not |
| produce the expected results. |
| .PP |
| The glibc implementation of the functions |
| .BR snprintf () |
| and |
| .BR vsnprintf () |
| conforms to the C99 standard, that is, behaves as described above, |
| since glibc version 2.1. |
| Until glibc 2.0.6, they would return \-1 |
| when the output was truncated. |
| .\" .SH HISTORY |
| .\" UNIX V7 defines the three routines |
| .\" .BR printf (), |
| .\" .BR fprintf (), |
| .\" .BR sprintf (), |
| .\" and has the flag \-, the width or precision *, the length modifier l, |
| .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. |
| .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags |
| .\" #, + and <space> and no longer mentions D,O,U,X. |
| .\" 2.11BSD has |
| .\" .BR vprintf (), |
| .\" .BR vfprintf (), |
| .\" .BR vsprintf (), |
| .\" and warns not to use D,O,U,X. |
| .\" 4.3BSD Reno has the flag 0, the length modifiers h and L, |
| .\" and the conversions n, p, E, G, X (with current meaning) |
| .\" and deprecates D,O,U. |
| .\" 4.4BSD introduces the functions |
| .\" .BR snprintf () |
| .\" and |
| .\" .BR vsnprintf (), |
| .\" and the length modifier q. |
| .\" FreeBSD also has functions |
| .\" .BR asprintf () |
| .\" and |
| .\" .BR vasprintf (), |
| .\" that allocate a buffer large enough for |
| .\" .BR sprintf (). |
| .\" In glibc there are functions |
| .\" .BR dprintf () |
| .\" and |
| .\" .BR vdprintf () |
| .\" that print to a file descriptor instead of a stream. |
| .SH BUGS |
| Because |
| .BR sprintf () |
| and |
| .BR vsprintf () |
| assume an arbitrarily long string, callers must be careful not to overflow |
| the actual space; this is often impossible to assure. |
| Note that the length |
| of the strings produced is locale-dependent and difficult to predict. |
| Use |
| .BR snprintf () |
| and |
| .BR vsnprintf () |
| instead (or |
| .BR asprintf (3) |
| and |
| .BR vasprintf (3)). |
| .\" .PP |
| .\" Linux libc4.[45] does not have a |
| .\" .BR snprintf (), |
| .\" but provides a libbsd that contains an |
| .\" .BR snprintf () |
| .\" equivalent to |
| .\" .BR sprintf (), |
| .\" that is, one that ignores the |
| .\" .I size |
| .\" argument. |
| .\" Thus, the use of |
| .\" .BR snprintf () |
| .\" with early libc4 leads to serious security problems. |
| .PP |
| Code such as |
| .BI printf( foo ); |
| often indicates a bug, since |
| .I foo |
| may contain a % character. |
| If |
| .I foo |
| comes from untrusted user input, it may contain \fB%n\fP, causing the |
| .BR printf () |
| call to write to memory and creating a security hole. |
| .\" .PP |
| .\" Some floating-point conversions under early libc4 |
| .\" caused memory leaks. |
| .SH EXAMPLE |
| To print |
| .I Pi |
| to five decimal places: |
| .PP |
| .in +4n |
| .EX |
| #include <math.h> |
| #include <stdio.h> |
| fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); |
| .EE |
| .in |
| .PP |
| To print a date and time in the form "Sunday, July 3, 10:02", |
| where |
| .I weekday |
| and |
| .I month |
| are pointers to strings: |
| .PP |
| .in +4n |
| .EX |
| #include <stdio.h> |
| fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", |
| weekday, month, day, hour, min); |
| .EE |
| .in |
| .PP |
| Many countries use the day-month-year order. |
| Hence, an internationalized version must be able to print |
| the arguments in an order specified by the format: |
| .PP |
| .in +4n |
| .EX |
| #include <stdio.h> |
| fprintf(stdout, format, |
| weekday, month, day, hour, min); |
| .EE |
| .in |
| .PP |
| where |
| .I format |
| depends on locale, and may permute the arguments. |
| With the value: |
| .PP |
| .in +4n |
| .EX |
| "%1$s, %3$d. %2$s, %4$d:%5$.2d\en" |
| .EE |
| .in |
| .PP |
| one might obtain "Sonntag, 3. Juli, 10:02". |
| .PP |
| To allocate a sufficiently large string and print into it |
| (code correct for both glibc 2.0 and glibc 2.1): |
| .PP |
| .EX |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <stdarg.h> |
| |
| char * |
| make_message(const char *fmt, ...) |
| { |
| int size = 0; |
| char *p = NULL; |
| va_list ap; |
| |
| /* Determine required size */ |
| |
| va_start(ap, fmt); |
| size = vsnprintf(p, size, fmt, ap); |
| va_end(ap); |
| |
| if (size < 0) |
| return NULL; |
| |
| size++; /* For '\e0' */ |
| p = malloc(size); |
| if (p == NULL) |
| return NULL; |
| |
| va_start(ap, fmt); |
| size = vsnprintf(p, size, fmt, ap); |
| va_end(ap); |
| |
| if (size < 0) { |
| free(p); |
| return NULL; |
| } |
| |
| return p; |
| } |
| .EE |
| .PP |
| If truncation occurs in glibc versions prior to 2.0.6, this is treated as an |
| error instead of being handled gracefully. |
| .SH SEE ALSO |
| .BR printf (1), |
| .BR asprintf (3), |
| .BR puts (3), |
| .BR scanf (3), |
| .BR setlocale (3), |
| .BR strfromd (3), |
| .BR wcrtomb (3), |
| .BR wprintf (3), |
| .BR locale (5) |