1.\" Copyright (c) 1990, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Chris Torek. 6.\" %sccs.include.redist.man% 7.\" 8.\" @(#)scanf.3 6.10 (Berkeley) 04/26/91 9.\" 10.Dd 11.Dt SCANF 3 12.Os 13.Sh NAME 14.Nm scanf , 15.Nm fscanf , 16.Nm sscanf , 17.Nm vscanf , 18.Nm vsscanf , 19.Nm vfscanf 20.Nd input format conversion 21.Sh SYNOPSIS 22.Fd #include <stdio.h> 23.Ft int 24.Fn scanf "const char *format" ... 25.Ft int 26.Fn fscanf "FILE *stream" "const char *format" ... 27.Ft int 28.Fn sscanf "const char *str" "const char *format" ... 29.Fd #include <stdarg.h> 30.Ft int 31.Fn vscanf "const char *format" "va_list ap" 32.Ft int 33.Fn vsscanf "const char *str" "const char *format" "va_list ap" 34.Ft int 35.Fn vfscanf "FILE *stream" "const char *format" "va_list ap" 36.Sh DESCRIPTION 37The 38.Fn scanf 39family of functions scans input according to a 40.Fa format 41as described below. 42This format may contain 43.Em conversion specifiers ; 44the results from such conversions, if any, 45are stored through the 46.Em pointer 47arguments. 48The 49.Fn scanf 50function 51reads input from the standard input stream 52.Em stdin , 53.Fn fscanf 54reads input from the stream pointer 55.Fa stream , 56and 57.Fn sscanf 58reads its input from the character string pointed to by 59.Fa str . 60The 61.Fn vfscanf 62function 63is analogous to 64.Xr vfprintf 3 65and reads input from the stream pointer 66.Fa stream 67using a variable argument list of pointers (see 68.Xr stdarg 3 ) . 69The 70.Fn vscanf 71function scans a variable argument list from the standard input and 72the 73.Fn vsscanf 74function scans it from a string; 75these are analogous to 76the 77.Fn vprintf 78and 79.Fn vsprintf 80functions respectively. 81Each successive 82.Em pointer 83argument must correspond properly with 84each successive conversion specifier 85(but see `suppression' below). 86All conversions are introduced by the 87.Cm % 88(percent sign) character. 89The 90.Fa format 91string 92may also contain other characters. 93White space (such as blanks, tabs, or newlines) in the 94.Fa format 95string match any amount of white space, including none, in the input. 96Everything else 97matches only itself. 98Scanning stops 99when an input character does not match such a format character. 100Scanning also stops 101when an input conversion cannot be made (see below). 102.Sh CONVERSIONS 103Following the 104.Cm % 105character introducing a conversion 106there may be a number of 107.Em flag 108characters, as follows: 109.Bl -tag -width indent 110.It Cm * 111Suppresses assignment. 112The conversion that follows occurs as usual, but no pointer is used; 113the result of the conversion is simply discarded. 114.It Cm h 115Indicates that the conversion will be one of 116.Cm dioux 117or 118.Cm n 119and the next pointer is a pointer to a 120.Em short int 121(rather than 122.Em int ) . 123.It Cm l 124Indicates either that the conversion will be one of 125.Cm dioux 126or 127.Cm n 128and the next pointer is a pointer to a 129.Em long int 130(rather than 131.Em int ) , 132or that the conversion will be one of 133.Cm efg 134and the next pointer is a pointer to 135.Em double 136(rather than 137.Em float ) . 138.It Cm L 139Indicates that the conversion will be 140.Cm efg 141and the next pointer is a pointer to 142.Em long double . 143(This type is not implemented; the 144.Cm L 145flag is currently ignored.) 146.El 147.Pp 148In addition to these flags, 149there may be an optional maximum field width, 150expressed as a decimal integer, 151between the 152.Cm % 153and the conversion. 154If no width is given, 155a default of `infinity' is used (with one exception, below); 156otherwise at most this many characters are scanned 157in processing the conversion. 158Before conversion begins, 159most conversions skip white space; 160this white space is not counted against the field width. 161.Pp 162The following conversions are available: 163.Bl -tag -width XXXX 164.It Cm % 165Matches a literal `%'. 166That is, `%\&%' in the format string 167matches a single input `%' character. 168No conversion is done, and assignment does not occur. 169.It Cm d 170Matches an optionally signed decimal integer; 171the next pointer must be a pointer to 172.Em int . 173.It Cm D 174Equivalent to 175.Xr ld ; 176this exists only for backwards compatibility. 177.It Cm i 178Matches an optionally signed integer; 179the next pointer must be a pointer to 180.Em int . 181The integer is read in base 16 if it begins 182with 183.Ql 0x 184or 185.Ql 0X , 186in base 8 if it begins with 187.Ql 0 , 188and in base 10 otherwise. 189Only characters that correspond to the base are used. 190.It Cm o 191Matches an octal integer; 192the next pointer must be a pointer to 193.Em unsigned int . 194.It Cm O 195Equivalent to 196.Xr lo ; 197this exists for backwards compatibility. 198.It Cm u 199Matches an optionally signed decimal integer; 200the next pointer must be a pointer to 201.Em unsigned int . 202.It Cm x 203Matches an optionally a signed hexadecimal integer; 204the next pointer must be a pointer to 205.Em unsigned int . 206.It Cm X 207Equivalent to 208.Cm lx ; 209this violates the 210.St -ansiC , 211but is backwards compatible with previous 212.Ux 213systems. 214.It Cm f 215Matches an optionally signed floating-point number; 216the next pointer must be a pointer to 217.Em float . 218.It Cm e 219Equivalent to 220.Cm f . 221.It Cm g 222Equivalent to 223.Cm f . 224.It Cm E 225Equivalent to 226.Cm lf ; 227this violates the 228.St -ansiC , 229but is backwards compatible with previous 230.Ux 231systems. 232.It Cm F 233Equivalent to 234.Cm lf ; 235this exists only for backwards compatibility. 236.It Cm s 237Matches a sequence of non-white-space characters; 238the next pointer must be a pointer to 239.Em char , 240and the array must be large enough to accept all the sequence and the 241terminating 242.Dv NUL 243character. 244The input string stops at white space 245or at the maximum field width, whichever occurs first. 246.It Cm c 247Matches a sequence of 248.Em width 249count 250characters (default 1); 251the next pointer must be a pointer to 252.Em char , 253and there must be enough room for all the characters 254(no terminating 255.Dv NUL 256is added). 257The usual skip of leading white space is suppressed. 258To skip white space first, use an explicit space in the format. 259.It Cm \&[ 260Matches a nonempty sequence of characters from the specified set 261of accepted characters; 262the next pointer must be a pointer to 263.Em char , 264and there must be enough room for all the characters in the string, 265plus a terminating 266.Dv NUL 267character. 268The usual skip of leading white space is suppressed. 269The string is to be made up of characters in 270(or not in) 271a particular set; 272the set is defined by the characters between the open bracket 273.Cm [ 274character 275and a close bracket 276.Cm ] 277character. 278The set 279.Em excludes 280those characters 281if the first character after the open bracket is a circumflex 282.Cm ^ . 283To include a close bracket in the set, 284make it the first character after the open bracket 285or the circumflex; 286any other position will end the set. 287The hyphen character 288.Cm - 289is also special; 290when placed between two other characters, 291it adds all intervening characters to the set. 292To include a hyphen, 293make it the last character before the final close bracket. 294For instance, 295.Ql [^]0-9-] 296means the set `everything except close bracket, zero through nine, 297and hyphen'. 298The string ends with the appearance of a character not in the 299(or, with a circumflex, in) set 300or when the field width runs out. 301.It Cm p 302Matches a pointer value (as printed by 303.Ql %p 304in 305.Xr printf 3 ) ; 306the next pointer must be a pointer to 307.Em void . 308.It Cm n 309Nothing is expected; 310instead, the number of characters consumed thus far from the input 311is stored through the next pointer, 312which must be a pointer to 313.Em int . 314This is 315.Em not 316a conversion, although it can be suppressed with the 317.Cm * 318flag. 319.El 320.Pp 321For backwards compatibility, 322other conversion characters (except 323.Ql \e0 ) 324are taken as if they were 325.Ql %d 326or, if uppercase, 327.Ql %ld , 328and a `conversion' of 329.Ql %\e0 330causes an immediate return of 331.Dv EOF . 332The 333.Cm F 334and 335.Cm X 336conversions will be changed in the future 337to conform to the 338.Tn ANSI 339C standard, 340after which they will act like 341.Cm f 342and 343.Cm x 344respectively. 345.Pp 346.Sh RETURN VALUES 347These 348functions 349return 350the number of input items assigned, which can be fewer than provided 351for, or even zero, in the event of a matching failure. 352Zero 353indicates that, while there was input available, 354no conversions were assigned; 355typically this is due to an invalid input character, 356such as an alphabetic character for a 357.Ql %d 358conversion. 359The value 360.Dv EOF 361is returned if an input failure occurs before any conversion such as an 362end-of-file occurs. If an error or end-of-file occurs after conversion 363has begun, 364the number of conversions which were successfully completed is returned. 365.Sh SEE ALSO 366.Xr strtol 3 , 367.Xr strtoul 3 , 368.Xr getc 3 , 369.Xr printf 3 370.Sh STANDARDS 371The functions 372.Fn fscanf , 373.Fn scanf , 374and 375.Fn sscanf 376conform to 377.St -ansiC . 378.Sh HISTORY 379The functions 380.Fn vscanf , 381.Fn vsscanf 382and 383.Fn vfscanf 384are new to this release. 385.Sh BUGS 386The current situation with 387.Cm %F 388and 389.Cm %X 390conversions is unfortunate. 391.Pp 392All of the backwards compatibility formats will be removed in the future. 393