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