1.\" $OpenBSD: scanf.3,v 1.12 2003/09/26 16:24:56 deraadt 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 January 31, 1995 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 105.Dq suppression 106below). 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 indent 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 h 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 short int 137(rather than 138.Li int ) . 139.It Cm l 140Indicates either 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 long int 146(rather than 147.Li int ) , 148or that the conversion will be one of 149.Cm efg 150and the next pointer is a pointer to 151.Li double 152(rather than 153.Li float ) . 154.It Cm q 155Indicates that the conversion will be one of 156.Cm dioux 157or 158.Cm n 159and the next pointer is a pointer to a 160.Li quad_t 161(rather than 162.Li int ) . 163.It Cm L 164Indicates that the conversion will be 165.Cm efg 166and the next pointer is a pointer to 167.Li long double . 168.El 169.Pp 170In addition to these flags, there may be an optional maximum field width, 171expressed as a decimal integer, between the 172.Cm % 173and the conversion. 174If no width is given, 175a default of 176.Dq infinity 177is used (with one exception, below); 178otherwise at most this many characters are scanned in processing the 179conversion. 180Before conversion begins, most conversions skip whitespace; 181this whitespace is not counted against the field width. 182.Pp 183The following conversions are available: 184.Bl -tag -width XXXX 185.It Cm % 186Matches a literal `%'. 187That is, 188.Ql %\&% 189in the format string matches a single input 190.Ql % 191character. 192No conversion is done, and assignment does not occur. 193.It Cm d 194Matches an optionally signed decimal integer; 195the next pointer must be a pointer to 196.Li int . 197.It Cm D 198Equivalent to 199.Cm ld ; 200this exists only for backwards compatibility. 201.It Cm i 202Matches an optionally signed integer; 203the next pointer must be a pointer to 204.Li int . 205The integer is read in base 16 if it begins 206with 207.Ql 0x 208or 209.Ql 0X , 210in base 8 if it begins with 211.Ql 0 , 212and in base 10 otherwise. 213Only characters that correspond to the base are used. 214.It Cm o 215Matches an octal integer; 216the next pointer must be a pointer to 217.Li unsigned int . 218.It Cm O 219Equivalent to 220.Cm lo ; 221this exists for backwards compatibility. 222.It Cm u 223Matches an optionally signed decimal integer; 224the next pointer must be a pointer to 225.Li unsigned int . 226.It Cm x 227Matches an optionally signed hexadecimal integer; 228the next pointer must be a pointer to 229.Li unsigned int . 230.It Cm X 231Equivalent to 232.Cm x . 233.It Cm f 234Matches an optionally signed floating-point number; 235the next pointer must be a pointer to 236.Li float . 237.It Cm e 238Equivalent to 239.Cm f . 240.It Cm g 241Equivalent to 242.Cm f . 243.It Cm E 244Equivalent to 245.Cm f . 246.It Cm G 247Equivalent to 248.Cm f . 249.It Cm s 250Matches a sequence of non-whitespace characters; 251the next pointer must be a pointer to 252.Li char , 253and the provided array must be large enough to accept and store 254all the sequence and the terminating 255.Tn NUL 256character. 257The input string stops at whitespace 258or at the maximum field width, whichever occurs first. 259If specified, the maximum field length refers to the sequence 260being scanned rather than the storage space, hence the provided 261array must be 1 larger for the terminating 262.Tn NUL 263character. 264.It Cm c 265Matches a sequence of 266.Li width 267count characters (default 1); 268the next pointer must be a pointer to 269.Li char , 270and there must be enough room for all the characters 271(no terminating 272.Tn NUL 273is added). 274The usual skip of leading whitespace is suppressed. 275To skip whitespace first, use an explicit space in the format. 276.It Cm \&[ 277Matches a nonempty sequence of characters from the specified set 278of accepted characters; 279the next pointer must be a pointer to 280.Li char , 281and there must be enough room for all the characters in the string, 282plus a terminating 283.Tn NUL 284character. 285The usual skip of leading whitespace is suppressed. 286The string is to be made up of characters in 287(or not in) 288a particular set; 289the set is defined by the characters between the open bracket 290.Cm [ 291character 292and a close bracket 293.Cm ] 294character. 295The set excludes those characters 296if the first character after the open bracket is a circumflex 297.Cm ^ . 298To include a close bracket in the set, 299make it the first character after the open bracket 300or the circumflex; 301any other position will end the set. 302The hyphen character 303.Cm - 304is also special; 305when placed between two other characters, 306it adds all intervening characters to the set. 307To include a hyphen, 308make it the last character before the final close bracket. 309For instance, 310.Ql [^]0-9-] 311means the set `everything except close bracket, zero through nine, 312and hyphen'. 313The string ends with the appearance of a character not in the 314(or, with a circumflex, in) set 315or when the field width runs out. 316.It Cm p 317Matches a pointer value (as printed by 318.Ql %p 319in 320.Xr printf 3 ) ; 321the next pointer must be a pointer to 322.Li void . 323.It Cm n 324Nothing is expected; 325instead, the number of characters consumed thus far from the input 326is stored through the next pointer, 327which must be a pointer to 328.Li int . 329This is 330.Em not 331a conversion, although it can be suppressed with the 332.Cm * 333flag. 334.El 335.Pp 336For backwards compatibility, other conversion characters (except 337.Ql \e0 ) 338are taken as if they were 339.Ql %d 340or, if uppercase, 341.Ql %ld , 342and a `conversion' of 343.Ql %\e0 344causes an immediate return of 345.Dv EOF . 346.Sh RETURN VALUES 347These functions return the number of input items assigned, which can be fewer 348than provided for, or even zero, in the event of a matching failure. 349Zero indicates that, while there was input available, no conversions were 350assigned; typically this is due to an invalid input character, 351such as an alphabetic character for a 352.Ql %d 353conversion. 354The value 355.Dv EOF 356is returned if an input failure occurs before any conversion such as an 357end-of-file occurs. 358If an error or end-of-file occurs after conversion has begun, 359the number of conversions which were successfully completed is returned. 360.Sh SEE ALSO 361.Xr getc 3 , 362.Xr printf 3 , 363.Xr strtod 3 , 364.Xr strtol 3 , 365.Xr strtoul 3 366.Sh STANDARDS 367The functions 368.Fn fscanf , 369.Fn scanf , 370and 371.Fn sscanf 372conform to 373.St -ansiC . 374.Sh HISTORY 375The functions 376.Fn vscanf , 377.Fn vsscanf , 378and 379.Fn vfscanf 380first appeared in 381.Bx 4.3 Reno . 382.Sh BUGS 383All of the backwards compatibility formats will be removed in the future. 384.Pp 385Numerical strings are truncated to 512 characters; for example, 386.Cm %f 387and 388.Cm %d 389are implicitly 390.Cm %512f 391and 392.Cm %512d . 393