snprintf [V1.07 or later]

Write text in specified format to array

[Classification]

Standard library

[Syntax]

#include <stdio.h>

int __far snprintf(char __far * restrict s, size_t n, const char __far * restrict format, ...); (C99)

[Return value]

The number of characters that were output (excluding the null character (\0)) is returned.

Returns EOF(-1) if a write error has occurred.

[Description]

This function converts the arguments following format into the output format and writes them into the array indicated by s. The conversion method in this case complies with the format specified by the string indicated by format. When n is 0, no text is written and s may be a null pointer. In other cases, output characters subsequent to the (n-1)th character are discarded without being written to the array and the null character is written after the character string that was actually written to the array. When copying is executed between objects whose areas overlap, correct operation is not guaranteed.

Correct operation is not guaranteed if there is not enough arguments to satisfy the format. If the format becomes full even though arguments are still left, the extra arguments are merely evaluated and they will be ignored.

The format consists of 0 or more directives. The format will be output without change except for a conversion specification starting with %. The conversion specification fetches the 0 or more subsequent arguments, converts them, and then outputs them.

The format consists of the following two types of directives:

Ordinary characters	Characters that are copied directly without conversion (other than "%").
Conversion specifications	Specifications that fetch zero or more arguments and assign a specification.

Each conversion specification begins with character "%" (to insert "%" in the output, specify "%%" in the format string). The following appear after the "%":

%[flag][field-width][precision][size][type-specification-character]

The meaning of each conversion specification is explained below.

(1)

flag

Zero or more flags, which qualify the meaning of the conversion specification, are placed in any order.

The flag characters and their meanings are as follows:

-	The result of the conversion will be left-justified in the field, with the right side filled with blanks (if this flag is not specified, the result of the conversion is right-justified).
+	The result of a signed conversion will start with a + or - sign (if this flag is not specified, the result of the conversion starts with a sign only when a negative value has been converted).
Space	If the first character of a signed conversion is not a sign and a signed conversion is not generated a character, a space (" ") will be appended to the beginning of result of the conversion. If both the space flag and + flag appear, the space flag is ignored.
#	The result is to be converted into an alternative format. For o conversion, the precision is increased so that the first digit of the conversion result is 0. For x or X conversion, 0x or 0X is appended to the beginning of a non-zero conversion result. For e, f, g, E, F, or G conversion, a decimal point "." is added to the conversion result even if no digits follow the decimal pointNote. For g or G conversion, trailing zeros will not be removed from the conversion result. The operation is undefined for conversions other than the above.
0	For d, e, f, g, i, o, u, x, E, F, G, or X conversion, zeros are added following the specification of the sign or base to fill the field width. If both the 0 flag and - flag are specified, the 0 flag is ignored. For d, i, o, u, x, or X conversion, when the precision is specified, the zero (0) flag is ignored. Note that 0 is interpreted as a flag and not as the beginning of the field width. The operation is undefined for conversion other than the above.

Note	Normally, a decimal point appears only when a digit follows it.

(2)	field width

This is an optional minimum field width.

If the converted value is smaller than this field width, the left side is filled with spaces (if the left justification flag explained above is assigned, the right side will be filled with spaces). This field width takes the form of "*" or a decimal integer. If "*" is specified, an int type argument is used as the field width. A negative field width is not supported. If an attempt is made to specify a negative field width, it is interpreted as a minus (-) flag appended to the beginning of a positive field width.

(3)

precision

For d, i, o, u, x, or X conversion, the value assigned for the precision is the minimum number of digits to appear. For e, f, E, or F conversion, it is the number of digits to appear after the decimal point. For g or G conversion, it is the maximum number of significant digits. For s conversion, it is the maximum number of bytes.

The precision takes the form of "*" or "." followed by a decimal integer. If "*" is specified, an int type argument is used as the precision. If a negative precision is specified, it is treated as if the precision were omitted. If only "." is specified, the precision is assumed to be 0. If the precision appears together with a conversion specification other than the above, the operation is undefined.

(4)

size

This is an arbitrary optional size character hh, h, l, ll, j, z, t, or L, which changes the default method for interpreting the data type of the corresponding argument.

When hh is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a signed char or unsigned char argument. hh also causes a following n type specification to be forcibly applied to a pointer to a signed char argument. (C99)

When h is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a short int or unsigned short int argument. h is also causes a following n type specification to be forcibly applied to a pointer to short argument.

When l is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a long or unsigned long argument. l is also causes a following n type specification to be forcibly applied to a pointer to long argument.

When ll is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a long long or unsigned long long argument. Furthermore, for ll, a following n type specification is forcibly applied to a long long pointer.

When j is specified, a following d, i, o, u, x, or X type specification is forcibly applied to an intmax_t or uintmax_t argument. j also causes a following n type specification to be forcibly applied to a pointer to an intmax_t argument. (C99)

When z is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a size_t or signed int argument. z also causes a following n type specification to be forcibly applied to a pointer to a signed int argument. (C99)

When t is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a ptrdiff_t or unsigned int argument. t also causes a following n type specification to be forcibly applied to a pointer to a ptrdiff_t argument. (C99)

When L is specified, a following e, E, f, F, g, or G type specification is forcibly applied to a long double argument. However, since the double type and long double type have the same format in this compiler, the specification has no effect.

(5)	type specification character

These are characters that specify the type of conversion that is to be applied.

The characters that specify conversion types and their meanings are as follows.

F conversion can only be specified for C99 libraries.

d, i	Convert an int type argument to a signed decimal number.
o, u, x, X	Convert an unsigned int type argument to octal notation (o), unsigned decimal notation (u), or unsigned hexadecimal notation (x or X) with dddd format. For x conversion, the letters abcdef are used. For X conversion, the letters ABCDEF are used.
f, F	Convert a double type (float type in a single-precision function) argument to decimal notation of the form [-]dddd.dddd. The format used for converting a double-type argument that indicates infinity is [-]inf for f conversion and [-]INF for F conversion. The format used for converting a double-type argument that indicates NaN is [-]nan for f conversion and [-]NAN for F conversion. (C99)
e, E	Convert a double type (float type in a single-precision function) argument to [-]d.dddde±dd format, which has one digit before the decimal point (not 0 if the argument is not 0) and the number of digits after the decimal point is equal to the precision. The E conversion specification generates a number in which the exponent part starts with "E" instead of "e". The format for converting a double-type argument that indicates infinity or NaN is the same as the f conversion or F conversion specifier. (C99)
g, G	Convert a double type (float type in a single-precision function) argument to e (E for a G conversion specification) or f format, with the number of digits in the mantissa specified for the precision. Trailing zeros of the conversion result are excluded from the fractional part. The decimal point appears only when it is followed by a digit. The format for converting a double-type argument that indicates infinity or NaN is the same as the f conversion or F conversion specifier. (C99)
c	Convert an int type argument to unsigned char type and output the characters of the conversion result.
s	The argument must be a pointer pointing to a character type array. Characters from this array are output up until the null character (\0) indicating termination (the null character (\0) itself is not included). If the precision is specified, no more than the specified number of characters will be output. If the precision is not specified or if the precision is greater than the size of this array, make sure that this array includes the null character (\0). The pointer must always be the far pointer. When passing a constant, add a cast to the argument to clearly show that it is a pointer. Correct operation is not guaranteed when a null pointer is passed.
p	Output the value of the pointer. The pointer must always be the far pointer. When passing a constant, add a cast to the argument to clearly show that it is a pointer.
n	Store the number of characters that were output in the same object. A pointer to int type is used as the argument.
%	Output the character "%". No argument is converted. The conversion specification is "%%".

[Restrictions]

a conversion or A conversion of the C99 standard is not supported.