1.\" $OpenBSD: scanf.3,v 1.17 2009/04/05 19:29:28 martynas Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd $Mdocdate: April 5 2009 $ 35.Dt SCANF 3 36.Os 37.Sh NAME 38.Nm scanf , 39.Nm fscanf , 40.Nm sscanf , 41.Nm vscanf , 42.Nm vsscanf , 43.Nm vfscanf 44.Nd input format conversion 45.Sh SYNOPSIS 46.Fd #include <stdio.h> 47.Ft int 48.Fn scanf "const char *format" ... 49.Ft int 50.Fn fscanf "FILE *stream" "const char *format" ... 51.Ft int 52.Fn sscanf "const char *str" "const char *format" ... 53.Fd #include <stdarg.h> 54.Ft int 55.Fn vscanf "const char *format" "va_list ap" 56.Ft int 57.Fn vsscanf "const char *str" "const char *format" "va_list ap" 58.Ft int 59.Fn vfscanf "FILE *stream" "const char *format" "va_list ap" 60.Sh DESCRIPTION 61The 62.Fn scanf 63family of functions read input according to the given 64.Fa format 65as described below. 66This format may contain 67.Dq conversion specifiers ; 68the results of such conversions, if any, are stored through a set of pointer 69arguments. 70.Pp 71The 72.Fn scanf 73function reads input from the standard input stream 74.Em stdin , 75.Fn fscanf 76reads input from the supplied stream pointer 77.Fa stream , 78and 79.Fn sscanf 80reads its input from the character string pointed to by 81.Fa str . 82.Pp 83The 84.Fn vfscanf 85function is analogous to 86.Xr vfprintf 3 87and reads input from the stream pointer 88.Fa stream 89using a variable argument list of pointers (see 90.Xr stdarg 3 ) . 91The 92.Fn vscanf 93function scans a variable argument list from the standard input and the 94.Fn vsscanf 95function scans it from a string; these are analogous to the 96.Fn vprintf 97and 98.Fn vsprintf 99functions, respectively. 100.Pp 101Each successive 102.Em pointer 103argument must correspond properly with each successive conversion specifier 104(but see the 105.Cm * 106conversion below). 107All conversions are introduced by the 108.Cm % 109(percent sign) character. 110The 111.Fa format 112string may also contain other characters. 113Whitespace (such as blanks, tabs, or newlines) in the 114.Fa format 115string match any amount of whitespace, including none, in the input. 116Everything else matches only itself. 117Scanning stops when an input character does not match such a format character. 118Scanning also stops when an input conversion cannot be made (see below). 119.Sh CONVERSIONS 120Following the 121.Cm % 122character, introducing a conversion, there may be a number of 123.Em flag 124characters, as follows: 125.Bl -tag -width "ll (ell ell)" 126.It Cm * 127Suppresses assignment. 128The conversion that follows occurs as usual, but no pointer is used; 129the result of the conversion is simply discarded. 130.It Cm hh 131Indicates that the conversion will be one of 132.Cm dioux 133or 134.Cm n 135and the next pointer is a pointer to a 136.Li char 137(rather than 138.Li int ) . 139.It Cm h 140Indicates that the conversion will be one of 141.Cm dioux 142or 143.Cm n 144and the next pointer is a pointer to a 145.Li short int 146(rather than 147.Li int ) . 148.It Cm l No (ell) 149Indicates either that the conversion will be one of 150.Cm dioux 151or 152.Cm n 153and the next pointer is a pointer to a 154.Li long int 155(rather than 156.Li int ) , 157or that the conversion will be one of 158.Cm efg 159and the next pointer is a pointer to 160.Li double 161(rather than 162.Li float ) . 163.It Cm \&ll No (ell ell) 164Indicates that the conversion will be one of 165.Cm dioux 166or 167.Cm n 168and the next pointer is a pointer to a 169.Li long long int 170(rather than 171.Li int ) . 172.It Cm L 173Indicates that the conversion will be 174.Cm efg 175and the next pointer is a pointer to 176.Li long double . 177.It Cm j 178Indicates that the conversion will be one of 179.Cm dioux 180or 181.Cm n 182and the next pointer is a pointer to an 183.Li intmax_t 184(rather than 185.Li int ) . 186.It Cm t 187Indicates that the conversion will be one of 188.Cm dioux 189or 190.Cm n 191and the next pointer is a pointer to a 192.Li ptrdiff_t 193(rather than 194.Li int ) . 195.It Cm z 196Indicates that the conversion will be one of 197.Cm dioux 198or 199.Cm n 200and the next pointer is a pointer to a 201.Li size_t 202(rather than 203.Li int ) . 204.It Cm q 205(deprecated) 206Indicates that the conversion will be one of 207.Cm dioux 208or 209.Cm n 210and the next pointer is a pointer to a 211.Li "long long int" 212(rather than 213.Vt int ) . 214.El 215.Pp 216In addition to these flags, there may be an optional maximum field width, 217expressed as a decimal integer, between the 218.Cm % 219and the conversion. 220If no width is given, 221a default of 222.Dq infinity 223is used (with one exception, below); 224otherwise at most this many characters are scanned in processing the 225conversion. 226Before conversion begins, most conversions skip whitespace; 227this whitespace is not counted against the field width. 228.Pp 229The following conversions are available: 230.Bl -tag -width XXXX 231.It Cm % 232Matches a literal `%'. 233That is, 234.Ql %\&% 235in the format string matches a single input 236.Ql % 237character. 238No conversion is done, and assignment does not occur. 239.It Cm d 240Matches an optionally signed decimal integer; 241the next pointer must be a pointer to 242.Li int . 243.It Cm D 244Equivalent to 245.Cm ld ; 246this exists only for backwards compatibility. 247.It Cm i 248Matches an optionally signed integer; 249the next pointer must be a pointer to 250.Li int . 251The integer is read in base 16 if it begins 252with 253.Ql 0x 254or 255.Ql 0X , 256in base 8 if it begins with 257.Ql 0 , 258and in base 10 otherwise. 259Only characters that correspond to the base are used. 260.It Cm o 261Matches an octal integer; 262the next pointer must be a pointer to 263.Li unsigned int . 264.It Cm O 265Equivalent to 266.Cm lo ; 267this exists for backwards compatibility. 268.It Cm u 269Matches an optionally signed decimal integer; 270the next pointer must be a pointer to 271.Li unsigned int . 272.It Cm x 273Matches an optionally signed hexadecimal integer; 274the next pointer must be a pointer to 275.Li unsigned int . 276.It Cm X 277Equivalent to 278.Cm x . 279.It Cm fF 280Matches an optionally signed floating-point number; 281the next pointer must be a pointer to 282.Li float . 283.It Cm e 284Equivalent to 285.Cm f . 286.It Cm g 287Equivalent to 288.Cm f . 289.It Cm E 290Equivalent to 291.Cm f . 292.It Cm G 293Equivalent to 294.Cm f . 295.It Cm s 296Matches a sequence of non-whitespace characters; 297the next pointer must be a pointer to 298.Li char , 299and the provided array must be large enough to accept and store 300all the sequence and the terminating 301.Tn NUL 302character. 303The input string stops at whitespace 304or at the maximum field width, whichever occurs first. 305If specified, the maximum field length refers to the sequence 306being scanned rather than the storage space, hence the provided 307array must be 1 larger for the terminating 308.Tn NUL 309character. 310.It Cm c 311Matches a sequence of characters consuming the number of bytes 312specified by the field width (defaults to 1 if unspecified); 313the next pointer must be a pointer to 314.Li char , 315and there must be enough room for all the characters 316(no terminating 317.Tn NUL 318is added). 319The usual skip of leading whitespace is suppressed. 320To skip whitespace first, use an explicit space in the format. 321.It Cm \&[ 322Matches a nonempty sequence of characters from the specified set 323of accepted characters; 324the next pointer must be a pointer to 325.Li char , 326and there must be enough room for all the characters in the string, 327plus a terminating 328.Tn NUL 329character. 330The usual skip of leading whitespace is suppressed. 331.Pp 332The string is to be made up of characters in 333(or not in) 334a particular set; 335the set is defined by the characters between the open bracket 336.Cm \&[ 337character 338and a close bracket 339.Cm \&] 340character. 341The set 342.Em excludes 343those characters 344if the first character after the open bracket is a circumflex 345.Cm ^ . 346To include a close bracket in the set, 347make it the first character after the open bracket 348or the circumflex; 349any other position will end the set. 350The hyphen character 351.Cm - 352is also special; 353when placed between two other characters, 354it adds all intervening characters to the set. 355To include a hyphen, 356make it the last character before the final close bracket. 357.Pp 358For instance, 359.Ql [^]0-9-] 360means the set 361.Do 362everything except close bracket, zero through nine, and hyphen 363.Dc . 364The string ends with the appearance of a character not in 365(or, with a circumflex, in) the set 366or when the field width runs out. 367.It Cm p 368Matches a pointer value (as printed by 369.Ql %p 370in 371.Xr printf 3 ) ; 372the next pointer must be a pointer to 373.Li void . 374.It Cm n 375Nothing is expected; 376instead, the number of characters consumed thus far from the input 377is stored through the next pointer, 378which must be a pointer to 379.Li int . 380This is 381.Em not 382a conversion, although it can be suppressed with the 383.Cm * 384flag. 385.El 386.Pp 387For backwards compatibility, other conversion characters (except 388.Ql \e0 ) 389are taken as if they were 390.Ql %d 391or, if uppercase, 392.Ql %ld , 393and a `conversion' of 394.Ql %\e0 395causes an immediate return of 396.Dv EOF . 397.Sh RETURN VALUES 398These functions return the number of input items assigned, which can be fewer 399than provided for, or even zero, in the event of a matching failure. 400Zero indicates that, while there was input available, no conversions were 401assigned; typically this is due to an invalid input character, 402such as an alphabetic character for a 403.Ql %d 404conversion. 405The value 406.Dv EOF 407is returned if an input failure occurs before any conversion such as an 408end-of-file occurs. 409If an error or end-of-file occurs after conversion has begun, 410the number of conversions which were successfully completed is returned. 411.Sh SEE ALSO 412.Xr getc 3 , 413.Xr printf 3 , 414.Xr strtod 3 , 415.Xr strtol 3 , 416.Xr strtoul 3 417.Sh STANDARDS 418The functions 419.Fn fscanf , 420.Fn scanf , 421and 422.Fn sscanf 423conform to 424.St -ansiC . 425.Sh HISTORY 426The functions 427.Fn vscanf , 428.Fn vsscanf , 429and 430.Fn vfscanf 431first appeared in 432.Bx 4.3 Reno . 433.Sh BUGS 434All of the backwards compatibility formats will be removed in the future. 435.Pp 436Numerical strings are truncated to 512 characters; for example, 437.Cm %f 438and 439.Cm %d 440are implicitly 441.Cm %512f 442and 443.Cm %512d . 444