gtpc2m35C/C++ Language Support User's Guide

fprintf, printf, sprintf-Format and Write Data

This function formats and writes data to a stream.

Format

#include <stdio.h>
int fprintf(FILE *stream, const char *format, ...);
int printf(const char *format, ...);
int sprintf(char *buffer, const char *format, ...);

stream
The stream to be written.

format
A specification of the output text format (see the information that follows).

buffer
The address of the first character in the array in which the output will be written.

....
Additional objects to be converted to output text.
ISO-C only

The fprintf() function is not available in the TARGET(TPF) C library. The printf() function in the TARGET(TPF) library is a limited and nonstandard substitute for the standard printf() function. The TARGET(TPF) library has no support for files, stdout, or file redirection.

The TARGET(TPF) version of the printf() function does not have the same effect as the ISO-C version. Results cannot be predicted if you use both versions in the same application.

The three related functions (fprintf, printf, and sprintf) are referred to as the fprintf family.

The fprintf function formats and writes output to stream. It converts each entry in the argument list, if any, and writes to the stream according to the corresponding format specification in format.

The printf function formats and writes output to the standard output stream, stdout.

TARGET(TPF) restrictions

The format controls for the TARGET(TPF) printf function are limited to those described in SAA Common Programming Interface C Reference - Level 2.

All TARGET(TPF) restrictions described for the puts function also apply to the printf function, which depends on the method of implementation at your installation.

Note:
This function relies on the puts function to operate correctly. If printf is called and puts support does not exist, control is transferred to the system error routine.

The sprintf function formats and stores a series of characters and values in the array pointed to by buffer. Any argument list is converted and put out according to the corresponding format specification in format. If the strings pointed to by buffer and format overlap, behavior is undefined.

The fprintf and printf functions have the same restriction as any write operation for a read immediately following a write, or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must be an intervening reposition unless an end-of-file (EOF) has been reached.

The format consists of ordinary characters, escape sequences, and conversion specifications. The ordinary characters are copied in the order of their appearance. Conversion specifications, beginning with a percent sign (%), determine the output format for any argument list following format. The format can contain multibyte characters beginning and ending in the initial shift state.

When format includes the use of the optional prefix ll to indicate that the size expected is a long long data type, the corresponding value in the argument list should be a long long data type if correct output is expected.

The format is read from left to right. When the first format specification is found, the value of the first argument after format is converted and write according to the format specification. The second format specification causes the second argument after the format to be converted and write, and so on through the end of the format. If there are more arguments than there are format specifications, the extra arguments are evaluated and ignored. The results are undefined if there are not enough arguments for all the format specifications. The following shows the format specification.



Each field of the format specification is a single character or number signifying a particular format option. The type character, which appears after the last optional format field, determines whether the associated argument is interpreted as a character, a string, a number, or pointer. The simplest format specification contains only the percent sign and a type character (for example, %s).

The percent sign

If a percent sign (%) is followed by a character that has no meaning as a format field, the character is simply copied. For example, to print a percent sign character, use %%.

The flag characters

The flag characters in Table 5 are used for the justification of output and printing of signs, blanks, decimal points, octal and hexadecimal prefixes, and the semantics for the wchar_t precision unit. Notice that more than one flag can appear in a format specification. This is an optional field.

Table 5. Flag Characters for the fprintf Family

Flag Meaning Default
- Left-justify the result in the field width. Right-justify.
+ Prefix the output value with a sign (+ or -) if the output value is of a signed type. Sign appears only for negative signed values (-).
blank(' ') Prefix the output value with a blank if the output value is signed and positive. The + flag overrides the blank flag if both appear, and a positive signed value will be written with a sign. No blank.
# When used with the o, x, or X formats, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. No prefix.
When used with the f, e, or E formats, the # flag forces the output value to contain a decimal point in all cases.

The decimal point is sensitive to the LC_NUMERIC category of the same current locale.

The decimal point appears only if digits follow it.
When used with the g or G formats, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. The decimal point appears only if digits follow it; trailing zeros are truncated.
When used with the ls or S format, the # flag causes precision to be measured in wide characters. Precision indicates the maximum number of bytes to be written.
0 When used with the d, i, o, u, x, X, e, E, f, g, or G formats, the 0 flag causes leading 0's to pad the output to the field width. The 0 flag is ignored if precision is specified for an integer or if the - flag is specified. Space padding.

Do not use the # flag with c, lc, C, d, i, u, s, or p types.

The width of the output

Width is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added on the left or the right (depending on whether the -- flag is specified) until the minimum width is reached.

Width never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or width is not given, all characters of the value are written (subject to the precision specification).

The width specification can be an asterisk (*); if it is, an argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. This is an optional field.

The precision of the output

The precision specification is a nonnegative decimal integer preceded by a period. It specifies the number of characters to be written or the number of decimal places. Unlike the width specification, precision can cause the output value to be truncated or a floating-point value to be rounded.

The precision specification can be an asterisk (*); if it is, an argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list. The precision field is optional.

The interpretation of the precision value and the default when precision is omitted depend on the type as shown in Table 6.

Table 6. Precision Argument in the fprintf Family

Type Meaning Default
i
d
u
o
x
X
Precision specifies the minimum number of digits to be written. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. If precision is 0 or omitted entirely, or if the period (.) appears without a number following it, precision is set to 1.
f
e
E
Precision specifies the number of digits to be written after the decimal point. The last digit output is rounded.

The decimal point is sensitive to the LC_NUMERIC category of the current locale.

The default precision is 6. If precision is 0 or the period appears without a number following it, no decimal point is written.
g
G
Precision specifies the maximum number of significant digits written. All significant digits are written.
c
No effect. The character is written.
C
lc
No effect. The wide character is written.
s
Precision specifies the maximum number of characters to be written. Characters in excess of precision are not written. Characters are written until a null character is found.
S
ls
Precision specifies the maximum number of bytes to be written. Bytes in excess of precision are not written; however, multibyte integrity is always preserved. wchar_t characters are written until a null character is found.

Optional prefix

The optional prefix is used to indicate the size of the argument expected:

h
A prefix with integer types d, i, o, u, x, X, and n that specifies that the argument is short int or unsigned short int.

l
A prefix with d, i, o, u, x, X, and n types that specifies that the argument is a long int or unsigned long int.

The l prefix with the c type conversion specifier indicates that the argument is a wchar_t. The l prefix with the s type conversion specifier indicates that the argument is a pointer to wchar_t.

L
A prefix with e, E, f, g, or G types that specifies that the argument is a long double value.

ll
A prefix with integer types d, i, o, u, x, or XX that specifies that the integer is 64 bits long.
Note:
If you pass a long double value and do not use the L qualifier, or if you pass a double value only and use the L qualifier, errors occur.

Table 7 shows the meaning of the type characters used in the precision argument.

Table 7. Type Characters and Their Meanings

Type Argument Output Format
d, i
Integer Signed decimal integer.
u
Integer Unsigned decimal integer.
o
Integer Unsigned octal integer.
x
Integer Unsigned hexadecimal integer, using abcdef.
X
Integer Unsigned hexadecimal integer, using ABCDEF.
f
Double Signed value having the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number. The number of digits after the decimal point is equal to the requested precision.

The decimal point is sensitive to the LC_NUMERIC category of the current locale.

e
Double Signed value having the form [-]d.dddde[sign]ddd, where d is a single-decimal digit, dddd is one or more decimal digits, ddd is two or more decimal digits, and sign is + or -.
E
Double Identical to the e format except that E introduces the exponent, not e.
g
Double Signed value output in f or e format. The e format is used only when the exponent of the value is less than -4 or greater than precision. Trailing zeros are truncated and the decimal point appears only if one or more digits follow it.
G
Double Identical to the g format, except that E introduces the exponent (where appropriate), not e.
D(n,p)
Decimal-type argument. Fixed-point value consisting of an optional sign (+ or -); a series of one or more decimal digits possibly containing a decimal point.
c
Character Single character.
C or lc
Wide Character The argument of wchar_t type is converted to an array of bytes representing a multibyte character as if by call to wctomb().
s
String Characters output up to the first null character (\0) or until precision is reached.
S or ls
Wide String The argument is a pointer to an array of wchar_t type. Wide characters from the array are converted to multibyte characters up to and including a terminating null wide character. Conversion takes place as if by a call to wcstombs() with the conversion state described by the mbstate_t object initialized to 0. The result that is written out will not include the terminating null character.

If no precision is specified, the array contains a null wide character. If a precision is specified, its sets the maximum number of characters written, including shift sequences. A partial multibyte character cannot be written.

n
Pointer to integer Number of characters successfully write so far to the stream or buffer; this value is stored in the integer whose address is given as the argument.
p
Pointer Pointer to void converted to a sequence of printable characters. The output format is equivalent to type X.

Normal Return

If successful the fprintf, printf, and sprintf functions return the number of characters written. The ending null character is not counted.

Error Return

A negative value indicates that an output error has occurred.

Programming Considerations

 The TPF system does not support creating, updating, or deleting files in 1052 or UTIL state. Special files may or may not be writable in 1052 or UTIL state depending on the device driver implementation. 

Examples

The following example prints data using the printf function in a variety of formats.

#include <stdio.h>
int main(void)
{
   char ch = 'h', *string = "computer";
   int count = 234, hex = 0x10, oct = 010, dec = 10;
   double fp = 251.7366;
   unsigned int a = 12;
   float b = 123.45;
   int c;
   void *d = "a";
 
   printf("the unsigned int is %u\n\n",a);
 
   printf("the float number is %g, and %G\n\n",b,b);
 
   printf("RAY%n\n\n",&c);
 
   printf("last line prints %d characters\n\n",c);
 
   printf("Address of d is %p\n\n",d);
 
   printf("%d   %+d    %06d     %X    %x     %o\n\n",
      count, count, count, count, count, count);
 
   printf("1234567890123%n4567890123456789\n\n", &count);
 
   printf("Value of count should be 13; count = %d\n\n", count);
 
   printf("%10c%5c\n\n", ch, ch);
 
   printf("%25s\n%25.4s\n\n", string, string);
 
   printf("%f    %.2f    %e    %E\n\n", fp, fp, fp, fp);
 
   printf("%i    %i     %i\n\n", hex, oct, dec);
}

Output

the unsigned int is 12
 
the float number is 123.45 and 123.45
 
RAY
 
last line prints 3 characters
 
Address of d is DD72F9
 
234   +234    000234     EA    ea     352
 
12345678901234567890123456789
 
Value of count should be 13; count = 13
 
         h    h
 
                 computer
                     comp
 
251.736600    251.74    2.517366e+02    2.517366E+02
 
16    8     10

The following example shows the use of printf to print fixed-point decimal data types.

#include <stdio.h>
#include <decimal.h>
 
decimal(10,2) pd01 = -12.34d;
decimal(12,4) pd02 = 12345678.9876d;
decimal(31,10) pd03 = 123456789013579246801.9876543210d;
 
int main(void) {
  printf("pd01 %%D(10,2)      = %D(10,2)\n", pd01);
  printf("pd02 %%D( 12 , 4 )  = %D( 12 , 4 )\n", pd02);
 
  printf("pd01 %%010.2D(10,2) = %010.2D(10,2)\n", pd01);
  printf("pd02 %%20.2D(12,4)  = %20.2D(12,4)\n", pd02);
  printf("\n Give strange result if the specified size is wrong!\n"
  printf("pd03 %%D(15,3)      = %D(15,3)\n\n", pd03);
}

Output

pd01 %D(10,2)      = -12.34
pd02 %D( 12 , 4 )  = 12345678.9876
pd01 %010.2D(10,2) = -000012.34
pd02 %20.2D(12,4)  =          12345678.98
 
Give strange result if the specified size is wrong!
pd03 %D(15,3)      = -123456789013.579

The following example shows the use of the sprintf function to format and print various data.

#include <stdio.h>
 
char buffer[200];
int i, j;
double fp;
char *s = "baltimore";
char c;
 
int main(void)
{
   c = 'l';
   i = 35;
   fp = 1.7320508;
 
   /* Format and print various data */
   j = sprintf(buffer, "%s\n", s);
   j += sprintf(buffer+j, "%c\n", c);
   j += sprintf(buffer+j, "%d\n", i);
   j += sprintf(buffer+j, "%f\n", fp);
   printf("string:\n%s\ncharacter count = %d\n", buff
}

Output

string:
baltimore
l
35
1.732051
 
character count = 24

Related Information

fscanf, scanf, sscanf-Read and Format Data.

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.