1.\" $OpenBSD: scanf.3,v 1.18 2011/07/03 17:57:47 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: July 3 2011 $ 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 eE 280Equivalent to 281.Cm f . 282.It Cm fF 283Matches an optionally signed floating-point number; 284the next pointer must be a pointer to 285.Li float . 286.It Cm gG 287Equivalent to 288.Cm f . 289.It Cm aA 290Equivalent to 291.Cm f . 292.It Cm s 293Matches a sequence of non-whitespace characters; 294the next pointer must be a pointer to 295.Li char , 296and the provided array must be large enough to accept and store 297all the sequence and the terminating 298.Tn NUL 299character. 300The input string stops at whitespace 301or at the maximum field width, whichever occurs first. 302If specified, the maximum field length refers to the sequence 303being scanned rather than the storage space, hence the provided 304array must be 1 larger for the terminating 305.Tn NUL 306character. 307.It Cm c 308Matches a sequence of characters consuming the number of bytes 309specified by the field width (defaults to 1 if unspecified); 310the next pointer must be a pointer to 311.Li char , 312and there must be enough room for all the characters 313(no terminating 314.Tn NUL 315is added). 316The usual skip of leading whitespace is suppressed. 317To skip whitespace first, use an explicit space in the format. 318.It Cm \&[ 319Matches a nonempty sequence of characters from the specified set 320of accepted characters; 321the next pointer must be a pointer to 322.Li char , 323and there must be enough room for all the characters in the string, 324plus a terminating 325.Tn NUL 326character. 327The usual skip of leading whitespace is suppressed. 328.Pp 329The string is to be made up of characters in 330(or not in) 331a particular set; 332the set is defined by the characters between the open bracket 333.Cm \&[ 334character 335and a close bracket 336.Cm \&] 337character. 338The set 339.Em excludes 340those characters 341if the first character after the open bracket is a circumflex 342.Cm ^ . 343To include a close bracket in the set, 344make it the first character after the open bracket 345or the circumflex; 346any other position will end the set. 347The hyphen character 348.Cm - 349is also special; 350when placed between two other characters, 351it adds all intervening characters to the set. 352To include a hyphen, 353make it the last character before the final close bracket. 354.Pp 355For instance, 356.Ql [^]0-9-] 357means the set 358.Do 359everything except close bracket, zero through nine, and hyphen 360.Dc . 361The string ends with the appearance of a character not in 362(or, with a circumflex, in) the set 363or when the field width runs out. 364.It Cm p 365Matches a pointer value (as printed by 366.Ql %p 367in 368.Xr printf 3 ) ; 369the next pointer must be a pointer to 370.Li void . 371.It Cm n 372Nothing is expected; 373instead, the number of characters consumed thus far from the input 374is stored through the next pointer, 375which must be a pointer to 376.Li int . 377This is 378.Em not 379a conversion, although it can be suppressed with the 380.Cm * 381flag. 382.El 383.Pp 384For backwards compatibility, other conversion characters (except 385.Ql \e0 ) 386are taken as if they were 387.Ql %d 388or, if uppercase, 389.Ql %ld , 390and a `conversion' of 391.Ql %\e0 392causes an immediate return of 393.Dv EOF . 394.Sh RETURN VALUES 395These functions return the number of input items assigned, which can be fewer 396than provided for, or even zero, in the event of a matching failure. 397Zero indicates that, while there was input available, no conversions were 398assigned; typically this is due to an invalid input character, 399such as an alphabetic character for a 400.Ql %d 401conversion. 402The value 403.Dv EOF 404is returned if an input failure occurs before any conversion such as an 405end-of-file occurs. 406If an error or end-of-file occurs after conversion has begun, 407the number of conversions which were successfully completed is returned. 408.Sh SEE ALSO 409.Xr getc 3 , 410.Xr printf 3 , 411.Xr strtod 3 , 412.Xr strtol 3 , 413.Xr strtoul 3 414.Sh STANDARDS 415The functions 416.Fn fscanf , 417.Fn scanf , 418and 419.Fn sscanf 420conform to 421.St -ansiC . 422.Sh HISTORY 423The functions 424.Fn vscanf , 425.Fn vsscanf , 426and 427.Fn vfscanf 428first appeared in 429.Bx 4.3 Reno . 430.Sh BUGS 431All of the backwards compatibility formats will be removed in the future. 432.Pp 433Numerical strings are truncated to 512 characters; for example, 434.Cm %f 435and 436.Cm %d 437are implicitly 438.Cm %512f 439and 440.Cm %512d . 441