1SCANF(3) 386BSD Programmer's Manual SCANF(3) 2 3NNAAMMEE 4 ssccaannff, ffssccaannff, ssssccaannff, vvssccaannff, vvssssccaannff, vvffssccaannff - input format conversion 5 6SSYYNNOOPPSSIISS 7 ##iinncclluuddee <<ssttddiioo..hh>> 8 9 _i_n_t 10 ssccaannff(_c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, ...) 11 12 _i_n_t 13 ffssccaannff(_F_I_L_E *_s_t_r_e_a_m, _c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, ...) 14 15 _i_n_t 16 ssssccaannff(_c_o_n_s_t _c_h_a_r *_s_t_r, _c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, ...) 17 18 ##iinncclluuddee <<ssttddaarrgg..hh>> 19 20 _i_n_t 21 vvssccaannff(_c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, _v_a__l_i_s_t _a_p) 22 23 _i_n_t 24 vvssssccaannff(_c_o_n_s_t _c_h_a_r *_s_t_r, _c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, _v_a__l_i_s_t _a_p) 25 26 _i_n_t 27 vvffssccaannff(_F_I_L_E *_s_t_r_e_a_m, _c_o_n_s_t _c_h_a_r *_f_o_r_m_a_t, _v_a__l_i_s_t _a_p) 28 29DDEESSCCRRIIPPTTIIOONN 30 The ssccaannff() family of functions scans input according to a _f_o_r_m_a_t as 31 described below. This format may contain _c_o_n_v_e_r_s_i_o_n _s_p_e_c_i_f_i_e_r_s; the 32 results from such conversions, if any, are stored through the _p_o_i_n_t_e_r 33 arguments. The ssccaannff() function reads input from the standard input 34 stream _s_t_d_i_n, ffssccaannff() reads input from the stream pointer _s_t_r_e_a_m, and 35 ssssccaannff() reads its input from the character string pointed to by _s_t_r. The 36 vvffssccaannff() function is analogous to vfprintf(3) and reads input from the 37 stream pointer _s_t_r_e_a_m using a variable argument list of pointers (see 38 stdarg(3)). The vvssccaannff() function scans a variable argument list from 39 the standard input and the vvssssccaannff() function scans it from a string; 40 these are analogous to the vvpprriinnttff() and vvsspprriinnttff() functions 41 respectively. Each successive _p_o_i_n_t_e_r argument must correspond properly 42 with each successive conversion specifier (but see `suppression' below). 43 All conversions are introduced by the %% (percent sign) character. The 44 _f_o_r_m_a_t string may also contain other characters. White space (such as 45 blanks, tabs, or newlines) in the _f_o_r_m_a_t string match any amount of white 46 space, including none, in the input. Everything else matches only 47 itself. Scanning stops when an input character does not match such a 48 format character. Scanning also stops when an input conversion cannot be 49 made (see below). 50 51CCOONNVVEERRSSIIOONNSS 52 Following the %% character introducing a conversion there may be a number 53 of _f_l_a_g characters, as follows: 54 55 ** Suppresses assignment. The conversion that follows occurs as 56 usual, but no pointer is used; the result of the conversion is 57 simply discarded. 58 59 hh Indicates that the conversion will be one of ddiioouuxx or nn and the 60 next pointer is a pointer to a _s_h_o_r_t _i_n_t (rather than _i_n_t). 61 62 ll Indicates either that the conversion will be one of ddiioouuxx or nn 63 and the next pointer is a pointer to a _l_o_n_g _i_n_t (rather than 64 _i_n_t), or that the conversion will be one of eeffgg and the next 65 66 pointer is a pointer to _d_o_u_b_l_e (rather than _f_l_o_a_t). 67 68 LL Indicates that the conversion will be eeffgg and the next pointer is 69 a pointer to _l_o_n_g _d_o_u_b_l_e. (This type is not implemented; the LL 70 flag is currently ignored.) 71 72 In addition to these flags, there may be an optional maximum field width, 73 expressed as a decimal integer, between the %% and the conversion. If no 74 width is given, a default of `infinity' is used (with one exception, 75 below); otherwise at most this many characters are scanned in processing 76 the conversion. Before conversion begins, most conversions skip white 77 space; this white space is not counted against the field width. 78 79 The following conversions are available: 80 81 %% Matches a literal `%'. That is, `%%' in the format string matches 82 a single input `%' character. No conversion is done, and 83 assignment does not occur. 84 85 dd Matches an optionally signed decimal integer; the next pointer must 86 be a pointer to _i_n_t. 87 88 DD Equivalent to ld; this exists only for backwards compatibility. 89 90 ii Matches an optionally signed integer; the next pointer must be a 91 pointer to _i_n_t. The integer is read in base 16 if it begins with 92 `0x' or `0X', in base 8 if it begins with `0', and in base 10 93 otherwise. Only characters that correspond to the base are used. 94 95 oo Matches an octal integer; the next pointer must be a pointer to 96 _u_n_s_i_g_n_e_d _i_n_t. 97 98 OO Equivalent to lo; this exists for backwards compatibility. 99 100 uu Matches an optionally signed decimal integer; the next pointer must 101 be a pointer to _u_n_s_i_g_n_e_d _i_n_t. 102 103 xx Matches an optionally a signed hexadecimal integer; the next 104 pointer must be a pointer to _u_n_s_i_g_n_e_d _i_n_t. 105 106 XX Equivalent to llxx; this violates the ANSI C3.159-1989 (``ANSI C''), 107 but is backwards compatible with previous UNIX systems. 108 109 ff Matches an optionally signed floating-point number; the next 110 pointer must be a pointer to _f_l_o_a_t. 111 112 ee Equivalent to ff. 113 114 gg Equivalent to ff. 115 116 EE Equivalent to llff; this violates the ANSI C3.159-1989 (``ANSI C''), 117 but is backwards compatible with previous UNIX systems. 118 119 FF Equivalent to llff; this exists only for backwards compatibility. 120 121 ss Matches a sequence of non-white-space characters; the next pointer 122 must be a pointer to _c_h_a_r, and the array must be large enough to 123 accept all the sequence and the terminating NUL character. The 124 input string stops at white space or at the maximum field width, 125 whichever occurs first. 126 127 cc Matches a sequence of _w_i_d_t_h count characters (default 1); the next 128 pointer must be a pointer to _c_h_a_r, and there must be enough room 129 for all the characters (no terminating NUL is added). The usual 130 skip of leading white space is suppressed. To skip white space 131 132 first, use an explicit space in the format. 133 134 [[ Matches a nonempty sequence of characters from the specified set of 135 accepted characters; the next pointer must be a pointer to _c_h_a_r, 136 and there must be enough room for all the characters in the string, 137 plus a terminating NUL character. The usual skip of leading white 138 space is suppressed. The string is to be made up of characters in 139 (or not in) a particular set; the set is defined by the characters 140 between the open bracket [ character and a close bracket ] 141 character. The set _e_x_c_l_u_d_e_s those characters if the first 142 character after the open bracket is a circumflex ^^. To include a 143 close bracket in the set, make it the first character after the 144 open bracket or the circumflex; any other position will end the 145 set. The hyphen character -- is also special; when placed between 146 two other characters, it adds all intervening characters to the 147 set. To include a hyphen, make it the last character before the 148 final close bracket. For instance, `[^]0-9-]' means the set 149 `everything except close bracket, zero through nine, and hyphen'. 150 The string ends with the appearance of a character not in the (or, 151 with a circumflex, in) set or when the field width runs out. 152 153 pp Matches a pointer value (as printed by `%p' in printf(3)); the 154 next pointer must be a pointer to _v_o_i_d. 155 156 nn Nothing is expected; instead, the number of characters consumed 157 thus far from the input is stored through the next pointer, which 158 must be a pointer to _i_n_t. This is _n_o_t a conversion, although it can 159 be suppressed with the ** flag. 160 161 For backwards compatibility, other conversion characters (except `\0') 162 are taken as if they were `%d' or, if uppercase, `%ld', and a 163 `conversion' of `%\0' causes an immediate return of EOF. The FF and XX 164 conversions will be changed in the future to conform to the ANSI C 165 standard, after which they will act like ff and xx respectively. 166 167RREETTUURRNN VVAALLUUEESS 168 These functions return the number of input items assigned, which can be 169 fewer than provided for, or even zero, in the event of a matching 170 failure. Zero indicates that, while there was input available, no 171 conversions were assigned; typically this is due to an invalid input 172 character, such as an alphabetic character for a `%d' conversion. The 173 value EOF is returned if an input failure occurs before any conversion 174 such as an end-of-file occurs. If an error or end-of-file occurs after 175 conversion has begun, the number of conversions which were successfully 176 completed is returned. 177 178SSEEEE AALLSSOO 179 strtol(3), strtoul(3), strtod(3), getc(3), printf(3) 180 181SSTTAANNDDAARRDDSS 182 The functions ffssccaannff(), ssccaannff(), and ssssccaannff() conform to ANSI C3.159-1989 183 (``ANSI C''). 184 185HHIISSTTOORRYY 186 The functions vvssccaannff(), vvssssccaannff() and vvffssccaannff() are new to this release. 187 188BBUUGGSS 189 The current situation with %%FF and %%XX conversions is unfortunate. 190 191 All of the backwards compatibility formats will be removed in the future. 192 193 Numerical strings are truncated to 512 characters; for example, %%ff and %%dd 194 are implicitly %%551122ff and %%551122dd. 195 196BSD Experimental January 8, 1993 3 197 198 199