Remarks

• You can change the delimiters of the input field with the bracket ([ ]) conversion specification. Otherwise, an input field is defined as a string of nonwhite-space characters. It extends either to the next white-space character or until the field width, if specified, is exhausted. The function reads across line and record boundaries, since the new-line character is a white-space character.
• A call to one of the input conversion functions resumes searching immediately after the last character processed by a previous call.
• If the assignment-suppression character (*) appears in the format specification, no assignment is made. The corresponding input field is interpreted and then skipped.
• The arguments must be pointers or other address-valued expressions, since Compaq C permits only calls by value. To read a number in decimal format and assign its value to n, you must use the following form:

  scanf("%d", &n)

  You cannot use the following form:

  scanf("%d", n)

• White space in a format specification matches optional white space in the input field. Consider the following format specification:

  field = %x

  
  This format specification matches the following forms:

  field = 5218 field=5218 field= 5218 field =5218

  
  These forms do not match the following example:

  fiel d=5218

The format specification string for the output of information can contain:

• Ordinary characters, which are copied to the output.
• Conversion specifications, each of which causes the conversion of a corresponding output source to a character string in a particular format Conversion specifications are matched to output sources in left-to-right order.

A conversion specification consists of the following, in the order listed:

• A percent character (%) or the sequence %n$.
  The sequence %n$ denotes that the conversion is applied to the nth output source listed, where n is a decimal integer between [1, NL_ARGMAX] (see the <limits.h> header file). For example, a conversion specification beginning %5$ means that the conversion will be applied to the 5th output source listed after the format specification.
  If the conversion specification does not begin with the sequence %n$, the conversion specification is matched to its output source in left-to-right order. You should only use one type of conversion specification (% or %n$) in a format specification.
• One or more optional characters (described in Table 2-4).
• A conversion specifier (described in Table 2-5) concludes the conversion specification.

For examples of conversion specifications, see the sample programs in Section 2.6.

Table 2-4 shows the characters you can use between the percent sign (%) (or the sequence %n$) and the conversion specifier. These characters are optional, but if specified, they must occur in the order shown in Table 2-4.

Table 2-4 Optional Characters Between% (or% n$) and the Output Conversion Specifier

Character	Meaning
flags	You can use the following flag characters, alone or in any combined order, to modify the conversion specification: ' (single quote) Requests that a numeric conversion is formatted with the thousands separator character. Only the numbers to the left of the radix character are formatted with the separator character. The character used as a separator and the positioning of the separators are defined in the program's current locale. -- (hyphen) Left-justifies the converted output source in its field. + Requests that an explicit sign be present on a signed conversion. If this flag is not specified, the result of a signed conversion begins with a sign only when a negative value is converted. space Prefixes a space to the result of a signed conversion, if the first character of the conversion is not a sign, or if the conversion results in no characters. If you specify both the space and the + flag, the space flag is ignored.
	# Requests an alternate conversion format. Depending on the conversion specified, different actions will occur. For the o (octal) conversion, the precision is increased to force the first digit to be a zero. For the x (or X) conversion, a nonzero result is prefixed with 0x (or 0X). For e, E, f, g, and G conversions, the result contains a decimal point even at the end of an integer value. For g and G conversions, trailing zeros are not trimmed. For other conversions, the effect of # is undefined. 0 Uses zeros rather than spaces to pad the field width for d, i, o, u, x, X, e, E, f, g, and G conversions. If both the 0 and the -- flags are specified, then the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag is ignored. For other conversions, the behavior of the 0 flag is undefined.
field width	The minimum field width can be designated by a decimal integer constant, or by an output source. To specify an output source, use an asterisk (*) or the sequence * n$, where n refers to the nth output source listed after the format specification. The minimum field width is considered after the conversion is done according to the all other components of the format directive. This component affects padding the result of the conversion as follows: If the result of the conversion is wider than the minimum field, write it out. If the result of the conversion is narrower than the minimum width, pad it to make up the field width. Pad with spaces by default. Pad with zeros if the 0 flag is specified; this does not mean that the width is an octal number. Padding is on the left by default, and on the right if a minus sign is specified. For the wide-character output functions, the field width is measured in wide characters; for the byte output functions, it is measured in bytes.
. (period)	Separates the field width from the precision.
precision	The precision defines any of the following: Minimum number of digits to appear for d, i, o, u, x, and X conversions Number of digits to appear after the decimal-point character for e, E, and f conversions Maximum number of significant digits for g and G conversions Maximum number of characters to be written from a string in an s or S conversion If a precision appears with any other conversion specifier, the behavior is undefined. Precision can be designated by a decimal integer constant, or by an output source. To specify an output source, use an asterisk (*) or the sequence * n$, where n refers to the nth output source listed after the format specification. If only the period is specified, the precision is taken as 0.
h, l, or L (or ll)	An h specifies that a following d, i, o, u, x, or X conversion specifier applies to a short int or unsigned short int argument; an h can also specify that a following n conversion specifier applies to a pointer to a short int argument. An l (lowercase ell) specifies that a following d, i, o, u, x, or X conversion specifier applies to a long int or unsigned long int argument; an l can also specify that a following n conversion specifier applies to a pointer to a long int argument. On OpenVMS Alpha systems, an L or ll (two lowercase ells) specifies that a following d, i, o, u, x, or X conversion specifier applies to an __int64 or unsigned __int64 argument. (ALPHA ONLY) An L specifies that a following e, E, f, g, or G conversion specifier applies to a long double argument. An l specifies that a following c or s conversion specifier applies to a wchar_t argument. If an h, l, or L appears with any other conversion specifier, the behavior is undefined. On OpenVMS VAX and OpenVMS Alpha systems, Compaq C int values are equivalent to long values.

Table 2-5 decribes the conversion specifiers for formatted output.

Table 2-5 Conversion Specifiers for Formatted Output

Specifier	Output Type1	Description
d, i		Converts an int argument to signed decimal format.
o		Converts an unsigned int argument to unsigned octal format.
u		Converts an unsigned int argument to unsigned decimal format (giving a number in the range 0 to 4,294,967,295).
x, X		Converts an unsigned int argument to unsigned hexadecimal format (with or without a leading 0x). The letters abcdef are used for x conversion, and the letters ABCDEF are used for X conversion.
f		Converts a float or double argument to the format [--]mmm.nnnnnn. The number of n's is equal to the precision specification: If no precision is specified, the default is 6. If the precision is 0 and the # flag is specified, the decimal point appears but no n's appear. If the precision is 0 and the # flag is not specified, the decimal point also does not appear. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.
e, E		Converts a float or double argument to the format [--]m.nnnnnnE<pm symbol>xx. The number of n's is specified by the precision. If no precision is specified, the default is 6. If the precision is explicitly 0 and the # flag is specified, the decimal point appears but no n's appear. If the precision is explicitly 0 and the # flag is not specified, the decimal point also does not appear. An 'e' is printed for e conversion; an 'E' is printed for E conversion. The exponent always contains at least two digits. If the value is 0, the exponent is 0.
g, G		Converts a float or double argument to format f or e (or E if the G conversion specifier is used), with the precision specifying the number of significant digits. If the precision is 0, it is taken as 1. The format used depends on the value of the argument: format e (or E) is used only if the exponent resulting from such a conversion is less than --4, or is greater than or equal to the precision; otherwise, format f is used. Trailing zeros are suppressed in the fractional portion of the result. A decimal point appears only if it is followed by a digit.
c	Byte	Converts an int argument to an unsigned char , and writes the resulting byte. If the optional character l (lowercase ell) precedes this conversion specifier, then the specifier converts a wchar_t argument to an array of bytes representing the character, and writes the resulting character. If the field width is specified and the resulting character occupies fewer bytes than the field width, it will be padded to the given width with space characters. If the precision is specified, the behavior is undefined.
	Wide-character	If an l (lowercase ell) does not precede the c specifier, then the int argument is converted to a wide character as if by calling btowc , and the resulting character is written. If an l (lowercase ell) precedes the c specifier, then the specifier converts a wchar_t argument to an array of bytes representing the character, and writes the resulting character. If the field width is specified and the resulting character occupies fewer characters than the field width, it will be padded to the given width with space characters. If the precision is specified, the behavior is undefined.
C	Byte	Converts a wchar_t argument to an array of bytes representing the character, and writes the resulting character. If the field width is specified and the resulting character occupies fewer bytes than the field width, it will be padded to the given width with space characters. If the precision is specified, the behavior is undefined.
	Wide-character	Converts a wchar_t argument to an array of bytes representing the character, and writes the resulting character. If the field width is specified and the resulting character occupies fewer wide characters than the field width, it will be padded to the given width with space characters. If the precision is specified, the behavior is undefined.
s	Byte	Requires an argument that is a pointer to an array of characters of type char . The argument is used to write characters until a null character is encountered or until the number of characters indicated by the precision specification is exhausted. If the precision specification is 0 or omitted, all characters up to a null are output. If the optional character l (lowercase ell) precedes this conversion specifier, then the specifier converts an array of wide-character codes to multibyte characters, and writes the multibyte characters. Requires an argument that is a pointer to an array of wide characters of type wchar_t . Characters are written until a null wide character is encountered or until the number of bytes indicated by the precision specification is exhausted. If the precision specification is omitted or is greater than the size of the array of converted bytes, the array of wide characters must be terminated by a null wide character.
	Wide-character	If an l (lowercase ell) does not precede the s specifier, then the specifier converts an array of multibyte characters, as if by calling mbrtowc for each multibyte character, and writes the resulting characters until a null wide character is encountered or the number of wide characters indicated by the precision specification is exhausted. If the precision specification is omitted or is greater than the size of the array of converted characters, the converted array must be terminated by a null wide character. If an l precedes this conversion specifier, then the argument is a pointer to an array of wchar_t . Characters from this array are written until a null wide character is encountered or the number of wide characters indicated by the precision specification is exhausted. If the precision specification is omitted or is greater than the size of the array, the array must be terminated by a null wide character.
S	Byte	Converts an array of wide-character codes to multibyte characters, and writes the multibyte characters. Requires an argument that is a pointer to an array of wide characters of type wchar_t . Characters are written until a null wide character is encountered or until the number of bytes indicated by the precision specification is exhausted. If the precision specification is omitted or is greater than the size of the array of converted bytes, the array of wide characters must be terminated by a null wide character.
	Wide-character	The argument is a pointer to an array of wchar_t . Characters from this array are written until a null wide character is encountered or the number of wide characters indicated by the precision specification is exhausted. If the precision specification is omitted or is greater than the size of the array, the array must be terminated by a null wide character.
p		Requires an argument that is a pointer to void . The value of the pointer is output as a hexadecimal number.
n		Requires an argument that is a pointer to an integer. The integer is assigned the number of characters written to the output stream so far by this call to the formatted output function. No argument is converted.
%		Writes out the percent symbol. No conversion is performed. The complete conversion specification would be %%.

Compaq C defines three file pointers that allow you to perform I/O to and from the logical devices usually associated with your terminal (for interactive jobs) or a batch stream (for batch jobs). In the OpenVMS environment, the three permanent process files SYS$INPUT, SYS$OUTPUT, and SYS$ERROR perform the same functions for both interactive and batch jobs. Terminal I/O refers to both terminal and batch stream I/O. The file pointers stdin, stdout, and stderr are defined when you include the <stdio.h> header file using the #include preprocessor directive.

The stdin file pointer is associated with the terminal to perform input. This file is equivalent to SYS$INPUT. The stdout file pointer is associated with the terminal to perform output. This file is equivalent to SYS$OUTPUT. The stderr file pointer is associated with the terminal to report run-time errors. This file is equivalent to SYS$ERROR.

There are three file descriptors that refer to the terminal. The file descriptor 0 is equivalent to SYS$INPUT, 1 is equivalent to SYS$OUTPUT, and 2 is equivalent to SYS$ERROR.

When performing I/O at the terminal, you can use Standard I/O functions and macros (specifying the pointers stdin, stdout, or stderr as arguments), you can use UNIX I/O functions (giving the corresponding file descriptor as an argument), or you can use the Terminal I/O functions and macros. There is no functional advantage to using one type of I/O over another; the Terminal I/O functions might save keystrokes since there are no arguments.

2.6 Program Examples

This section gives some program examples that show how the I/O functions can be used in applications.

Example 2-1 shows the printf function.

Example 2-1 Output of the Conversion Specifications

/* CHAP_2_OUT_CONV.C */ /* This program uses the printf function to print the */ /* various conversion specifications and their affect */ /* on the output. */ /* Include the proper header files in case printf has */ /* to return EOF. */ #include <stdlib.h> #include <stdio.h> #include <wchar.h> #define WIDE_STR_SIZE 20 main() { double val = 123345.5; char c = 'C'; int i = -1500000000; char *s = "thomasina"; wchar_t wc; wchar_t ws[WIDE_STR_SIZE]; /* Produce a wide character and a wide character string */ if (mbtowc(&wc, "W", 1) == -1) { perror("mbtowc"); exit(EXIT_FAILURE); } if (mbstowcs(ws, "THOMASINA", WIDE_STR_SIZE) == -1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Print the specification code, a colon, two tabs, and the */ /* formatted output value delimited by the angle bracket */ /* characters (<>). */ printf("%%9.4f:\t\t<%9.4f>\n", val); printf("%%9f:\t\t<%9f>\n", val); printf("%%9.0f:\t\t<%9.0f>\n", val); printf("%%-9.0f:\t\t<%-9.0f>\n\n", val); printf("%%11.6e:\t\t<%11.6e>\n", val); printf("%%11e:\t\t<%11e>\n", val); printf("%%11.0e:\t\t<%11.0e>\n", val); printf("%%-11.0e:\t\t<%-11.0e>\n\n", val); printf("%%11g:\t\t<%11g>\n", val); printf("%%9g:\t\t<%9g>\n\n", val); printf("%%d:\t\t<%d>\n", c); printf("%%c:\t\t<%c>\n", c); printf("%%o:\t\t<%o>\n", c); printf("%%x:\t\t<%x>\n\n", c); printf("%%d:\t\t<%d>\n", i); printf("%%u:\t\t<%u>\n", i); printf("%%x:\t\t<%x>\n\n", i); printf("%%s:\t\t<%s>\n", s); printf("%%-9.6s:\t\t<%-9.6s>\n", s); printf("%%-*.*s:\t\t<%-*.*s>\n", 9, 5, s); printf("%%6.0s:\t\t<%6.0s>\n\n", s); printf("%%C:\t\t<%C>\n", wc); printf("%%S:\t\t<%S>\n", ws); printf("%%-9.6S:\t\t<%-9.6S>\n", ws); printf("%%-*.*S:\t\t<%-*.*S>\n", 9, 5, ws); printf("%%6.0S:\t\t<%6.0S>\n\n", ws); }

Running Example 2-1 produces the following output:

$ RUN EXAMPLE %9.4f: <123345.5000> %9f: <123345.500000> %9.0f: < 123346> %-9.0f: <123346 > %11.6e: <1.233455e+05> %11e: <1.233455e+05> %11.0e: < 1e+05> %-11.0e: <1e+05 > %11g: < 123346> %9g: < 123346> %d: <67> %c: <C> %o: <103> %x: <43> %d: <-1500000000> %u: <2794967296> %x: <a697d100> %s: <thomasina> %-9.6s: <thomas > %-*.*s: <thoma > %6.0s: < > %C: <W> %S: <THOMASINA> %-9.6S: <THOMAS > %-*.*S: <THOMA > %6.0S: < > $

Example 2-2 shows the use of the fopen , ftell , sprintf , fputs , fseek , fgets , and fclose functions.

Example 2-2 Using the Standard I/O Functions

/* CHAP_2_STDIO.C */ /* This program establishes a file pointer, writes lines from */ /* a buffer to the file, moves the file pointer to the second */ /* record, copies the record to the buffer, and then prints */ /* the buffer to the screen. */ #include <stdio.h> #include <stdlib.h> main() { char buffer[32]; int i, pos; FILE *fptr; /* Set file pointer. */ fptr = fopen("data.dat", "w+"); if (fptr == NULL) { perror("fopen"); exit(EXIT_FAILURE); } for (i = 1; i < 5; i++) { if (i == 2) /* Get position of record 2. */ pos = ftell(fptr); /* Print a line to the buffer. */ sprintf(buffer, "test data line %d\n", i); /* Print buffer to the record. */ fputs(buffer, fptr); } /* Go to record number 2. */ if (fseek(fptr, pos, 0) < 0) { perror("fseek"); /* Exit on fseek error. */ exit(EXIT_FAILURE); } /* Read record 2 in the buffer. */ if (fgets(buffer, 32, fptr) == NULL) { perror("fgets"); /* Exit on fgets error. */ exit(EXIT_FAILURE); } /* Print the buffer. */ printf("Data in record 2 is: %s", buffer); fclose(fptr); /* Close the file. */ }