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