SCANN(3F) UNIX Programmer's Manual SCANN(3F) NAME scann, fscann, sscann - formatted input conversion SYNTAX integer n, scann character*(L) format n = scann(format [ , arg ] . . . ) integer fileid, n, fscann character*(L) format n = fscann(fileid, format [ , arg ] . . . ) integer n, sscann character*(L) s, format n = sscann(s, format [ , arg ] . . . ) DESCRIPTION _S_c_a_n_n reads from the standard input _s_t_d_i_n. _F_s_c_a_n_n reads from the file associated with _f_i_l_e_i_d. _S_s_c_a_n_n reads from the character string _s, which should be terminated by a null ('\0') character. Each function reads characters, inter- prets them according to a format, and stores the results in its arguments. Each expects as arguments a control string _f_o_r_m_a_t, described below, and a set of arguments into which the converted input is stored. The control string usually contains conversion specifica- tions, which are used to direct interpretation of input sequences. The control string may contain: 1. Blanks, tabs or newlines, which match optional white space in the input. 2. An ordinary character (not %) which must match the next character of the input stream. 3. Conversion specifications, consisting of the character %, an optional assignment suppressing character *, an optional numerical maximum field width, and a conversion character. A conversion specification directs the conversion of the next input field; the result is placed in the the corresponding argument, unless assignment suppression was indicated by *. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. The conversion character indicates the interpretation of the input field; the corresponding argument must usually be of a restricted type. The following conversion characters are Printed 5/17/83 1 SCANN(3F) UNIX Programmer's Manual SCANN(3F) legal: % a single `%' is expected in the input at this point; no assignment is done. d a decimal integer is expected; the corresponding argu- ment should be an integer*2. o an octal integer is expected; the corresponding argument should be an integer*2. x a hexadecimal integer is expected; the corresponding argument should be an integer*2. n (Equivalent to 'ld' or 'D'.) A decimal integer is expected; the corresponding argument should be an integer*4. s a character string is expected; the corresponding argu- ment should be a character string large enough to accept the string and a terminating `\0', which will be added. The input field is terminated by a space character or a newline. c a character is expected; the corresponding argument should be a character. The normal skip over space char- acters is suppressed in this case; to read the next non-space character, try `%1s'. If a field width is given, the corresponding argument should refer to a character string, and the indicated number of characters is read. e99f7 a real number is expected; the next field is converted accordingly and stored through the corresponding argu- ment, which should be a _r_e_a_l. The input format for real numbers is an optionally signed string of digits possi- bly containing a decimal point, followed by an optional exponent field consisting of an E or e followed by an optionally signed integer. [ indicates a string not to be delimited by space charac- ters. The left bracket is followed by a set of charac- ters and a right bracket; the characters between the brackets define a set of characters making up the string. If the first character is not circumflex (^), the input field is all characters until the first char- acter not in the set between the brackets; if the first character after the left bracket is ^, the input field is all characters until the first character which is in the remaining set of characters between the brackets. The corresponding argument must point to a character string. Printed 5/17/83 2 SCANN(3F) UNIX Programmer's Manual SCANN(3F) The conversion characters d, o and x may be capitalized or preceded by l to indicate that a integer*4 rather than a integer*2 is in the argument list. Similarly, the conver- sion characters e or f may be capitalized or preceded by l to indicate a double precision rather than a real. The _s_c_a_n_n functions return the number of successfully matched and assigned input items. This can be used to decide how many input items were found. The constant -1 is returned upon end of input; note that this is different from 0, which means that no conversion was done; if conversion was intended, it was frustrated by an inappropriate charac- ter in the input. For example, the call: integer*2 i; real x; character*50 name; scann( '%d%f%s', i, x, name); with the input line: 25 54.32E-1 thompson will assign to _i the value 25, _x the value 5.432, and _n_a_m_e will contain `_t_h_o_m_p_s_o_n_\_0'. Or, integer*2 i; real x; character*50 name; scann('%2d%f%*d%[1234567890]', &i, &x, name); with input: 56789 0123 56a72 will assign 56 to _i, 789.0 to _x, skip `0123', and place the string `56\0' in _n_a_m_e. The next call to _g_e_t_c_h_a_r will return `a'. SEE ALSO atof(3), getc(3F), printn(3F) DIAGNOSTICS The _s_c_a_n_n functions return -1 on end of input, and a short count for missing or illegal data items. BUGS The success of literal matches is not directly determinable. Assignment suppression (see _s_c_a_n_f) does not work yet. AUTHOR Bruce Julian, U.S. Geological Survey, Menlo Park, California Printed 5/17/83 3