scanf, scanf_l -- convert formatted input

SYNOPSIS

#include <stdio.h>

#include <stdarg.h>

int fscanf(FILE *stream, const char *format, ...);

int scanf(const char *format, ...);

int sscanf(const char *s, const char *format, ...);

int vfscanf(FILE *stream, const char *format, va_list ap);

int vscanf(const char *format, va_list ap);

int vsscanf(const char *s, const char *format, va_list ap);

#include <wchar.h>

#include <stdarg.h>

int wscanf(const wchar_t *format, ...);

int fwscanf(FILE *stream, const wchar_t *format, ...);

int swscanf(const wchar_t *s, const wchar_t *format, ...);

int vfwscanf(FILE *stream, const wchar_t *format, va_list ap);

int vswscanf(const wchar_t *s, const wchar_t *format, va_list ap);

int vwscanf(const wchar_t *format, va_list ap);

#include <stdio.h>

#include <locale.h>

int fscanf_l(FILE *stream, locale_t locale, const char *format, ...);

int scanf_l(locale_t locale, const char *format, ...);

int sscanf_l(const char *s, locale_t locale, const char *format, ...);

int vfscanf_l(FILE *stream, locale_t locale, const char *format, va_list ap);

int vscanf_l(locale_t locale, const char *format, va_list ap);

#include <wchar.h> #include <locale.h>

int vswscanf_l(const wchar_t *s, locale_t locale, const wchar_t *format, va_list ap);

int fwscanf_l(FILE *stream, locale_t locale, const wchar_t *format, ...);

int swscanf_l(const wchar_t *s, locale_t locale, const wchar_t *format, ...);

int vfwscanf_l(FILE *stream, locale_t locale, const wchar_t *format, va_list ap);

int vsscanf_l(const char *s, locale_t locale, const char *format, va_list ap);

int wscanf_l(locale_t locale, const wchar_t *format, ...);

int vwscanf_l(locale_t locale, const wchar_t *format, va_list ap);

These functions convert formatted input. The fscanf() and vfscanf() functions read from the specified stream. The scanf() and vscanf() functions read from the standard input stream stdin. The sscanf() and vsscanf() functions read from the specified string.

The fwscanf(), swscanf(), vfwscanf(), vswscanf(), wscanf() and vwscanf() functions are wide character versions of fscanf(), sscanf(), vfscanf(), vsscanf(), scanf() and vscanf() respectively. In all other ways, the wide character versions of these functions behave in an identical fashion to the narrow character versions.

These functions read characters, interpret them according to a format, and store the results in its arguments. They expect, as parameters, an input source (as specified above), a control (format) string, described below, and either a set of pointer arguments indicating where the converted input should be stored (for fscanf(), scanf(), and sscanf()) or an argument list of type va_list defined by the <stdarg.h> header indicating where the converted input should be stored (for vfscanf(), vscanf() and vsscanf()). If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are simply ignored.

Many of the scanf() family of functions have an _l() variant. These functions are used to convert formatted input in the locale locale (perhaps returned from newlocale(). They behave in the same way as the versions without the _l suffix, except where but use the specified locale rather than the global or per-thread locale.

The vfscanf(), vscanf() and vsscanf() functions do not invoke the va_end macro. As this function invokes the va_arg macro, the value of the parameter ap after return is indeterminate.

The control string directs interpretation of input sequences and may consist of white-space characters (blanks, tabs, new-lines, or form-feeds), ordinary characters (neither a white-space character nor %, or a conversion specification.

White-space characters, with the exception of the two cases below, cause input to be read up to the next non-white-space character.

Ordinary characters must match the next character from the input stream.

Conversion specifications begin with % and can be followed, in sequence with:

An optional asterisk (*) to suppress the next assignment. The conversion that follows occurs as usual, but no pointer is used; the result of the conversion is simply discarded.

An optional non-zero decimal integer to specify the maximum filed width.

An optional modifier that specifies the size of the receiving object. Valid size modifiers include:

h

When the following conversion code is d, i, n, o, u, or x, the argument is a pointer to short int or unsigned short int rather than a pointer to int or unsigned int.

I32

is equivalent to l.

I64

is equivalent to ll.

l

When the following conversion code is d, i, n, o, u, or x, the argument is a pointer to long int or unsigned long int rather than a pointer to int or unsigned int.

When the following conversion code is e, f, or g, the argument is a pointer to double rather than a pointer to float.

ll

When the following conversion code is d, i, o, u, or x, the argument is a pointer to quad_t or unsigned quad_t rather than a pointer to int or unsigned int.

Note:

While the type quad_t is used here for 64-bit integer, the types long long and __int64 are equivalent and also acceptable.

L

When the following conversion code is e, f, or g, the argument is a pointer to long double rather than a pointer to float.

When the following conversion code is d, i, o, u, or x, this size modifier is equivalent to ll.

q

is equivalent to ll.

A conversion specification directs the conversion of the next input field; the result is placed in the variable pointed to by the corresponding argument unless assignment suppression was indicated by the character *. The suppression of assignment provides a way of describing an input field that is to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the maximum field width, if one is specified, is exhausted. For all descriptors except the character [ and the character c, white space leading an input field is ignored.

The conversion code indicates the interpretation of the input field; the corresponding pointer argument must usually be of a restricted type. For a suppressed field, no pointer argument is given. The following codes are valid:

%

A single % is expected in the input at this point; no assignment is done.

c

Matches a sequence of characters of the number specified by the field width (1 if no field width is present in the directive). The corresponding argument should be a pointer to the initial character of an array large enough to accept the sequence. No null character is added. The normal skip over white space is suppressed. The conversion specifier hC is equivalent.

C

Same as lc. Matches a sequence of wide characters of the number specified by the field width (1 if no field width is present in the directive). The corresponding argument should be a pointer to the initial character of an array large enough to accept the sequence. No null character is added. The normal skip over white space is suppressed.

d

Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the strtol() function with the value 10 for the base argument. The corresponding argument should be a pointer to integer.

D

Same as d.

e

f

g

Matches an optionally signed floating point number, whose format is the same as expected for the subject string of the strtod() function. The corresponding argument should be a pointer to a floating point value.

E

Same as e.

F

Same as f.

i

Matches an optionally signed integer, whose format is the same as expected for the subject sequence of strtol() function with the value 0 for the base argument. The corresponding argument should be a pointer to an integer.

n

No input is consumed. The corresponding argument should be a pointer to an integer into which is to be written the number of characters read from the input stream so far by the call to the function. Execution of a %n directive does not increment the assignment count returned at the completion of the execution of the function. It may be suppressed with the * flag.

o

Matches an unsigned octal integer, whose format is the same as expected for the subject sequence of the strtoul() function with the value 8 for the base argument. The corresponding argument should be a pointer to an integer.

O

Same as o.

p

Matches the set of sequences produced as output by the %p conversion of the printf() functions. The corresponding argument should be a pointer to void (void *). If the input item is a value converted earlier during the same program execution, the pointer that results compares equal to that value; otherwise, the behavior of the %p conversion is undefined.

s

A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating \0, which is added automatically. A white-space character terminates the input field. The conversion specifier hS is equivalent.

S

Same as ls. A wide character string is expected; the corresponding argument should be a wide character pointer pointing to an array of wide characters large enough to accept the wide character string and a terminating \0, which is added automatically. A white-space character terminates the input field.

u

Matches an unsigned decimal integer, whose format is the same as expected for the subject sequence of the strtoul() with the value 10 for the base argument. The corresponding argument should be a pointer to an integer.

x

Matches an unsigned hexadecimal integer, whose format is the same as expected for the subject sequence of the strtoul() function with the value of 16 for the base argument. The corresponding argument should be a pointer to an unsigned integer.

X

Same as x.

[

Matches a nonempty sequence of characters from a set of expected characters (the scanset). The corresponding argument should be a pointer to the initial character of an array large enough to accept the sequence and a terminating null character, which is added automatically. The conversion specifier includes all subsequent characters in the format string, up to and including the matching right bracket (]). The characters between the brackets (the scanlist) comprise the scanset, unless the character after the left bracket is a circumflex (^), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right bracket. If the conversion specifier begins with [] or [^], the right bracket character is in the scanlist and the next right bracket character is the matching right bracket that ends the specification; otherwise the first right bracket character is the one that ends the specification.

A range of characters in the scanset may be represented by the construct first-last; thus [0123456789] may be expressed [0-9]. Using this convention, first must be lexically less than or equal to last, or else the dash stands for itself. The character - also stands for itself whenever it is the first or the last character in the scanlist. To include the right bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanlist and in this case it is not syntactically interpreted as the closing bracket. At least one character must match for this conversion to be considered successful.

If an invalid conversion code follows the %, the results of the operation may not be predictable.

Each function allows for detection of a language dependent decimal point character in the input string. The decimal point character is defined by the program's locale (category LC_NUMERIC). In the C locale, or in a locale where the decimal point character is not defined, the decimal point character defaults to a period (.).

The conversion terminates at the end of file (for fscanf(), scanf(), vfscanf(), and vscanf() functions), at the end of the input string (for sscanf() and vsscanf()), at the end of the control string, or when an input character conflicts with the control string.

If end-of-file (EOF) is encountered during input, conversion is terminated. If EOF occurs before any characters matching the current directive have been read (other that leading white space, where permitted), execution of the current directive terminates with an input failure; otherwise, unless execution of the current directive of the following directive (if any) is terminated with an input failure.

If conversion terminates on a conflicting input character, the offending input character is left unread in the input stream. Trailing white space (including new-line characters) is left unread unless matched by a directive. The success of literal matches and suppressed assignments is not directly determinable other than via the %N directive.

PARAMETERS

stream: Points to the input stream.
s: Is the string from which the input is read.
format: Specifies the format of the data to be read.
...: Represents optional arguments to hold the results of the scan, based on format.
ap: Is an argument list, of type va_list, to hold the results of the scan, based on format.

RETURN VALUES

The scanf() functions return the number of successfully matched and assigned input items. If an early matching failure between an input character and the control string occurs, this number can be zero. If the input ends before the first matching failure or conversion, the scanf() functions return EOF, and set errno to one of the following values:

EAGAIN: The O_NONBLOCK flag is set for the file descriptor's underlying stream and the process would be delayed.
EBADF: The file descriptor's underlying stream is not a valid file descriptor open for reading.
EILSEQ: Input byte sequence does not form a valid character.
EINTR: A signal interrupted the call.
EINVAL: There are insufficient arguments.
EIO: A physical I/O error has occurred.
EOVERFLOW: The file is a regular file and an attempt was made to read at or beyond the offset associated with the corresponding stream.
ENOMEM: Insufficient storage space is available.
ENXIO: A request was made of a non-existent device, or the request was outside the capabilities of the device.
EOVERFLOW: The file is a regular file and an attempt was made to read at or beyond the offset maximum associated with the corresponding stream.

CONFORMANCE

fscanf(), scanf(), sscanf(): UNIX 98, with exceptions.

vfscanf(), vscanf(), vsscanf(): 4.4BSD, with exceptions

MULTITHREAD SAFETY LEVEL

scanf(), fscanf(), sscanf(): MT-Safe, with exceptions.

vfscanf(), vscanf(), vsscanf(): MT-Safe, with exceptions.

These functions are MT-Safe as long as no thread calls setlocale() while these functions are executing.

PORTING ISSUES

The NuTCRACKER Platform implementation of the scanf() family of functions adds several additional conversion specification characters to those defined by UNIX 98 and 4.4BSD; these are all detailed in the DESCRIPTION section. The NuTCRACKER Platform implementation currently does not recognize the %n$ positional-parameter specifier defined in UNIX 98.

Earlier implementations of scanf() treated %D, %E, %F, %O and %X as their lowercase equivalents with an l modifier. In addition, scanf() treated an unknown conversion character as %d or %D, depending on its case. This functionality has been removed for compatibility with UNIX 98. Note that for backwards compatibility purposes, applications linked to version 10.0 of MKS Toolkit and earlier will continue to behave as before - only once these applications are relinked, this new behavior will be seen.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

scanf, scanf_l
convert formatted input

Command