home *** CD-ROM | disk | FTP | other *** search
- <H3>SYNOPSIS</H3>
- int printf(const char *format, /* args*/ ...);
- <BR>
- int sprintf(char *s, const char *format, /* args*/ ...);
- <BR>
- <BR>
- The printf() function places output on the output stream stdout.
- The sprintf() function places output, followed by the null byte (\0),
- in consecutive bytes starting at <I>s</I>; the CScript engine ensures
- that enough storage is available.
- <BR>
- Each of these functions converts, formats, and prints its <I>args</I>
- under control of the <I>format</I>. The <I>format</I> is a character
- string, beginning and ending in its initial shift state, if any.
- The <I>format</I> is composed of zero or more directives defined as follows:
- <P>
- <UL>
- <LI><I>ordinary</I> <I>characters</I>, which are simply copied to the
- output stream;</LI>
- <LI><I>escape</I> <I>sequences</I>, which represent non-graphic characters;
- and</LI>
- <LI><I>conversion</I> <I>specifications</I>, each of which results in the
- fetching of zero or more arguments.</LI>
- </UL>
- <P>
- The results are undefined if there are insufficient arguments for the
- <I>format</I>. If the <I>format</I> is exhausted while arguments remain,
- the excess arguments are evaluated but are otherwise ignored.
- Conversions can be applied to the <I>n</I>th argument after the
- <I>format</I> in the argument list, rather than to the next unused
- argument. In this case, the conversion character % (see below) is
- replaced by the sequence %<I>n</I>$, where <I>n</I> is a decimal integer
- in the range [1, NL_ARGMAX], giving the position of
- the argument in the argument list. This feature provides for
- the definition of format strings that select arguments in an
- order appropriate to specific languages (see the EXAMPLES section).
- <P>
- In format strings containing the %<I>n</I>$ form of conversion
- specifications, numbered arguments in the argument list can
- be referenced from the format string as many times as
- required.
- <P>
- In format strings containing the % form of conversion
- specifications, each argument in the argument list is used
- exactly once.
- <P>
- <B>Escape Sequences</B><BR>
- The following escape sequences produce the associated action
- on display devices capable of the action:
- <UL>
- <LI><B>\n</B> Newline. Move the printing position to the start
- of the next line.</LI>
- <LI><B>\r</B> Carriage return. Move the printing position to the
- start of the current line.</LI>
- <LI><B>\t</B> Horizontal tab. Move the printing position to the
- next implementation-defined horizontal tab position on the current line.</LI>
- </UL>
- <P>
- <B>Conversion Specifications</B><BR>
- Each conversion specification is introduced by the character
- % or by the character sequence %<I>n</I>$, after which the following
- appear in sequence:
- <P>
- <UL>
- <LI>An optional field, consisting of a decimal digit
- string followed by a $, specifying the next <I>args</I> to be
- converted. If this field is not provided, the <I>args</I>
- following the last <I>args</I> converted will be used.</LI>
-
- <LI>Zero or more <I>flags</I> (in any order), which modify the
- meaning of the conversion specification.</LI>
-
- <LI>An optional minimum <I>field</I> <I>width</I>. If the converted
- value has fewer bytes than the field width, it will be
- padded with spaces by default on the left; it will be
- padded on the right, if the left-adjustment flag (-),
- described below, is given to the field width. The
- field width takes the form of an asterisk (*),
- described below, or a decimal integer.<BR>
-
- If the conversion character is s, a standard-conforming
- application interprets the field width as the
- minimum number of
- bytes to be printed; an application that is not
- standard-conforming interprets the field width as
- the minimum number of columns of screen display.
- For an application that is not standard-
- conforming, %10s means if the converted value has
- a screen width of 7 columns, 3 spaces would be
- padded on the right.
- <BR>
- If the format is %ws, then the field width should
- be interpreted as the minimum number of columns
- of screen display.</LI>
-
- <LI>An optional <I>precision</I> that gives the minimum number of
- digits to appear for the d, i, o, u, x, or X conversions (the field
- is padded with leading zeros); the
- number of digits to appear after the radix character
- for the e, E, and f conversions, the maximum number of
- significant digits for the g and G conversions; or the
- maximum number of bytes to be printed from a string in
- s and S conversions. The precision takes the form of
- a period (.) followed either by an asterisk (*),
- described below, or an optional decimal digit string,
- where a null digit string is treated as 0. If a precision
- appears with any other conversion character,
- the behavior is undefined.<BR>
-
- If the conversion character is s or S, a
- standard-conforming application interprets the precision
- as the maximum number of bytes to be written; an application that is not
- standard-conforming interprets the precision as
- the maximum number of columns of screen display.
- For an application that is not standard-conforming,
- %.5s would print only the portion of
- the string that would display in 5 screen columns.
- Only complete characters are written.
-
- For %ws, the precision should be interpreted as
- the maximum number of columns of screen display.
- The precision takes the form of a period (.) followed by a
- decimal digit string; a null digit
- string is treated as zero. Padding specified by
- the precision overrides the padding specified by
- the field width.</LI>
-
- <LI>An optional h specifies that a following d, i, o, u,
- x, or X conversion character applies to a type short
- int or unsigned short int argument (the argument will
- be promoted according to the integral promotions and
- its value converted to type short int or unsigned
- short int before printing); an optional h specifies
- that a following n conversion character applies to a
- pointer to a type short int argument. An optional l
- (ell) specifies that a following d, i, o, u, x, or X
- conversion character applies to a type long int or
- unsigned long int argument; an optional l (ell)
- specifies that a following n conversion character
- applies to a pointer to a type long int argument. An
- optional ll (ell ell) specifies that a following d,
- i, o, u, x, or X conversion character applies to a
- type long long or unsigned long long argument; an
- optional ll (ell ell) specifies that a following n
- conversion character applies to a pointer to a long
- long argument. An optional L specifies that a following
- e, E, f, g, or G conversion character applies to a
- long double argument. If an h, l, or L appears before
- any other conversion character, the behavior is undefined.</LI>
-
- <LI>A <I>conversion</I> <I>character</I> (see below) that indicates the
- type of conversion to be applied.</LI>
- </UL>
- <P>
- A field width or precision may be indicated by an asterisk
- (*) instead of a digit string. In this case, an integer <I>args</I>
- supplies the field width or precision. The <I>args</I> that is
- actually converted is not fetched until the conversion
- letter is seen, so the <I>args</I> specifying field width or precision
- must appear before the <I>args</I> (if any) to be converted.
- If the <I>precision</I> argument is negative, it will be changed to
- zero. A negative field width argument is taken as a - flag,
- followed by a positive field width. A negative precision is
- taken as if the precision were omitted. In format strings
- containing the %<I>n</I>$ form of a conversion specification, a
- field width or precision may be indicated by the sequence
- *<I>m</I>$, where <I>m</I> is a decimal integer in the range [1,
- NL_ARGMAX] giving the position in the argument list (after
- the format argument) of an integer argument containing the
- field width or precision, for example:
- <P>
- <BLOCKQUOTE>
- <CODE>printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);</CODE>
- </BLOCKQUOTE>
- <P>
- The <I>format</I> can contain either numbered argument specifications
- (that is, %<I>n</I>$ and *<I>m</I>$), or unnumbered argument specifications
- (that is, % and *), but normally not both. The only exception to this
- is that %% can be mixed with the %<I>n</I>$ form. The results of mixing
- numbered and unnumbered argument specifications in a <I>format</I>
- string are undefined. When numbered argument specifications are used,
- specifying the <I>N</I>th argument requires that all the leading
- arguments, from the first to the (<I>N</I>-<I>1</I>)th, are specified in
- the format string.
- <P>
- <B>Flag Characters</B><BR>
- The flag characters and their meanings are:
- <BR>
- <UL>
- <LI><B>'</B> The integer portion of the result of a decimal
- conversion (%i, %d, %u, %f, %g, or %G) will be
- formatted with thousands' grouping characters. For
- other conversions the behavior is undefined. The
- non-monetary grouping character is used.</LI>
-
- <LI><B>-</B> The result of the conversion will be left-justified
- within the field. (It will be right-justified if this flag is not
- specified.)
- <LI><B>+</B> The result of a signed conversion will always
- begin with a sign (+ or -). (It will begin with a
- sign only when a negative value is converted if
- this flag is not specified.)</LI>
- <LI><B>space</B> If the first character of a signed conversion is
- not a sign, a space will be placed before the
- result. This means that if the space and + flags
- both appear, the space flag will be ignored.
- <LI><B>#</B> The value is to be converted to an alternate form.
- For c, d, i, s, and u conversions, the flag has no
- effect. For an o conversion, it increases the precision to
- force the first digit of the result to be a zero.
- For x (or X) conversion, a non-zero
- result will have 0x (or 0X) prepended to it. For
- e, E, f, g, and G conversions, the result will
- always contain a radix character, even if no
- digits follow the point (normally, a decimal point
- appears in the result of these conversions only if
- a digit follows it). For g and G conversions,
- trailing zeros will not be removed from the result
- as they normally are.</LI>
- <LI><B>0</B> For d, i, o, u, x, X, e, E, f, g, and G conversions,
- leading zeros (following any indication of
- sign or base) are used to pad to the field width;
- no space padding is performed. If the 0 and -
- flags both appear, the 0 flag will be ignored. For
- d, i, o, u, x, and X conversions, if a precision
- is specified, the 0 flag will be ignored. For
- other conversions, the behavior is undefined.
- </UL>
- <P>
- <B>Conversion Characters</B><BR>
- Each conversion character results in fetching zero or more
- <I>args</I>. The results are undefined if there are insufficient
- <I>args</I> for the format. If the format is exhausted while <I>args</I>
- remain, the excess <I>args</I> are ignored.
- <P>
- The conversion characters and their meanings are:
- <UL>
- <LI><B>d,i</B> The int argument is converted to a signed decimal
- in the style [-]<I>dddd</I>. The precision specifies the
- minimum number of digits to appear; if the value
- being converted can be represented in fewer
- digits, it will be expanded with leading zeros.
- The default precision is 1. The result of converting 0
- with an explicit precision of 0 is no characters.</LI>
-
- <LI><B>o</B> The unsigned int argument is converted to unsigned
- octal format in the style <I>dddd</I>. The precision
- specifies the minimum number of digits to appear;
- if the value being converted can be represented in
- fewer digits, it will be expanded with leading
- zeros. The default precision is 1. The result of
- converting 0 with an explicit precision of 0 is no
- characters.</LI>
-
- <LI><B>u</B> The unsigned int argument is converted to unsigned
- decimal format in the style <I>dddd</I>. The precision
- specifies the minimum number of digits to appear;
- if the value being converted can be represented in
- fewer digits, it will be expanded with leading
- zeros. The default precision is 1. The result of
- converting 0 with an explicit precision of 0 is no
- characters.</LI>
-
- <LI><B>x</B> The unsigned int argument is converted to unsigned
- hexadecimal format in the style <I>dddd</I>; the letters
- abcdef are used. The precision specifies the
- minimum number of digits to appear; if the value
- being converted can be represented in fewer
- digits, it will be expanded with leading zeros.
- The default precision is 1. The result of converting
- ing 0 with an explicit precision of 0 is no characters.</LI>
-
- <LI><B>X</B> Behaves the same as the x conversion character
- except that letters ABCDEF are used instead of abcdef.</LI>
-
- <LI><B>f</B> The double <I>args</I> is converted to decimal notation
- in the style [-]<I>ddd</I>.<I>ddd</I>, where the number of
- digits after the radix character
- is equal to the precision specification. If the precision is
- omitted from <I>arg</I>, six
- digits are output; if the precision is explicitly
- zero and the # flag is not specified, no radix
- character appears. If a radix character appears,
- at least 1 digit appears before it. The value is
- rounded to the appropriate number of digits.</LI>
-
- <LI><B>e,E</B> The double <I>args</I> is converted to the style
- [-]<I>d</I>.<I>ddd</I>e<B>_</B><I>dd</I>, where there is one digit before the
- radix character (which is non-zero if the argument
- is non-zero) and the number of digits after it is
- equal to the precision. When the precision is
- missing, six digits are produced; if the precision
- is zero and the # flag is not specified, no radix
- character appears. The E conversion character
- will produce a number with E instead of e introducing the
- exponent. The exponent always contains
- at least two digits. The value is rounded to the
- appropriate number of digits.</LI>
-
- <LI><B>g,G</B> The double <I>args</I> is printed in style f or e (or in
- style E in the case of a G conversion character),
- with the precision specifying the number of significant digits.
- If the precision is zero, it is
- taken as one. The style used depends on the value
- converted: style e (or E) will be used only if the
- exponent resulting from the 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 radix character appears only
- if it is followed by a digit.</LI>
-
- <LI><B>c</B> The int <I>args</I> is converted to an unsigned char, and
- the resulting byte is printed.</LI>
-
- <LI><B>s</B> The <I>args</I> is taken to be a string (character
- pointer) and characters from the string are written
- up to (but not including) a terminating null
- byte. If a precision is specified, a standard-conforming application
- will write only the number of bytes specified by precision; an
- application that is not standard-conforming will write only
- the portion of the string that will display in the number of columns
- of screen display specified by precision.
- <BR>
- If the precision is not specified, it is taken to
- be infinite, so all bytes up to the first null
- byte are printed. A null value for <I>args</I> will yield
- undefined results.</LI>
-
- <LI><B>%</B> Print a %; no argument is converted. The entire
- conversion specification must be %%.</LI>
- </UL>
- <P>
- If a conversion specification does not match one of the
- above forms, the behavior is undefined.
- <P>
- If a floating-point value is the internal representation for
- infinity, the output is [<B>_</B>]<I>Infinity</I>, where <I>Infinity</I>
- is either Infinity or Inf, depending on the desired output
- string length. Printing of the sign follows the rules
- described above.
- <P>
- If a floating-point value is the internal representation for
- "not-a-number," the output is [<B>_</B>]<I>NaN</I>. Printing of the sign
- follows the rules described above.
- <P>
- In no case does a non-existent or small field width cause
- truncation of a field; if the result of a conversion is
- wider than the field width, the field is simply expanded to
- contain the conversion result. Characters generated by
- printf() are printed as if the function had been called.
- <P>
- <H3>RETURN VALUES</H3>
- The printf() and sprintf() functions return the number of bytes
- transmitted (not including the \0 in the case of sprintf()). The
- snprintf() function returns the number of characters formatted,
- that is, the number of characters that were written to the buffer.
- Each function returns a negative value if an output error was encountered.
- <P>
- <H3>EXAMPLES</H3>
- Example 1: To print the language-independent date and time
- format, the following statement could be used:
- <BLOCKQUOTE>
- printf (format, weekday, month, day, hour, min);
- </BLOCKQUOTE>
- For American usage, <I>format</I> could be a pointer to the string:
- <BLOCKQUOTE>
- "%s, %s %d, %d:%.2d\n"
- </BLOCKQUOTE>
- producing the message:
- <BLOCKQUOTE>
- Sunday, July 3, 10:02
- </BLOCKQUOTE>
- whereas for German usage, <I>format</I> could be a pointer to the string:
- <BLOCKQUOTE>
- "%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
- </BLOCKQUOTE>
- producing the message:
- <BLOCKQUOTE>
- Sonntag, 3. Juli, 10:02
- </BLOCKQUOTE>
- Example 2: To print a date and time in the form Sunday, July
- 3, 10:02, where weekday and month are pointers to null-terminated strings:
- <BLOCKQUOTED>
- printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);
- </BLOCKQUOTED>
- Example 3: To print pi to 5 decimal places:
- <BLOCKQUOTED>
- printf("pi = %.5f", 4 * atan(1.0));
- </BLOCKQUOTED>
-