PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) ------------------------------------------------------------------------------- printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf PURPOSE Prints formatted output. LIBRARY Standard I/O Library (libc.a) SYNTAX #include int printf ( fmt [, val, ... ]) char *fmt; int fprintf (stream, fmt [, val, ... ]) FILE *stream; char *fmt; int sprintf (s, fmt [, val, ... ]) char *s, *fmt; int NLprintf ( fmt [, val, ... ]) char *fmt; int NLfprintf (stream, fmt [, val, ... ]) FILE *stream; char *fmt; int NLsprintf (s, fmt [, val, ... ]) char *s, *fmt; int wsprintf (scs, fmt [,val,...]) wchar_t *wcs; char *fmt; DESCRIPTION The printf subroutine converts, formats, and writes its val parameters, under control of the fmt parameter, to the standard output stream stdout. The fprintf subroutine converts, formats, and writes its val parameters, under control of the fmt parameter, to the output stream specified by its stream Processed July 12, 1991 PRINTF(3s,L) 1 PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) parameter. The sprintf subroutine converts, formats, and stores its val parameters, under control of the fmt parameter, into consecutive bytes starting at the address specified by the s parameter. The sprintf subroutine places a "'\0'" (null character) at the end. It is your responsibility to ensure that enough storage space is available to contain the formatted string. The wsprintf subroutine is equivalent to sprintf except that the argument wcs specifies an array of wide characters into which the generated output is written. A NULL wide character is appended at the end of the array, but it is not counted as part of the returned sum. If copying takes place between objects that overlap, the behavior is undefined. The NLprintf, NLfprintf, and NLsprintf subroutines are provided for backward compatibility and behave exactly like the printf, fprintf, and sprintf subroutines respectively. The fmt parameter is a character string that contains two types of objects: o Plain characters, which are copied to the output stream. o Conversion specifications, each of which causes zero or more items to be fetched from the val parameter list. If there are not enough items for the fmt in the val parameter list, then the results are unpredictable. If more vals remain after the entire fmt has been processed, they are ignored. Conversions can be applied to the nth argument in the argument list, rather than to the next unused argument. In this case, the conversion character "%" is replaced by the sequence "%digit$", where digit is a decimal integer n in the range of [1, {NL_ARGMAX}], giving the position of the argument in the argument list. With this feature, format strings can be defined to assure that arguments are selected in an order appropriate for the specified language. Each conversion specification in the fmt parameter has the following syntax: o A "%" (percent) sign or the character sequence "%digit$", which introduces the conversion specification. o Zero or more options, which modify the meaning of the conversion specification. The option characters and their meanings are: "-" The result of the conversion is left-justified within the field. "+" The result of a signed conversion always begins with a sign ("+" or "-"). blank If the first character of a signed conversion is not a sign, a blank is prefixed to the result. If both the blank and "+" options appear, then the blank option is ignored. Processed July 12, 1991 PRINTF(3s,L) 2 PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) "#" This option specifies that the value is to be converted to an alternate form. For c, d, s, and u conversions, the option has no effect. For o conversion, it increases the precision to force the first digit of the result to be a "0". For x and X conversions, a nonzero result has "0x" or "0X" prefixed to it. For e, E, f, g, and G conversions, the result always contains a decimal point, even if no digits follow the decimal point. For g and G conversions, trailing zeros are not removed from the result. B This option affects conversions using the s or S conversion characters of the NLprintf, NLfprintf, and NLsprintf subroutines only. The B flag specifies that field width and precision are given in bytes rather than in code points. N This option affects the s and S conversion characters of the NLprintf, NLfprintf, and NLsprintf subroutines only. The N flag specifies that each international character support code point in the converted string converts into a printable ASCII escape sequence that uniquely identifies the code point. o An optional decimal digit string that specifies the minimum field width. If the converted value has fewer characters than the field width, the field is padded on the left to the length specified by the field width. If the left-adjustment option is specified, the field is padded on the right. For the NLprintf, NLfprintf, and NLsprintf subroutines, field width is measured in code points rather than bytes, unless the B flag is specified. o An optional precision. The precision is a "." (period) followed by a decimal digit string. If no precision is given, it is treated as 0. The precision specifies: - The minimum number of digits to appear for the d, i, u, o, x, or X conversions - The number of digits to appear after the decimal point for the e and f conversions - The maximum number of significant digits for the g conversion - The maximum number of characters to be printed from a string in the s conversion. o An optional l (the letter "ell") specifying that a following d, i, u, o, x, or X conversion character applies to a long integer val. With printf, an optional L specifying that a following d, i, u, o, x, or X conversion character applies to a long double val. o A character that indicates the type of conversion to be applied: "%" Performs no conversion. Prints a "%". Note: If the character after the "%" or "%digit$" sequence is not a valid conversion character, the results of the conversion are undefined. Processed July 12, 1991 PRINTF(3s,L) 3 PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) d, i Accepts an integer val and converts it to signed decimal notation. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a 0 value with a precision of 0 is a null string. Specifying a field width with a zero as a leading character causes the field width value to be padded with leading zeros. Note: i applies to printf only. u Accepts an integer value and converts it to unsigned decimal notation. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a 0 value with a precision of 0 is a null string. Specifying a field width with a zero as a leading character causes the field width value to be padded with leading zeros. o Accepts an integer val and converts it to octal notation. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a 0 value with a precision of 0 is a null string. Specifying a field width with a zero as a leading character causes the field width value to be padded with leading zeros. An octal value for field width is not implied. x, X Accepts an integer val and converts it to hexadecimal notation. The letters "abcdef" are used for the x conversion and the letters "ABCDEF" are used for the X conversion. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a 0 value with a precision of 0 is a null string. Specifying a field width with a zero as a leading character causes the field width value to be padded with leading zeros. f Accepts a float or double val and converts it to decimal notation in the format [-]ddd.ddd. The number of digits after the decimal point is equal to the precision specification. If no precision is specified, then six digits are output. If the precision is 0, then no decimal point appears. See Note below. e, E Accepts a float or double val and converts it to the exponential form [-]d.ddde+/-dd. There is one digit before the decimal point and the number of digits after the decimal point is equal to the precision specification. If no precision is specified, then six digits are output. If the precision is 0, then no decimal point appears. The E conversion character produces a number with E instead of e before the exponent. The exponent always contains at least two digits. See Note below. Processed July 12, 1991 PRINTF(3s,L) 4 PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) g, G Accepts a float or double val and converts it in the style of the e, E or f conversion characters, with the precision specifying the number of significant digits. Trailing zeros are removed from the result. A decimal point appears only if it is followed by a digit. The style used depends on the value converted. Style e (E, if G is the flag used) results only if the exponent resulting from the conversion is less than -4, or if it is greater than or equal to the precision. Note: Because of the inexactness of floating point numbers, attempts to display more than 6 (PS/2) or 7 (S/370) digits of a single prec- ision floating point number or more than 15 (PS/2) or 16 (S/370) digits of a double precision floating point number may result in trailing digits which are innacurate. For more details on the representation of floating point numbers on the PS/2 and S/370, see the AIX C Language User's Guide. c Accepts and prints the character val. C Prints one NLchar. Applies to NLprintf only. s Accepts a val is as a string (character pointer) and characters from the string are printed until a "'\0'" (null character) is encountered or the number of characters indicated by the precision is reached. If no precision is specified, all characters up to the first null character are printed. If the string pointer val has a value of 0 or NULL, the results are undefined. S The corresponding NLprintf, NLfprintf, or NLsprintf val is taken to be a pointer to a string of the type NLchar. Characters from the string are printed until a "\0" (null) character is encountered or the number of characters indicated by precision is reached. If no precision is specified, all characters up to the first null character are printed. If the string pointer val has a value of 0 or NULL, the results are undefined. n Accepts a pointer to an integer. The number of characters successfully written so far to the stream or buffer is stored in the integer whose address is given as the argument. Applies to printf only. p Accepts an integer val and converts it to hexidecimal notation. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a 0 value with a precision of 0 is a null string. Specifying a field width with a zero as a leading character causes the field with value to be padded with zeros. This type of conversion applies to NLprintf only. %wc The wchar_t type argument is converted to an array of characters and the resulting multibyte characters are written. If the resulting multibyte characters contain fewer bytes than the specified field width, the field is padded with blank characters. Precision is ignored, even if specified. This conversion is the same as that performed by the wctomb subroutine. Processed July 12, 1991 PRINTF(3s,L) 5 PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) %ws The argument is a pointer to a wchar_t type array. Wide characters from the array are converted to multibyte characters and the resulting multibyte characters are written up to (but no including) a terminating NULL wide character. If both the precision and the "#" are specified, the number of wide characters written cannot exceed the number of bytes specified by the precision; if only precision is specified, the number of characters written is equal to the precision number. If the precision is not specified or it is greater than the size of the array, the array contains a NULL character. If the resulting multibyte characters have fewer bytes than the specified field width, the field will be padded with blanks. This conversion is the same as that performed by the wcstombs subroutine. A field width or precision may be indicated by an * (asterisk) instead of a digit string. In this case, an integer val parameter supplies the field width or precision. The val parameter that is converted for output is not fetched until the conversion letter is reached, so the parameters specifying field width or precision must appear before the value (if any) to be converted. If the result of a conversion is wider than the field width, then the field is expanded to contain the converted result. No truncation occurs. However, a small precision may cause truncation on the right. The e, E, f and g formats represent the special floating-point values as follows: Quiet NaN "+QNaN" or "-QNaN" Signalling NaN "+SNaN" or "-SNaN" +/-infinity "+INF" or "-INF" +/-0 "+0" or "-0" The representation of the plus sign depends on whether the + or blank formatting option is specified. RETURN VALUE Upon successful completion, each of these subroutines except wsprintf returns the number of display characters in the output string rather than the number of bytes in the string. (The NLprintf, NLfprintf and NLsprintf subroutines use strings that may contain 2-byte NLchars.) The value returned by sprintf and NLsprintf does not include the final "'\0'" character. If an output error occurs, a negative value is returned. The wsprintf subroutine returns the number of wide characters written into the array, not counting the terminating NULL wide character. Processed July 12, 1991 PRINTF(3s,L) 6 PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L) EXAMPLE To print the language-dependent date and time format, the following statement could be used: printf (format, weekday, month, day, hour, min); For American usage, format could be a pointer to the string: %1$s, %2$s %3$d, %4$d:%5$.2d\n producing the message: Sunday, July 3, 10:02 whereas for German usage, format could be a pointer to the string: %1Ss, %3$d. %2$s, %4$d:%5$.2d\n producing the message: Sonntag, 3. Juli, 10:02 RELATED INFORMATION In this book: "conv," "vprintf, vfprintf, vsprintf, NLvprintf, NLvfprintf, NLvsprintf," "limits.h," "ecvt, fcvt, gcvt," "putc, putchar, fputc, putw, putwc, putwchar, fputwc," "scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf, wsscanf," and "stdio." Examples of using printf in AIX C Language Guide and AIX C Language Reference. "Introduction to International Character Support" in Managing the AIX Operating System. AIX Guide to Multibyte Character Set (MBCS) Support. Processed July 12, 1991 PRINTF(3s,L) 7