]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
2 | .\" 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 6.14 (Berkeley) 1/8/93 | |
37 | .\" | |
38 | .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu | |
c13182ef | 39 | .\" modified to resemble the GNU libio setup used in the Linux libc |
fea681da MK |
40 | .\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de |
41 | .\" Modified, aeb, 970121 | |
c13182ef MK |
42 | .\" 2005-07-14, mtk, added description of %n$ form; various text |
43 | .\" incorporated from the GNU C library documentation ((C) The | |
991910a4 | 44 | .\" Free Software Foundation); other parts substantially rewritten. |
fea681da | 45 | .\" |
7deb3c8b MK |
46 | .\" FIXME |
47 | .\" The glibc 2.7 release announcement says: | |
48 | .\" Implement 'm' modifier for scanf. Add stricter C99/SUS compliance | |
49 | .\" by not recognizing 'a' as a modifier when those specs are requested. | |
50 | .\" These changes need to be documented. | |
51 | .\" | |
cc4615cc | 52 | .TH SCANF 3 2007-07-26 "GNU" "Linux Programmer's Manual" |
fea681da MK |
53 | .SH NAME |
54 | scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion | |
55 | .SH SYNOPSIS | |
56 | .nf | |
57 | .B #include <stdio.h> | |
a45ebabf MK |
58 | |
59 | .BI "int scanf(const char *" format ", ...);" | |
60 | .BI "int fscanf(FILE *" stream ", const char *" format ", ...);" | |
61 | .BI "int sscanf(const char *" str ", const char *" format ", ...);" | |
fea681da MK |
62 | .sp |
63 | .B #include <stdarg.h> | |
a45ebabf | 64 | |
fea681da | 65 | .BI "int vscanf(const char *" format ", va_list " ap ); |
fea681da | 66 | .BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap ); |
fea681da | 67 | .BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap ); |
cc4615cc MK |
68 | .fi |
69 | .sp | |
70 | .in -4n | |
71 | Feature Test Macro Requirements for glibc (see | |
72 | .BR feature_test_macros (7)): | |
73 | .in | |
74 | .sp | |
75 | .BR vscanf (), | |
76 | .BR vsscanf (), | |
77 | .BR vfscanf (): | |
cc4615cc MK |
78 | _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE; or |
79 | .I "cc -std=c99" | |
fea681da MK |
80 | .SH DESCRIPTION |
81 | The | |
e511ffb6 | 82 | .BR scanf () |
991910a4 | 83 | family of functions scans input according to |
fea681da | 84 | .I format |
c13182ef MK |
85 | as described below. |
86 | This format may contain | |
991910a4 MK |
87 | .IR "conversion specifications" ; |
88 | the results from such conversions, if any, | |
89 | are stored in the locations pointed to by the | |
c13182ef | 90 | .I pointer |
991910a4 MK |
91 | arguments that follow |
92 | .IR format . | |
c13182ef | 93 | Each |
fea681da | 94 | .I pointer |
c13182ef | 95 | argument must be of a type that is appropriate for the value returned |
991910a4 MK |
96 | by the corresponding conversion specification. |
97 | ||
98 | If the number of conversion specifications in | |
99 | .I format | |
100 | exceeds the number of | |
101 | .I pointer | |
102 | arguments, the results are undefined. | |
103 | If the number of | |
104 | .I pointer | |
105 | arguments exceeds the number of conversion specifications, then the excess | |
106 | .I pointer | |
107 | arguments are evaluated, but are otherwise ignored. | |
108 | ||
109 | The | |
e511ffb6 | 110 | .BR scanf () |
fea681da MK |
111 | function reads input from the standard input stream |
112 | .IR stdin , | |
e511ffb6 | 113 | .BR fscanf () |
fea681da MK |
114 | reads input from the stream pointer |
115 | .IR stream , | |
116 | and | |
e511ffb6 | 117 | .BR sscanf () |
fea681da MK |
118 | reads its input from the character string pointed to by |
119 | .IR str . | |
120 | .PP | |
121 | The | |
e511ffb6 | 122 | .BR vfscanf () |
fea681da MK |
123 | function is analogous to |
124 | .BR vfprintf (3) | |
125 | and reads input from the stream pointer | |
126 | .I stream | |
127 | using a variable argument list of pointers (see | |
128 | .BR stdarg (3). | |
129 | The | |
e511ffb6 | 130 | .BR vscanf () |
fea681da | 131 | function scans a variable argument list from the standard input and the |
e511ffb6 | 132 | .BR vsscanf () |
fea681da | 133 | function scans it from a string; these are analogous to the |
fb186734 | 134 | .BR vprintf (3) |
fea681da | 135 | and |
fb186734 | 136 | .BR vsprintf (3) |
fea681da MK |
137 | functions respectively. |
138 | .PP | |
991910a4 MK |
139 | The |
140 | .I format | |
c13182ef | 141 | string consists of a sequence of |
0daa9e92 | 142 | .I directives |
991910a4 MK |
143 | which describe how to process the sequence of input characters. |
144 | If processing of a directive fails, no further input is read, and | |
e511ffb6 | 145 | .BR scanf () |
991910a4 MK |
146 | returns. |
147 | A "failure" can be either of the following: | |
148 | .IR "input failure" , | |
149 | meaning that input characters were unavailable, or | |
150 | .IR "matching failure" , | |
151 | meaning that the input was inappropriate (see below). | |
152 | ||
153 | A directive is one of the following: | |
154 | .TP | |
155 | \(bu | |
0967c11f | 156 | A sequence of white-space characters (space, tab, newline, etc.; see |
991910a4 MK |
157 | .BR isspace (3)). |
158 | This directive matches any amount of white space, | |
159 | including none, in the input. | |
160 | .TP | |
161 | \(bu | |
333a424b | 162 | An ordinary character (i.e., one other than white space or \(aq%\(aq). |
991910a4 MK |
163 | This character must exactly match the next character of input. |
164 | .TP | |
165 | \(bu | |
333a424b MK |
166 | A conversion specification, |
167 | which commences with a \(aq%\(aq (percent) character. | |
c13182ef | 168 | A sequence of characters from the input is converted according to |
991910a4 | 169 | this specification, and the result is placed in the corresponding |
fea681da | 170 | .I pointer |
991910a4 | 171 | argument. |
8666f209 | 172 | If the next item of input does not match the conversion specification, |
991910a4 MK |
173 | the conversion fails \(em this is a |
174 | .IR "matching failure" . | |
175 | .PP | |
176 | Each | |
c13182ef | 177 | .I conversion specification |
991910a4 | 178 | in |
c13182ef | 179 | .I format |
333a424b | 180 | begins with either the character \(aq%\(aq or the character sequence |
991910a4 | 181 | "\fB%\fP\fIn\fP\fB$\fP" |
faa42a0a | 182 | (see below for the distinction) followed by: |
991910a4 MK |
183 | .TP |
184 | \(bu | |
333a424b | 185 | An optional \(aq*\(aq assignment-suppression character: |
e511ffb6 | 186 | .BR scanf () |
991910a4 MK |
187 | reads input as directed by the conversion specification, |
188 | but discards the input. | |
189 | No corresponding | |
190 | .I pointer | |
191 | argument is required, and this specification is not | |
192 | included in the count of successful assignments returned by | |
e511ffb6 | 193 | .BR scanf (). |
991910a4 MK |
194 | .TP |
195 | \(bu | |
333a424b | 196 | An optional \(aqa\(aq character. |
c13182ef | 197 | This is used with string conversions, and relieves the caller of the |
991910a4 | 198 | need to allocate a corresponding buffer to hold the input: instead, |
e511ffb6 | 199 | .BR scanf () |
c13182ef | 200 | allocates a buffer of sufficient size, |
991910a4 MK |
201 | and assigns the address of this buffer to the corresponding |
202 | .I pointer | |
203 | argument, which should be a pointer to a | |
204 | .I "char *" | |
d9bfdb9c | 205 | variable (this variable does not need to be initialized before the call). |
991910a4 MK |
206 | The caller should subsequently |
207 | .BR free (3) | |
208 | this buffer when it is no longer required. | |
209 | This is a GNU extension; | |
333a424b | 210 | C99 employs the \(aqa\(aq character as a conversion specifier (and |
991910a4 MK |
211 | it can also be used as such in the GNU implementation). |
212 | .TP | |
213 | \(bu | |
214 | An optional decimal integer which specifies the | |
215 | .IR "maximum field width" . | |
c13182ef MK |
216 | Reading of characters stops either when this maximum is reached or |
217 | when a non-matching character is found, whichever happens first. | |
218 | Most conversions discard initial whitespace characters (the exceptions | |
219 | are noted below), | |
991910a4 | 220 | and these discarded characters don't count towards the maximum field width. |
333a424b | 221 | String input conversions store a null terminator (\(aq\\0\(aq) |
c13182ef | 222 | to mark the end of the input; |
991910a4 MK |
223 | the maximum field width does not include this terminator. |
224 | .TP | |
225 | \(bu | |
c13182ef MK |
226 | An optional |
227 | .IR "type modifier character" . | |
991910a4 MK |
228 | For example, the |
229 | .B l | |
c13182ef | 230 | type modifier is used with integer conversions such as |
5adafd6d | 231 | .B %d |
991910a4 MK |
232 | to specify that the corresponding |
233 | .I pointer | |
c13182ef | 234 | argument refers to a |
991910a4 | 235 | .I "long int" |
c13182ef | 236 | rather than a pointer to an |
991910a4 MK |
237 | .IR int . |
238 | .TP | |
239 | \(bu | |
c13182ef | 240 | A |
991910a4 MK |
241 | .I "conversion specifier" |
242 | that specifies the type of input conversion to be performed. | |
c13182ef | 243 | .PP |
991910a4 | 244 | The conversion specifications in |
fea681da | 245 | .I format |
333a424b | 246 | are of two forms, either beginning with \(aq%\(aq or beginning with |
991910a4 | 247 | "\fB%\fP\fIn\fP\fB$\fP". |
c13182ef | 248 | The two forms should not be mixed in the same |
fea681da | 249 | .I format |
c13182ef | 250 | string, except that a string containing |
991910a4 MK |
251 | "\fB%\fP\fIn\fP\fB$\fP" |
252 | specifications can include | |
5adafd6d | 253 | .B %% |
c13182ef | 254 | and |
5adafd6d | 255 | .BR %* . |
991910a4 MK |
256 | If |
257 | .I format | |
333a424b | 258 | contains \(aq%\(aq |
991910a4 MK |
259 | specifications then these correspond in order with successive |
260 | .I pointer | |
261 | arguments. | |
262 | In the | |
263 | "\fB%\fP\fIn\fP\fB$\fP" | |
68e1685c | 264 | form (which is specified in POSIX.1-2001, but not C99), |
991910a4 | 265 | .I n |
c13182ef | 266 | is a decimal integer that specifies that the converted input should |
991910a4 MK |
267 | be placed in the location referred to by the |
268 | .IR n -th | |
269 | .I pointer | |
270 | argument following | |
271 | .IR format . | |
8af1ba10 | 272 | .SS Conversions |
991910a4 | 273 | The following |
0daa9e92 | 274 | .I "type modifier characters" |
991910a4 | 275 | can appear in a conversion specification: |
fea681da MK |
276 | .TP |
277 | .B h | |
278 | Indicates that the conversion will be one of | |
991910a4 | 279 | .B diouxX |
fea681da MK |
280 | or |
281 | .B n | |
282 | and the next pointer is a pointer to a | |
991910a4 MK |
283 | .I short int |
284 | or | |
285 | .I unsigned short int | |
fea681da MK |
286 | (rather than |
287 | .IR int ). | |
288 | .TP | |
991910a4 MK |
289 | .B hh |
290 | As for | |
291 | .BR h , | |
292 | but the next pointer is a pointer to a | |
293 | .I signed char | |
294 | or | |
295 | .IR "unsigned char" . | |
296 | .TP | |
297 | .B j | |
298 | As for | |
299 | .BR h , | |
3c5e62b6 | 300 | but the next pointer is a pointer to an |
991910a4 | 301 | .I intmax_t |
3c5e62b6 | 302 | or a |
991910a4 MK |
303 | .IR uintmax_t . |
304 | This modifier was introduced in C99. | |
305 | .TP | |
fea681da MK |
306 | .B l |
307 | Indicates either that the conversion will be one of | |
991910a4 | 308 | .B diouxX |
fea681da MK |
309 | or |
310 | .B n | |
311 | and the next pointer is a pointer to a | |
991910a4 MK |
312 | .I long int |
313 | or | |
314 | .I unsigned long int | |
fea681da MK |
315 | (rather than |
316 | .IR int ), | |
317 | or that the conversion will be one of | |
318 | .B efg | |
319 | and the next pointer is a pointer to | |
320 | .I double | |
321 | (rather than | |
322 | .IR float ). | |
c13182ef | 323 | Specifying two |
fea681da | 324 | .B l |
991910a4 MK |
325 | characters is equivalent to |
326 | .BR L . | |
327 | If used with | |
5adafd6d | 328 | .B %c |
c13182ef | 329 | or |
5adafd6d | 330 | .B %s |
c13182ef | 331 | the corresponding parameter is considered |
d0f17b57 | 332 | as a pointer to a wide character or wide-character string respectively. |
991910a4 | 333 | .\" This use of l was introduced in Amendment 1 to ISO C90. |
fea681da MK |
334 | .TP |
335 | .B L | |
336 | Indicates that the conversion will be either | |
337 | .B efg | |
338 | and the next pointer is a pointer to | |
0daa9e92 | 339 | .I "long double" |
c13182ef | 340 | or the conversion will be |
fea681da MK |
341 | .B dioux |
342 | and the next pointer is a pointer to | |
343 | .IR "long long" . | |
c13182ef | 344 | .\" MTK, Jul 05: The following is no longer true for modern |
991910a4 | 345 | .\" ANSI C (i.e., C99): |
c13182ef MK |
346 | .\" (Note that long long is not an |
347 | .\" ANSI C | |
991910a4 MK |
348 | .\" type. Any program using this will not be portable to all |
349 | .\" architectures). | |
fea681da MK |
350 | .TP |
351 | .B q | |
c13182ef MK |
352 | equivalent to |
353 | .BR L . | |
991910a4 MK |
354 | This specifier does not exist in ANSI C. |
355 | .TP | |
356 | .B t | |
357 | As for | |
358 | .BR h , | |
359 | but the next pointer is a pointer to a | |
360 | .IR ptrdiff_t . | |
361 | This modifier was introduced in C99. | |
362 | .TP | |
363 | .B z | |
364 | As for | |
365 | .BR h , | |
366 | but the next pointer is a pointer to a | |
367 | .IR size_t . | |
368 | This modifier was introduced in C99. | |
fea681da | 369 | .PP |
c13182ef | 370 | The following |
991910a4 MK |
371 | .I "conversion specifiers" |
372 | are available: | |
fea681da MK |
373 | .TP |
374 | .B % | |
333a424b | 375 | Matches a literal \(aq%\(aq. |
c13182ef | 376 | That is, |
5adafd6d | 377 | .B %\&% |
991910a4 | 378 | in the format string matches a |
333a424b | 379 | single input \(aq%\(aq character. |
c13182ef | 380 | No conversion is done, and assignment does not |
fea681da MK |
381 | occur. |
382 | .TP | |
383 | .B d | |
384 | Matches an optionally signed decimal integer; | |
385 | the next pointer must be a pointer to | |
386 | .IR int . | |
387 | .TP | |
388 | .B D | |
389 | Equivalent to | |
991910a4 | 390 | .IR ld ; |
fea681da | 391 | this exists only for backwards compatibility. |
c13182ef MK |
392 | (Note: thus only in libc4. |
393 | In libc5 and glibc the | |
5adafd6d | 394 | .B %D |
991910a4 | 395 | is silently ignored, causing old programs to fail mysteriously.) |
fea681da MK |
396 | .TP |
397 | .B i | |
398 | Matches an optionally signed integer; the next pointer must be a pointer to | |
399 | .IR int . | |
c13182ef | 400 | The integer is read in base 16 if it begins with |
991910a4 | 401 | .I 0x |
c13182ef MK |
402 | or |
403 | .IR 0X , | |
404 | in base 8 if it begins with | |
405 | .IR 0 , | |
991910a4 MK |
406 | and in base 10 otherwise. |
407 | Only characters that correspond to the base are used. | |
fea681da MK |
408 | .TP |
409 | .B o | |
410 | Matches an unsigned octal integer; the next pointer must be a pointer to | |
411 | .IR "unsigned int" . | |
412 | .TP | |
413 | .B u | |
414 | Matches an unsigned decimal integer; the next pointer must be a | |
415 | pointer to | |
416 | .IR "unsigned int" . | |
417 | .TP | |
418 | .B x | |
419 | Matches an unsigned hexadecimal integer; the next pointer must | |
420 | be a pointer to | |
421 | .IR "unsigned int" . | |
422 | .TP | |
423 | .B X | |
424 | Equivalent to | |
425 | .BR x . | |
426 | .TP | |
427 | .B f | |
428 | Matches an optionally signed floating-point number; the next pointer must | |
429 | be a pointer to | |
430 | .IR float . | |
431 | .TP | |
432 | .B e | |
433 | Equivalent to | |
434 | .BR f . | |
435 | .TP | |
436 | .B g | |
437 | Equivalent to | |
438 | .BR f . | |
439 | .TP | |
440 | .B E | |
441 | Equivalent to | |
442 | .BR f . | |
443 | .TP | |
991910a4 MK |
444 | .B a |
445 | (C99) Equivalent to | |
446 | .BR f . | |
447 | .TP | |
fea681da | 448 | .B s |
991910a4 | 449 | Matches a sequence of non-white-space characters; |
c13182ef MK |
450 | the next pointer must be a pointer to character array that is |
451 | long enough to hold the input sequence and the terminating null | |
333a424b | 452 | character (\(aq\\0\(aq), which is added automatically. |
991910a4 | 453 | The input string stops at white space or at the maximum field |
fea681da MK |
454 | width, whichever occurs first. |
455 | .TP | |
456 | .B c | |
991910a4 MK |
457 | Matches a sequence of characters whose length is specified by the |
458 | .I maximum field width | |
459 | (default 1); the next pointer must be a pointer to | |
fea681da MK |
460 | .IR char , |
461 | and there must be enough room for all the characters (no terminating | |
28d88c17 | 462 | null byte |
c13182ef MK |
463 | is added). |
464 | The usual skip of leading white space is suppressed. | |
465 | To skip white space first, use an explicit space in the format. | |
fea681da MK |
466 | .TP |
467 | .B \&[ | |
1f04cc97 | 468 | Matches a non-empty sequence of characters from the specified set of |
fea681da MK |
469 | accepted characters; the next pointer must be a pointer to |
470 | .IR char , | |
471 | and there must be enough room for all the characters in the string, plus a | |
28d88c17 | 472 | terminating null byte. |
c13182ef MK |
473 | The usual skip of leading white space is suppressed. |
474 | The string is to be made up of characters in (or not in) a particular set; | |
475 | the set is defined by the characters between the open bracket | |
fea681da MK |
476 | .B [ |
477 | character and a close bracket | |
478 | .B ] | |
c13182ef MK |
479 | character. |
480 | The set | |
fea681da MK |
481 | .I excludes |
482 | those characters if the first character after the open bracket is a | |
483 | circumflex | |
43daf87d | 484 | .RB ( ^ ). |
fea681da MK |
485 | To include a close bracket in the set, make it the first character after |
486 | the open bracket or the circumflex; any other position will end the set. | |
487 | The hyphen character | |
8c383102 | 488 | .B \- |
fea681da | 489 | is also special; when placed between two other characters, it adds all |
c13182ef MK |
490 | intervening characters to the set. |
491 | To include a hyphen, make it the last | |
492 | character before the final close bracket. | |
493 | For instance, | |
34131745 | 494 | .B [^]0\-9\-] |
991910a4 MK |
495 | means |
496 | the set "everything except close bracket, zero through nine, and hyphen". | |
fea681da MK |
497 | The string ends with the appearance of a character not in the (or, with a |
498 | circumflex, in) set or when the field width runs out. | |
499 | .TP | |
500 | .B p | |
c13182ef | 501 | Matches a pointer value (as printed by |
5adafd6d | 502 | .B %p |
991910a4 | 503 | in |
fea681da | 504 | .BR printf (3); |
475f1bca | 505 | the next pointer must be a pointer to a pointer to |
fea681da MK |
506 | .IR void . |
507 | .TP | |
508 | .B n | |
509 | Nothing is expected; instead, the number of characters consumed thus far | |
510 | from the input is stored through the next pointer, which must be a pointer | |
511 | to | |
512 | .IR int . | |
513 | This is | |
514 | .I not | |
515 | a conversion, although it can be suppressed with the | |
516 | .B * | |
991910a4 | 517 | assignment-suppression character. |
c13182ef | 518 | The C standard says: "Execution of a |
5adafd6d | 519 | .B %n |
991910a4 MK |
520 | directive does not increment |
521 | the assignment count returned at the completion of execution" | |
c13182ef MK |
522 | but the Corrigendum seems to contradict this. |
523 | Probably it is wise | |
991910a4 | 524 | not to make any assumptions on the effect of |
5adafd6d | 525 | .B %n |
991910a4 | 526 | conversions on the return value. |
fea681da | 527 | .SH "RETURN VALUE" |
c13182ef MK |
528 | These functions return the number of input items |
529 | successfully matched and assigned, | |
530 | which can be fewer than provided for, | |
991910a4 | 531 | or even zero in the event of an early matching failure. |
4d9b6984 MK |
532 | |
533 | The value | |
534 | .B EOF | |
c13182ef | 535 | is returned if the end of input is reached before either the first |
6e888f06 | 536 | successful conversion or a matching failure occurs. |
fea681da | 537 | .B EOF |
c13182ef | 538 | is also returned if a read error occurs, |
4d9b6984 MK |
539 | in which case the error indicator for the stream (see |
540 | .BR ferror (3)) | |
541 | is set, and | |
542 | .I errno | |
543 | is set indicate the error. | |
fea681da MK |
544 | .SH "CONFORMING TO" |
545 | The functions | |
e511ffb6 MK |
546 | .BR fscanf (), |
547 | .BR scanf (), | |
fea681da | 548 | and |
e511ffb6 | 549 | .BR sscanf () |
68e1685c | 550 | conform to C89 and C99. |
fea681da | 551 | .PP |
c13182ef | 552 | The |
fea681da | 553 | .B q |
c13182ef | 554 | specifier is the 4.4BSD notation for |
fea681da MK |
555 | .IR "long long" , |
556 | while | |
557 | .B ll | |
558 | or the usage of | |
559 | .B L | |
560 | in integer conversions is the GNU notation. | |
561 | .PP | |
c13182ef MK |
562 | The Linux version of these functions is based on the |
563 | .I GNU | |
fea681da | 564 | .I libio |
c13182ef MK |
565 | library. |
566 | Take a look at the | |
fea681da | 567 | .I info |
c13182ef | 568 | documentation of |
fea681da MK |
569 | .I GNU |
570 | .I libc (glibc-1.08) | |
c13182ef | 571 | for a more concise description. |
fea681da | 572 | .SH BUGS |
c13182ef MK |
573 | All functions are fully C89 conformant, but provide the |
574 | additional specifiers | |
fea681da MK |
575 | .B q |
576 | and | |
577 | .B a | |
d9bfdb9c | 578 | as well as an additional behavior of the |
fea681da | 579 | .B L |
c13182ef MK |
580 | and |
581 | .B l | |
582 | specifiers. | |
583 | The latter may be considered to be a bug, as it changes the | |
d9bfdb9c | 584 | behavior of specifiers defined in C89. |
fea681da | 585 | .PP |
c13182ef MK |
586 | Some combinations of the type modifiers and conversion |
587 | specifiers defined by ANSI C do not make sense | |
588 | (e.g. | |
fea681da | 589 | .BR "%Ld" ). |
d9bfdb9c | 590 | While they may have a well-defined behavior on Linux, this need not |
c13182ef MK |
591 | to be so on other architectures. |
592 | Therefore it usually is better to use | |
75b94dc3 | 593 | modifiers that are not defined by ANSI C at all, that is, use |
fea681da | 594 | .B q |
c13182ef | 595 | instead of |
fea681da | 596 | .B L |
c13182ef | 597 | in combination with |
fea681da | 598 | .B diouxX |
c13182ef | 599 | conversions or |
fea681da MK |
600 | .BR ll . |
601 | .PP | |
602 | The usage of | |
603 | .B q | |
43daf87d | 604 | is not the same as on 4.4BSD, |
c13182ef | 605 | as it may be used in float conversions equivalently to |
fea681da | 606 | .BR L . |
e37e3282 MK |
607 | .SH "SEE ALSO" |
608 | .BR getc (3), | |
609 | .BR printf (3), | |
610 | .BR setlocale (3), | |
611 | .BR strtod (3), | |
612 | .BR strtol (3), | |
613 | .BR strtoul (3) |