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