SCANF(3s,L) AIX Technical Reference SCANF(3s,L) ------------------------------------------------------------------------------- scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf, wsscanf PURPOSE Converts formatted input. LIBRARY Standard I/O Library (libc.a) SYNTAX #include int scanf (fmt [, ptr, ... ]) char *fmt; int fscanf (stream, fmt [, ptr, ... ]) FILE *stream; char *fmt; int sscanf (s, fmt [, ptr, ... ]) char *s, *fmt; int NLscanf (fmt [, ptr, ... ]) char *fmt; int NLfscanf (stream, fmt [, ptr, ... ]) FILE *stream; char *fmt; int NLsscanf (s, fmt [, ptr, ... ]) char *s, *fmt; int wsscanf (wcs, fmt [, ptr, ...]) wchar_t *wcs; char *fmt; DESCRIPTION The scanf, fscanf, and sscanf subroutines read character data, interpret it according to a format, and store the converted results into specified memory locations. The NLscanf, NLfscanf, and NLsscanf subroutines parallel their corresponding functions, providing conversion types to handle NLchars as well as chars. The wsscanf subroutine is equivalent to sscanf, except that the Processed July 12, 1991 SCANF(3s,L) 1 SCANF(3s,L) AIX Technical Reference SCANF(3s,L) argument wcs specifies a wide character string from which the input is obtained, rather than a string. Reaching the end of the wide character string is equivalent to reaching the end of string for sscanf. If copying takes place between objects that overlap, the behavior is undefined. These subroutines read their input from the following sources: scanf, NLscanf Reads from standard input (stdin). fscanf, NLfscanf Reads from stream. sscanf, NLsscanf Reads from the character string s. wsscanf Reads from the wide character string s. The fmt parameter contains conversion specifications used to interpret the input. The ptr parameters specify where to store the interpreted data. The fmt parameter can contain the following: o White space characters (blanks, tabs, new-lines, or form-feeds) which, except in two cases described following, reads the input up to the next nonwhite space character. Unless there is a match in the control string, trailing white space (including a new-line character) is not read. o Any character except "%" (percent), which must match the next one or more characters of the input stream. o A conversion specification that directs the conversion of the next input field. It consists of the following: - The character "%" (percent) - An 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: l Signed long integer rather than an int when preceding the d, u, o or x conversion codes. A double rather than a float, when preceding the e, f or g conversion codes. h Signed short integer (half int) rather than an int when preceding the d, u, o or x conversion codes. - A conversion code. Each conversion specification in the fmt parameter has a "%" (percent sign) or the character sequence "%digit$", which introduces the conversion specification. Conversions can be applied to the nth argument in the argument list, rather than to the next unused argument. In this case, the conversion character "%" is replaced by the sequence "%digit$", where digit is a decimal integer n in the range of [1, {NL_ARGMAX}], giving the position of the argument inthe argument list. With this feature, format strings can be defined to assure that arguments are selected in an order appropriate for the specified language. %[*][width][size]convcode Processed July 12, 1991 SCANF(3s,L) 2 SCANF(3s,L) AIX Technical Reference SCANF(3s,L) The results from the conversion are placed in *ptr unless you specify assignment suppression with *. 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 ptr must usually be of a restricted type. You should not specify ptr for a suppressed field. You can use the following conversion codes: % Accepts a single "%" input at this point; no assignment is done. d Accepts a decimal integer; ptr should be an integer pointer. u Accepts an unsigned decimal integer; ptr should be an unsigned integer pointer. o Accepts an octal integer; ptr should be an integer pointer. x Accepts a hexadecimal integer; ptr should be an integer pointer. e, f, g Accepts 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 some optional characteristics: o It can be a signed value. o 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. o It can be one of the special values INF, QNaN, or SNaN, which is translated into the ANSI/IEEE value for infinity, quiet NaN, or signalling NaN, respectively. s Accepts a string of chars. The ptr 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 chars is output. S (Used by the NLscanf, NLfscanf, and NLsscanf subroutines only.) Accepts an NLchar string. The ptr parameter should point to an array of characters large enough to accept the string and end with "'\0'". The "'\0'" is added automatically. The input field ends with a white space character. A string of NLchars is output. N (Used by the NLscanf, NLfscanf, and NLsscanf subroutines only.) Accepts an ASCII string, possibly containing extended character information in the form of escape sequences used by the NLescstr and NLunescstr subroutines. (See "display symbols" for a list of these escape sequences.) The output is in the form of NLchars. Processed July 12, 1991 SCANF(3s,L) 3 SCANF(3s,L) AIX Technical Reference SCANF(3s,L) c A character is expected. The ptr parameter should be a character pointer. The normal skip over white space is suppressed. Use "%"1s to read the next nonwhite-space character. If a field width is given, ptr should refer to a character array; the indicated number of characters is read. wc Matches a sequence of multibyte characters of the number specified by the field width (1 if no field width is present in the directive). The corresponding argument is a pointer to the initial wide character of an array large enough to accept the sequence resulting from the conversion. This conversion is the same as that performed by the mbstowcs routine. ws Matches a sequence of non-white space multibyte characters. The corresponding argument is a pointer to the initial wide character of an array large enough to accept the sequence resulting from the conversion and a terminating NULL wide character, which is added automatically. This conversion is the same as that performed by the mbstowcs subroutine. [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 normal skip over leading white space 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: o 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. o The range of characters, which is locale dependent, is determined by the current locale's collation table. o 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 ptr must point to a character array large enough to hold the data field and that ends with "'\0'". The "'\0'" is added automatically. A scanf or NLscanf conversion ends at the end-of-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 character that conflicts is not read from the input stream. Processed July 12, 1991 SCANF(3s,L) 4 SCANF(3s,L) AIX Technical Reference SCANF(3s,L) Note: Unless there is a match in the control string, trailing blanks (including a new-line character) are not read. The success of literal matches and suppressed assignments is not directly determinable. RETURN VALUE The scanf and NLscanf subroutines return the number of successfully matched and assigned input items. This number can be 0 if there was an early conflict between an input character and the control string. If the input ends before the first conflict or conversion, only EOF is returned. The wsscanf subroutine returns the value of the macro EOF if an input failure occurs before any conversion. Otherwise, wsscanf returns the number of input items assigned, which can be fewer than provided for, or even zero in the event of an early matching failure. EXAMPLES 1. To read several values and assign them to variables: int i; float x; char name[50]; scanf ("%d%f%s", &i, &x, name); with the input line: 25 54.32E-1 thompson This assigns to "i" the value "25", to "x" the value "5.432", and to "name" the value "thompson\0". 2. To perform simple pattern-matching while scanning the input: int i; float x; char name[50]; scanf ("%2d%f%*d %[0-9]", &i, &x, name); with the input: 56789 0123 56a72 This assigns "56" to "i", "789.0" to "x", skips "0123", and places the string "56\0" in "name". The next call to getchar returns "a". (See "getc, fgetc, getchar, getw, getwc, fgetwc, getwchar.") Processed July 12, 1991 SCANF(3s,L) 5 SCANF(2,L) AIX Technical Reference SCANF(2,L) RELATED INFORMATION In this book: "getc, fgetc, getchar, getw, getwc, fgetwc, getwchar," "printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf," "stdio," "strtod, atof," "strtol, atol, atoi," "limits.h," and "display symbols." "Introduction to International Character Support" in Managing the AIX Operating System. AIX Guide to Multibyte Character Set (MBCS) Support. Processed July 12, 1991 SCANF(2,L) 6