1.\" $NetBSD: scanf.3,v 1.27 2010/05/14 03:04:32 joerg 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.\" @(#)scanf.3 8.2 (Berkeley) 12/11/93 35.\" 36.Dd March 21, 2010 37.Dt SCANF 3 38.Os 39.Sh NAME 40.Nm scanf , 41.Nm fscanf , 42.Nm sscanf , 43.Nm vscanf , 44.Nm vsscanf , 45.Nm vfscanf 46.Nd input format conversion 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In stdio.h 51.Ft int 52.Fn scanf "const char * restrict format" ... 53.Ft int 54.Fn fscanf "FILE * restrict stream" "const char * restrict format" ... 55.Ft int 56.Fn sscanf "const char * restrict str" "const char * restrict format" ... 57.In stdarg.h 58.Ft int 59.Fn vscanf "const char * restrict format" "va_list ap" 60.Ft int 61.Fn vsscanf "const char * restrict str" "const char * restrict format" "va_list ap" 62.Ft int 63.Fn vfscanf "FILE * restrict stream" "const char * restrict format" "va_list ap" 64.Sh DESCRIPTION 65The 66.Fn scanf 67family of functions scans input according to a 68.Fa format 69as described below. 70This format may contain 71.Em conversion specifiers ; 72the results from such conversions, if any, 73are stored through the 74.Em pointer 75arguments. 76.Pp 77The 78.Fn scanf 79function 80reads input from the standard input stream 81.Em stdin , 82.Fn fscanf 83reads input from the stream pointer 84.Fa stream , 85and 86.Fn sscanf 87reads its input from the character string pointed to by 88.Fa str . 89The 90.Fn vfscanf 91function 92is analogous to 93.Xr vfprintf 3 94and reads input from the stream pointer 95.Fa stream 96using a variable argument list of pointers (see 97.Xr stdarg 3 ) . 98The 99.Fn vscanf 100function scans a variable argument list from the standard input and 101the 102.Fn vsscanf 103function scans it from a string; 104these are analogous to 105the 106.Fn vprintf 107and 108.Fn vsprintf 109functions respectively. 110.Pp 111Each successive 112.Em pointer 113argument must correspond properly with 114each successive conversion specifier 115(but see `suppression' below). 116All conversions are introduced by the 117.Cm % 118(percent sign) character. 119The 120.Fa format 121string 122may also contain other characters. 123White space (such as blanks, tabs, or newlines) in the 124.Fa format 125string match any amount of white space, including none, in the input. 126Everything else 127matches only itself. 128Scanning stops 129when an input character does not match such a format character. 130Scanning also stops 131when an input conversion cannot be made (see below). 132.Sh CONVERSIONS 133Following the 134.Cm % 135character introducing a conversion 136there may be a number of 137.Em flag 138characters, as follows: 139.Bl -tag -width indent 140.It Cm * 141Suppresses assignment. 142The conversion that follows occurs as usual, but no pointer is used; 143the result of the conversion is simply discarded. 144.It Cm h 145Indicates that the conversion will be one of 146.Cm dioux 147or 148.Cm n 149and the next pointer is a pointer to a 150.Em short int 151(rather than 152.Em int ) . 153.It Cm hh 154Indicates that the conversion will be one of 155.Cm dioux 156or 157.Cm n 158and the next pointer is a pointer to a 159.Em char 160(rather than 161.Em int ) . 162.It Cm j 163Indicates that the conversion will be one of 164.Cm dioux 165or 166.Cm n 167and the next pointer is a pointer to an 168.Em intmax_t 169(rather than 170.Em int ) . 171.It Cm l 172Indicates either that the conversion will be one of 173.Cm dioux 174or 175.Cm n 176and the next pointer is a pointer to a 177.Em long int 178(rather than 179.Em int ) , 180or that the conversion will be one of 181.Cm efg 182and the next pointer is a pointer to 183.Em double 184(rather than 185.Em float ) . 186.It Cm ll 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.Em long long int 193(rather than 194.Em int ) . 195.It Cm q 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.Em quad_t 202(rather than 203.Em int ) . 204.It Cm t 205Indicates that the conversion will be one of 206.Cm dioux 207or 208.Cm n 209and the next pointer is a pointer to a 210.Em ptrdiff_t 211(rather than 212.Em int ) . 213.It Cm z 214Indicates that the conversion will be one of 215.Cm dioux 216or 217.Cm n 218and the next pointer is a pointer to a 219.Em size_t 220(rather than 221.Em int ) . 222.It Cm L 223Indicates that the conversion will be 224.Cm efg 225and the next pointer is a pointer to 226.Em long double . 227.El 228.Pp 229In addition to these flags, 230there may be an optional maximum field width, 231expressed as a decimal integer, 232between the 233.Cm % 234and the conversion. 235If no width is given, 236a default of `infinity' is used (with one exception, below); 237otherwise at most this many characters are scanned 238in processing the conversion. 239Before conversion begins, 240most conversions skip white space; 241this white space is not counted against the field width. 242.Pp 243The following conversions are available: 244.Bl -tag -width XXXX 245.It Cm % 246Matches a literal `%'. 247That is, `%\&%' in the format string 248matches a single input `%' character. 249No conversion is done, and assignment does not occur. 250.It Cm d 251Matches an optionally signed decimal integer; 252the next pointer must be a pointer to 253.Em int . 254.It Cm D 255Equivalent to 256.Cm ld ; 257this exists only for backwards compatibility. 258.It Cm i 259Matches an optionally signed integer; 260the next pointer must be a pointer to 261.Em int . 262The integer is read in base 16 if it begins 263with 264.Ql 0x 265or 266.Ql 0X , 267in base 8 if it begins with 268.Ql 0 , 269and in base 10 otherwise. 270Only characters that correspond to the base are used. 271.It Cm o 272Matches an octal integer; 273the next pointer must be a pointer to 274.Em unsigned int . 275.It Cm O 276Equivalent to 277.Cm lo ; 278this exists for backwards compatibility. 279.It Cm u 280Matches an optionally signed decimal integer; 281the next pointer must be a pointer to 282.Em unsigned int . 283.It Cm x 284Matches an optionally signed hexadecimal integer; 285the next pointer must be a pointer to 286.Em unsigned int . 287.It Cm X 288Equivalent to 289.Cm x . 290.It Cm f 291Matches an optionally signed floating-point number; 292the next pointer must be a pointer to 293.Em float . 294.It Cm e 295Equivalent to 296.Cm f . 297.It Cm g 298Equivalent to 299.Cm f . 300.It Cm E 301Equivalent to 302.Cm f . 303.It Cm G 304Equivalent to 305.Cm f . 306.It Cm s 307Matches a sequence of non-white-space characters; 308the next pointer must be a pointer to 309.Em char , 310and the array must be large enough to accept all the sequence and the 311terminating 312.Dv NUL 313character. 314The input string stops at white space 315or at the maximum field width, whichever occurs first. 316.It Cm c 317Matches a sequence of 318.Em width 319count 320characters (default 1); 321the next pointer must be a pointer to 322.Em char , 323and there must be enough room for all the characters 324(no terminating 325.Dv NUL 326is added). 327The usual skip of leading white space is suppressed. 328To skip white space first, use an explicit space in the format. 329.It Cm \&[ 330Matches a nonempty sequence of characters from the specified set 331of accepted characters; 332the next pointer must be a pointer to 333.Em char , 334and there must be enough room for all the characters in the string, 335plus a terminating 336.Dv NUL 337character. 338The usual skip of leading white space is suppressed. 339The string is to be made up of characters in 340(or not in) 341a particular set; 342the set is defined by the characters between the open bracket 343.Cm \&[ 344character 345and a close bracket 346.Cm \&] 347character. 348The set 349.Em excludes 350those characters 351if the first character after the open bracket is a circumflex 352.Cm ^ . 353To include a close bracket in the set, 354make it the first character after the open bracket 355or the circumflex; 356any other position will end the set. 357The hyphen character 358.Cm - 359is also special; 360when placed between two other characters, 361it adds all intervening characters to the set. 362To include a hyphen, 363make it the last character before the final close bracket. 364For instance, 365.Ql [^]0-9-] 366means the set `everything except close bracket, zero through nine, 367and hyphen'. 368The string ends with the appearance of a character not in the 369(or, with a circumflex, in) set 370or when the field width runs out. 371.It Cm p 372Matches a pointer value (as printed by 373.Ql %p 374in 375.Xr printf 3 ) ; 376the next pointer must be a pointer to 377.Em void . 378.It Cm n 379Nothing is expected; 380instead, the number of characters consumed thus far from the input 381is stored through the next pointer, 382which must be a pointer to 383.Em int . 384This is 385.Em not 386a conversion, although it can be suppressed with the 387.Cm * 388flag. 389.El 390.Pp 391For backwards compatibility, 392other conversion characters (except 393.Ql \e0 ) 394are taken as if they were 395.Ql %d 396or, if uppercase, 397.Ql %ld , 398and a `conversion' of 399.Ql %\e0 400causes an immediate return of 401.Dv EOF . 402.Pp 403The format string specifier macros described in 404.Xr inttypes 3 405should be used for the standard 406.Dq C99 407fixed-size integers documented in 408.Xr stdint 3 . 409.Sh RETURN VALUES 410These 411functions 412return 413the number of input items assigned, which can be fewer than provided 414for, or even zero, in the event of a matching failure. 415Zero 416indicates that, while there was input available, 417no conversions were assigned; 418typically this is due to an invalid input character, 419such as an alphabetic character for a 420.Ql %d 421conversion. 422The value 423.Dv EOF 424is returned if an input failure occurs before any conversion such as an 425end-of-file occurs. 426If an error or end-of-file occurs after conversion has begun, 427the number of conversions which were successfully completed is returned. 428.Sh SEE ALSO 429.Xr getc 3 , 430.Xr inttypes 3 , 431.Xr printf 3 , 432.Xr strtod 3 , 433.Xr strtol 3 , 434.Xr strtoul 3 435.Sh STANDARDS 436The functions 437.Fn fscanf , 438.Fn scanf , 439and 440.Fn sscanf 441conform to 442.St -isoC-90 . 443The 444.Cm %j , 445.Cm %t 446and 447.Cm %z 448conversion format modifiers 449conform to 450.St -isoC-99 . 451The 452.Fn vfscanf , 453.Fn vscanf 454and 455.Fn vsscanf 456functions conform to 457.St -isoC-99 . 458.Sh HISTORY 459The functions 460.Fn vscanf , 461.Fn vsscanf 462and 463.Fn vfscanf 464appeared in 465.Bx 4.4 466or even 467.Bx 4.3 . 468.Sh NOTES 469All of the backwards compatibility formats will be removed in the future. 470.Sh BUGS 471Numerical strings are truncated to 512 characters; for example, 472.Cm %f 473and 474.Cm %d 475are implicitly 476.Cm %512f 477and 478.Cm %512d . 479