OSF

NAME

scanf, fscanf, sscanf −  Converts formatted input

LIBRARY

Standard I/O package (libc.a)

SYNOPSIS

#include <stdio.h> int scanf (
const char ∗format [ , pointer, ... ] ); int fscanf (
FILE ∗stream,
const char ∗format [ , pointer, ... ] ); int sscanf (
const char ∗string,
const char ∗format [ , pointer, ... ] );

PARAMETERS

formatSpecifies the format conversion. 

streamSpecifies the input stream. 

stringSpecifies input to be read. 

pointerPoints to location to store interpreted data. 

DESCRIPTION

The scanf(), fscanf(), and sscanf() functions read character data, interpret it according to a format, and store the converted results into specified memory locations. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. 

These functions read their input from the following sources:

scanf()Reads from standard input (stdin). 

fscanf()Reads from the stream parameter. 

sscanf()Reads from the character string specified by the string parameter. 

The format parameter contains conversion specifications used to interpret the input. The pointer parameters specify where to store the interpreted data. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated as always but are otherwise ignored. 

The format parameter can contain white-space characters (blanks, tabs, newline, or formfeed) that, except in the following two cases, read the input up to the next nonwhite-space character. Unless there is a match in the control string, trailing white space (including a newline character) is not read. 

       •Any character except % (percent sign), which must match the next character of the input stream. 

       •A conversion specification that directs the conversion of the next input field. 

Conversion Specifications

Each conversion specification in the format parameter contains the following elements:

       •The character % (percent sign)

       •The optional assignment suppression character ∗ (asterisk)

       •An optional numeric maximum field width

       •An optional character that sets the size of the receiving variable as for some flags, as follows:

lSigned long integer rather than an int when preceding the d, u, o, or x conversion codes. 

LA double rather than a float, when preceding the e, f, or g conversion codes. 

hSigned short integer (half int) rather than an int when preceding the d, u, o, or x conversion codes. 

       •A conversion code

The conversion specification has the following syntax: %[∗][width][size]convcode

The results from the conversion are placed in ∗pointer unless you specify assignment suppression with ∗ (asterisk). Assignment suppression provides a way to describe an input field that is to be skipped. The input field is a string of nonwhite-space characters.  It extends to the next inappropriate character or until the field width, if specified, is exhausted. 

The conversion code indicates how to interpret the input field.  The corresponding pointer must usually be of a restricted type. You should not specify the pointer parameter for a suppressed field. You can use the following conversion codes:

%Accepts a single % (percent sign) input at this point; no assignment is done. 

d, iAccepts a decimal integer; the pointer parameter should be an integer pointer. 

uAccepts an unsigned decimal integer; the pointer parameter should be an unsigned integer pointer. 

oAccepts an octal integer; the pointer parameter should be an integer pointer. 

xAccepts a hexadecimal integer; the pointer parameter should be an integer pointer. 

e, f, gAccepts a floating-point number.  The next field is converted accordingly and stored through the corresponding parameter, which should be a pointer to a float. The input format for floating-point numbers is a string of digits, with the following optional characteristics:

       •It can be a signed value. 

       •It can be an exponential value, containing a decimal point followed by an exponent field, which consists of an E or an e followed by an (optionally signed) integer. 

       •It can be one of the special values INF, NaNQ, or NaNS. This value is translated into the ANSI/IEEE value for infinity, quiet NaN, or signaling NaN, respectively. 

For Japanese Language Support, the conversion codes recognize double-width versions of digits as equivalent to the single-width versions of those digits. 

pMatches an unsigned hexadecimal integer, the same as the &p conversion of the printf() function. The corresponding argument will be a pointer to a pointer to void. 

nNo input is consumed. The corresponding argument is a pointer to an integer into which is written the number of characters read from the input stream so far by this function. The assignment count returned at the completion of this function is not incremented. 

sAccepts a string of characters. The pointer parameter should be a character pointer that points to an array of characters large enough to accept the string and ending with \0.  The \0 is added automatically. The input field ends with a white-space character. A string of char values is output. 

cA char value is expected. The pointer parameter should be a char pointer. The normal skip over white space is suppressed. Use %ls to read the next nonwhite-space character.  If a field width is given, pointer refers to a character array, and the indicated number of char values is read. 

cFor Japanese Language Support, a char value is expected and the pointer parameter should be a char pointer. The normal skip over white space is again suppressed, and %ls is used to read the next nonwhite-space char value. If a field width is given, pointer refers to a character array, and the indicated number of char values is read. 

[scanset]Accepts as input the characters included in the scanset. The scanset explicitly defines the characters that are accepted in the string data as those enclosed within square brackets. The leading white space that is normally skipped over is suppressed. A scanset in the form of [^scanset] is an exclusive scanset: the ^ (circumflex) serves as a complement operator and the following characters in the scanset are not accepted as input. Conventions used in the construction of the scanset follow:

       •You can represent a range of characters by the construct First-Last. Thus, you can express [0123456789] as [0-9]. The First parameter must be lexically less than or equal to Last, or else the - (dash) stands for itself. The - also stands for itself whenever it is the first or the last character in the scanset. 

       •You can include the ] (right bracket) as an element of the scanset if it is the first character of the scanset. In this case it is not interpreted as the bracket that closes the scanset.  If the scanset is an exclusive scanset, the ] is preceded by the ^ (circumflex) to make the ] an element of the scanset.  The corresponding pointer parameter must point to a character array large enough to hold the data field and that ends with 0 (zero). The 0 is added automatically. 

A scanf() ends at the end of the file, the end of the control string, or when an input character conflicts with the control string. If it ends with an input character conflict, the conflicting character is not read from the input stream. 

Unless there is a match in the control string, trailing white space (including a newline character) is not read. 

The success of literal matches and suppressed assignments is not directly determinable. 

Japanese Language Support

The NLS extensions to the scanf() functions can handle a format string that enables the system to process elements of the argument list in variable order. The normal conversion character % (percent sign) is replaced by %digit$, where digit is a decimal number.  Conversions are then applied to arguments in the list with ordinal digits, rather than to the next unused argument. 

The following restrictions apply:

       •The format passed to the NLS extensions can contain one of the following forms, but not both:

       —
The format of the conversion.

       —
The explicit or implicit argument number.

These forms cannot be mixed within a single format string.

       •The ∗ (asterisk) specification for field width or precision is not permitted with the variable order %digit$ format. 

NOTES

AES Support Level:
Full use

RETURN VALUES

The scanf(), fscanf(), or sscanf() function returns the display length of the string it outputs, which is the number of the display characters in the string, rather than the number of bytes. These functions return EOF on the end of input and on a short count for missing or invalid data items. 

The scanf() functions return the number of successfully matched and assigned input items. This number can be 0 (zero) if there was an early conflict between an input character and the control string. If the input ends before the first conflict or conversion, EOF is returned and errno is set to indicate the error. 

ERRORS

The fscanf() function fails if either the stream is unbuffered, or the stream’s buffer needed to be flushed and the function call caused an underlying write() or lseek() to be invoked.  In addition, if the scanf(), fscanf(), sscanf(), function fails, errno may be set to one of the following values:

[EAGAIN]The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the write operation. 

[EBADF]The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG]An attempt was made to write to a file that exceeds the process’ file size limit or the maximum file size. 

[EINTR]The read operation was interrupted by a signal which was caught, and no data was transferred. 

[EIO]The implementation supports job control, the process is a member of a background process group attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU and the process group of the process is orphaned.  This error may also be returned under implementation-defined conditions. 

[ENOSPC]There was no free space remaining on the device containing the file. 

[EPIPE]An attempt was made to write to a pipe or FIFO that is not open for reading by any process.  A SIGPIPE signal will also be sent to the process. 

RELATED INFORMATION

Functions: atof(3), atoi(3), getc(3), getwc(3), printf(3), wsscanf(3)