Chapter Contents

Previous

Next
fprintf

fprintf



Write Formatted Output to a File


SYNOPSIS
DESCRIPTION
CAUTION
RETURN VALUE
DIAGNOSTICS
PORTABILITY
IMPLEMENTATION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO


SYNOPSIS

#include <stdio.h>
 int fprintf(FILE *f, const char *format, var1, var2, ...);


DESCRIPTION

fprintf writes output to the stream associated with the FILE object addressed by f under the control of the string addressed by format . The argument list following format may contain one or more additional arguments whose values are to be formatted and transmitted.

format points to a string that contains ordinary characters (not including % ) that are sent without modification to the file and 0 or more conversion specifications. Conversion specifications begin with the % character. The % character may be followed by these specifications:

Here are the modifier flags:
- left-justifies the result of the conversion within the field.
+ always precedes the result of a signed conversion with a plus sign or minus sign.
space precedes the result of a signed conversion with a space or a minus sign. (If both space and + are used, the space flag is ignored.)
# uses an alternate form of the conversion. This flag affects the o and x (or X ) integer-conversion specifiers and all of the floating-point conversion specifiers.

For o conversions, the # flag forces the result to have a leading 0. For x (or X ) conversion, the result of the conversion is prefixed with 0x (or 0X ).

For e , E , f , g , and G conversions, the # flag causes the result of the conversion to always have a decimal indicator. For g and G conversions, the # indicates that trailing 0s are not to be removed.

0 for d , i , o , u , x , X , e , E , f , g , and G conversions, leading 0 s are used to pad the field width. (If both - and 0 are used, the 0 flag is ignored.)

For d , i , o , u , x , and X conversions, the 0 flag is ignored if a precision is specified.

@ for conversions that specify or dereference a pointer (p, s, n, V), treat pointers as _ _far.

The field width specifies the minimum number of characters in the converted value. If the value has fewer characters than that specified by the field width, it is padded on the left (or right, if the - flag is used). By default, the pad character is a blank.

The precision specifies the minimum number of digits to appear for the d , i , o , u , p , x, and X conversions. For the e , E, and f conversions, the precision specifies the number of digits to appear after the decimal indicator. For the g and G conversions, the precision specifies the maximum number of significant digits to appear. Finally, the precision specifies the maximum number of characters to be used in the s conversion.

If the precision is explicitly given as 0 and the value to be converted is 0, no characters are written. If no precision is specified, the default precision is 0. The actual width of the field is the wider of that specified by the field width and that specified by the precision.

Precision might be followed by the conversion modifer specified as a tilde (~) followed by a character. The following are acceptable conversion modifier values:
~b argument is binary floating point (IEEE), _ _binfmt.
~h argument is hex floating point, _ _hexfmt.
~n argument pointer is a _ _near pointer.
~f argument pointer is a _ _far pointer.
~l argument pointer is a _ _hugeptr pointer.

An * may be used for either the field width, the precision, or both. If used, the value of the field width or precision is supplied by an int argument. This argument appears in the argument list before the argument to be converted. A negative value for the field width is taken as a - (left-justify) flag followed by a positive field width. A negative value for the precision is ignored.

An hh before a d, i, o, u, x, or X conversion specifier indicates that the conversion applies to a char or unsigned char. An hh before an n conversion specifier indicates that the conversion applies to a pointer to a char.

An h before a d , i , o , u , x , or X conversion specifier indicates that the conversion applies to a short int or unsigned short int . An h before an n conversion specifier indicates that the conversion applies to a pointer to a short int .

An l , z, or t before a d , i , o , u , x , or X conversion specifier indicates that the conversion applies to a long int or an unsigned long int . An l before an n conversion specifier indicates that the conversion applies to a pointer to a long int . An L before an e , E , f , g , or G conversion specifier indicates that the conversion applies to a long double .

An ll, or j before a d, i, o, u, x, or X conversion specifier indicates that the conversion applies to a long long int or unsigned long long int. An ll, or j before an n conversion specifier indicates that the conversion applies to a pointer to a long long int.

An L before an e, E, f, g, or G conversion specifier indicates that the conversion applies to a long double.

The type of conversion to be performed is specified by one of these characters:
a, A converts the corresponding double argument to hexadecimal notation in the style [-]0x.hhhp+dd, where there is one hexadecimal digit (which is nonzero if the argument is a normalized floating-point number and is otherwise unspecified) before the decimal-point character and the number of hexadecimal digits after it is equal to the precision. If the precision is zero and the # flag is not specified, no decimal point character appears. The exponent always contains at least one digit, and only as many additional digits as necessary to represent the decimal exponent of 2. If the value is zero, the exponent is zero.
c converts the corresponding int argument to unsigned char and writes the character.
d , i converts the corresponding int argument to decimal notation.
e , E converts the corresponding double argument to the form [-] d.ddde± dd or [-] d.dddE± dd . The precision has the same effect as with the f conversion. The exponent will be a minimum of two digits.
f converts the corresponding double argument to the form [-] ddd.ddd . The precision indicates the number of digits after the decimal indicator. If no precision is given, the default is 6. If the precision is given as 0, a decimal indicator is not used. If a decimal indicator is used, at least one digit appears before it.
g , G converts the double argument using the f or e (or E ) format. The precision specifies the number of significant digits in the converted result. An e conversion is used if the exponent is greater than the precision or is less than -3. Unless the # (alternate form) flag is used, trailing 0s are removed. The decimal indicator appears only if followed by a digit.
n writes a number into the string addressed by the corresponding int * argument. The number written is the number of characters written to the output stream so far by this call to fprintf .
o converts the corresponding unsigned int argument to octal notation.
p converts the void * argument to a sequence of printable characters. In this implementation, p is converted as if x were specified.
s writes characters from the string addressed by the corresponding char * argument until a terminating null character (`\0') is encountered or the number of characters specified by the precision have been copied. The null character, if encountered, is not written.
u converts the corresponding unsigned int argument to decimal notation.
V is the same as the %s conversion specifier, except that it expects the corresponding argument to be a pointer to a PL/I or Pascal format varying-length character string. See the SAS/C Compiler Interlanguage Communication Feature User's Guide for more information on this conversion specifier.
x , X converts the corresponding unsigned int argument to hexadecimal notation. The letters abcdef are used for x conversion and ABCDEF for X conversion.

A % character can be written by using the sequence %% in the format string. The fprintf formats are described in more detail in the ISO/ANSI C standard.

In support of installations that use terminals with only uppercase characters, this implementation of fprintf accepts any of the lowercase format characters in uppercase. Use of this extension renders a program nonportable.


CAUTION

Binary floating point (BFP) NaN values will always have a minimum of 10 characters with a maximum of 22 characters. Trailing zeros are stripped. The following are two examples of maximum output:
Negative Quiet NaN -nan(q_0fffffffffffff)
Positive Signaling NaN +nan(S_00000000000001)


RETURN VALUE

fprintf returns the number of characters transmitted to the output file.


DIAGNOSTICS

If there is an error during output, fprintf returns a negative value.


PORTABILITY

The %V format is an extension and is not portable. The

~ and @ modifiers are not portable, either.


IMPLEMENTATION

The format string can also contain multibyte characters. For details on how fprintf handles multibyte characters in the format string and in conversions, see Chapter 11, "Multibyte Character Functions," in the SAS/C Library Reference, Volume 2.

fprintf can only produce up to 512 characters per conversion specification, except for %s and %V conversions, which are limited to 16 megabytes.


EXAMPLE

#include <math.h>
#include <stdio.h>
#include <stdlib.h>

main()
{
  int i;
  double x;
  FILE *sysout;

      /* Print a columnar table of logs and square roots to an */
      /*  MVS SYSOUT data set.                                 */
   sysout = fopen("dsn:sysout=a", "w");
   if (!sysout) abort();
   fprintf(sysout, " x %10s  log(x) %10s  sqrt(x)\n\n", " ", " ");

      /* Print heading. */    
   for(i = 1; i <= 20; ++i {
         x = i;
         fprintf(sysout, "%3d%10s%10.5f%10s%10.5f\n",
                 i, " ", log(x), " ", sqrt(x));
   }
   exit(EXIT_SUCCESS);
}


RELATED FUNCTIONS

fscanf , printf , sprintf , vfprintf


SEE ALSO


Chapter Contents

Previous

Next

Top of Page

Copyright © 2004 by SAS Institute Inc., Cary, NC, USA. All rights reserved.