| blob | 1237835f8feae5c52be3f616bf2ca4a9e1924c62 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH SCANF 3C "Jul 10, 2008"
48 .SH NAME
49 scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf \- convert formatted input
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <stdio.h>
55 \fBint\fR \fBscanf\fR(\fBconst char *restrict\fR \fIformat\fR...);
56 .fi
58 .LP
59 .nf
60 \fBint\fR \fBfscanf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst char *restrict\fR \fIformat\fR...);
61 .fi
63 .LP
64 .nf
65 \fBint\fR \fBsscanf\fR(\fBconst char *restrict\fR \fIs\fR, \fBconst char *restrict\fR \fIformat\fR...);
66 .fi
68 .LP
69 .nf
70 #include <stdarg.h>
71 #include <stdio.h>
73 \fBint\fR \fBvscanf\fR(\fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIarg\fR);
74 .fi
76 .LP
77 .nf
78 \fBint\fR \fBvfscanf\fR(\fBFILE *\fR\fIstream\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIarg\fR);
79 .fi
81 .LP
82 .nf
83 \fBint\fR \fBvsscanf\fR(\fBconst char *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIarg\fR);
84 .fi
86 .SH DESCRIPTION
87 .sp
88 .LP
89 The \fBscanf()\fR function reads from the standard input stream \fBstdin\fR.
90 .sp
91 .LP
92 The \fBfscanf()\fR function reads from the named input \fIstream\fR.
93 .sp
94 .LP
95 The \fBsscanf()\fR function reads from the string \fIs\fR.
96 .sp
97 .LP
98 The \fBvscanf()\fR, \fBvfscanf()\fR, and \fBvsscanf()\fR functions are
99 equivalent to the \fBscanf()\fR, \fBfscanf()\fR, and \fBsscanf()\fR functions,
100 respectively, except that instead of being called with a variable number of
101 arguments, they are called with an argument list as defined by the
102 <\fBstdarg.h\fR> header . These functions do not invoke the \fBva_end()\fR
103 macro. Applications using these functions should call \fBva_end\fR(\fIap\fR)
104 afterwards to clean up.
105 .sp
106 .LP
107 Each function reads bytes, interprets them according to a format, and stores
108 the results in its arguments. Each expects, as arguments, a control string
109 \fIformat\fR described below, and a set of \fIpointer\fR arguments indicating
110 where the converted input should be stored. The result is undefined if there
111 are insufficient arguments for the format. If the format is exhausted while
112 arguments remain, the excess arguments are evaluated but are otherwise ignored.
113 .sp
114 .LP
115 Conversions can be applied to the \fInth\fR argument after the \fIformat\fR in
116 the argument list, rather than to the next unused argument. In this case, the
117 conversion character \fB%\fR (see below) is replaced by the sequence
118 \fB%\fR\fIn\fR\fB$\fR, where \fIn\fR is a decimal integer in the range [1,
119 \fBNL_ARGMAX\fR]. This feature provides for the definition of format strings
120 that select arguments in an order appropriate to specific languages. In format
121 strings containing the \fB%\fR\fIn\fR\fB$\fR form of conversion specifications,
122 it is unspecified whether numbered arguments in the argument list can be
123 referenced from the format string more than once.
124 .sp
125 .LP
126 The \fIformat\fR can contain either form of a conversion specification, that
127 is, \fB%\fR or \fB%\fR\fIn\fR\fB$\fR, but the two forms cannot normally be
128 mixed within a single \fIformat\fR string. The only exception to this is that
129 \fB%%\fR or \fB%*\fR can be mixed with the \fB%\fR\fIn\fR\fB$\fR form.
130 .sp
131 .LP
132 The \fBscanf()\fR function in all its forms allows for detection of a
133 language-dependent radix character in the input string. The radix character is
134 defined in the program's locale (category \fBLC_NUMERIC\fR). In the POSIX
135 locale, or in a locale where the radix character is not defined, the radix
136 character defaults to a period (.).
137 .sp
138 .LP
139 The format is a character string, beginning and ending in its initial shift
140 state, if any, composed of zero or more directives. Each directive is composed
141 of one of the following:
142 .RS +4
143 .TP
144 .ie t \(bu
145 .el o
146 one or more \fIwhite-space characters\fR (space, tab, newline, vertical-tab or
147 form-feed characters);
148 .RE
149 .RS +4
150 .TP
151 .ie t \(bu
152 .el o
153 an \fIordinary character\fR (neither \fB%\fR nor a white-space character); or
154 .RE
155 .RS +4
156 .TP
157 .ie t \(bu
158 .el o
159 a \fIconversion specification\fR.
160 .RE
161 .SS "Conversion Specifications"
162 .sp
163 .LP
164 Each conversion specification is introduced by the character \fB%\fR or the
165 character sequence \fB%\fR\fIn\fR\fB$\fR, after which the following appear in
166 sequence:
167 .RS +4
168 .TP
169 .ie t \(bu
170 .el o
171 An optional assignment-suppressing character \fB*\fR.
172 .RE
173 .RS +4
174 .TP
175 .ie t \(bu
176 .el o
177 An optional non-zero decimal integer that specifies the maximum field width.
178 .RE
179 .RS +4
180 .TP
181 .ie t \(bu
182 .el o
183 An option length modifier that specifies the size of the receiving object.
184 .RE
185 .RS +4
186 .TP
187 .ie t \(bu
188 .el o
189 A conversion specifier character that specifies the type of conversion to be
190 applied. The valid conversion characters are described below.
191 .RE
192 .sp
193 .LP
194 The \fBscanf()\fR functions execute each directive of the format in turn. If a
195 directive fails, as detailed below, the function returns. Failures are
196 described as input failures (due to the unavailability of input bytes) or
197 matching failures (due to inappropriate input).
198 .sp
199 .LP
200 A directive composed of one or more white-space characters is executed by
201 reading input until no more valid input can be read, or up to the first byte
202 which is not a white-space character which remains unread.
203 .sp
204 .LP
205 A directive that is an ordinary character is executed as follows. The next byte
206 is read from the input and compared with the byte that comprises the directive;
207 if the comparison shows that they are not equivalent, the directive fails, and
208 the differing and subsequent bytes remain unread.
209 .sp
210 .LP
211 A directive that is a conversion specification defines a set of matching input
212 sequences, as described below for each conversion character. A conversion
213 specification is executed in the following steps:
214 .sp
215 .LP
216 Input white-space characters (as specified by \fBisspace\fR(3C)) are skipped,
217 unless the conversion specification includes a \fB[\fR, \fBc\fR, \fBC\fR, or
218 \fBn\fR conversion character.
219 .sp
220 .LP
221 An item is read from the input unless the conversion specification includes an
222 \fBn\fR conversion character. The length of the item read is limited to any
223 specified maximum field width, which is interpreted in either characters or
224 bytes depending on the conversion character. In Solaris default mode, the input
225 item is defined as the longest sequence of input bytes that forms a matching
226 sequence. In some cases, \fBscanf()\fR might need to read several extra
227 characters beyond the end of the input item to find the end of a matching
228 sequence. In C99/SUSv3 mode, the input item is defined as the longest sequence
229 of input bytes that is, or is a prefix of, a matching sequence. With this
230 definition, \fBscanf()\fR need only read at most one character beyond the end
231 of the input item. Therefore, in C99/SUSv3 mode, some sequences that are
232 acceptable to \fBstrtod\fR(3C), \fBstrtol\fR(3C), and similar functions are
233 unacceptable to \fBscanf()\fR. In either mode, \fBscanf()\fR attempts to push
234 back any excess bytes read using \fBungetc\fR(3C). Assuming all such attempts
235 succeed, the first byte, if any, after the input item remains unread. If the
236 length of the input item is 0, the conversion fails. This condition is a
237 matching failure unless end-of-file, an encoding error, or a read error
238 prevented input from the stream, in which case it is an input failure.
239 .sp
240 .LP
241 Except in the case of a \fB%\fR conversion character, the input item (or, in
242 the case of a \fB%\fR\fIn\fR conversion specification, the count of input
243 bytes) is converted to a type appropriate to the conversion character. If the
244 input item is not a matching sequence, the execution of the conversion
245 specification fails; this condition is a matching failure. Unless assignment
246 suppression was indicated by a \fB*\fR, the result of the conversion is placed
247 in the object pointed to by the first argument following the \fIformat\fR
248 argument that has not already received a conversion result if the conversion
249 specification is introduced by \fB%\fR, or in the \fIn\fRth argument if
250 introduced by the character sequence \fB%\fR\fIn\fR\fB$\fR. If this object does
251 not have an appropriate type, or if the result of the conversion cannot be
252 represented in the space provided, the behavior is undefined.
253 .SS "Length Modifiers"
254 .sp
255 .LP
256 The length modifiers and their meanings are:
257 .sp
258 .ne 2
259 .na
260 \fB\fBhh\fR\fR
261 .ad
262 .RS 16n
263 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
264 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
265 pointer to \fBsigned char\fR or \fBunsigned char\fR.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBh\fR\fR
272 .ad
273 .RS 16n
274 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
275 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
276 pointer to \fBshort\fR or \fBunsigned short\fR.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBl\fR (ell)\fR
283 .ad
284 .RS 16n
285 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
286 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
287 pointer to \fBlong\fR or \fBunsigned long\fR; that a following \fBa\fR,
288 \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, or \fBG\fR conversion
289 specifier applies to an argument with type pointer to \fBdouble\fR; or that a
290 following \fBc\fR, \fBs\fR, or \fB[\fR conversion specifier applies to an
291 argument with type pointer to \fBwchar_t\fR.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBll\fR (ell-ell)\fR
298 .ad
299 .RS 16n
300 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
301 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
302 pointer to \fBlong long\fR or \fBunsigned long long\fR.
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fBj\fR\fR
309 .ad
310 .RS 16n
311 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
312 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
313 pointer to \fBintmax_t\fR or \fBuintmax_t\fR.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fBz\fR\fR
320 .ad
321 .RS 16n
322 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
323 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
324 pointer to \fBsize_t\fR or the corresponding signed integer type.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fB\fBt\fR\fR
331 .ad
332 .RS 16n
333 Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR,
334 \fBX\fR, or \fBn\fR conversion specifier applies to an argument with type
335 pointer to \fBptrdiff_t\fR or the corresponding \fBunsigned\fR type.
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fBL\fR\fR
342 .ad
343 .RS 16n
344 Specifies that a following \fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR,
345 \fBF\fR, \fBg\fR, or \fBG\fR conversion specifier applies to an argument with
346 type pointer to \fBlong double\fR.
347 .RE
349 .sp
350 .LP
351 If a length modifier appears with any conversion specifier other than as
352 specified above, the behavior is undefined.
353 .SS "Conversion Characters"
354 .sp
355 .LP
356 The following conversion characters are valid:
357 .sp
358 .ne 2
359 .na
360 \fB\fBd\fR\fR
361 .ad
362 .RS 11n
363 Matches an optionally signed decimal integer, whose format is the same as
364 expected for the subject sequence of \fBstrtol\fR(3C) with the value 10 for the
365 \fIbase\fR argument. In the absence of a size modifier, the corresponding
366 argument must be a pointer to \fBint\fR.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBi\fR\fR
373 .ad
374 .RS 11n
375 Matches an optionally signed integer, whose format is the same as expected for
376 the subject sequence of \fBstrtol()\fR with 0 for the \fIbase\fR argument. In
377 the absence of a size modifier, the corresponding argument must be a pointer to
378 \fBint\fR.
379 .RE
381 .sp
382 .ne 2
383 .na
384 \fB\fBo\fR\fR
385 .ad
386 .RS 11n
387 Matches an optionally signed octal integer, whose format is the same as
388 expected for the subject sequence of \fBstrtoul\fR(3C) with the value 8 for the
389 \fIbase\fR argument. In the absence of a size modifier, the corresponding
390 argument must be a pointer to \fBunsigned int\fR.
391 .RE
393 .sp
394 .ne 2
395 .na
396 \fB\fBu\fR\fR
397 .ad
398 .RS 11n
399 Matches an optionally signed decimal integer, whose format is the same as
400 expected for the subject sequence of \fBstrtoul()\fR with the value 10 for the
401 \fIbase\fR argument. In the absence of a size modifier, the corresponding
402 argument must be a pointer to \fBunsigned int\fR.
403 .RE
405 .sp
406 .ne 2
407 .na
408 \fB\fBx\fR\fR
409 .ad
410 .RS 11n
411 Matches an optionally signed hexadecimal integer, whose format is the same as
412 expected for the subject sequence of \fBstrtoul()\fR with the value 16 for the
413 \fIbase\fR argument. In the absence of a size modifier, the corresponding
414 argument must be a pointer to \fBunsigned int\fR.
415 .RE
417 .sp
418 .ne 2
419 .na
420 \fB\fBa\fR,\fBe\fR,\fBf\fR,\fBg\fR\fR
421 .ad
422 .RS 11n
423 Matches an optionally signed floating-point number, infinity, or NaN, whose
424 format is the same as expected for the subject sequence of \fBstrtod\fR(3C). In
425 the absence of a size modifier, the corresponding argument must be a pointer to
426 \fBfloat\fR. The \fBe\fR, \fBf\fR, and \fBg\fR specifiers match hexadecimal
427 floating point values only in C99/SUSv3 (see \fBstandards\fR(5)) mode, but the
428 \fBa\fR specifier always matches hexadecimal floating point values.
429 .sp
430 These conversion specifiers match any subject sequence accepted by
431 \fBstrtod\fR(3C), including the INF, INFINITY, NAN, and
432 NAN(\fIn-char-sequence\fR) forms. The result of the conversion is the same as
433 that of calling \fBstrtod()\fR (or \fBstrtof()\fR or \fBstrtold()\fR) with the
434 matching sequence, including the raising of floating point exceptions and the
435 setting of \fBerrno\fR to \fBERANGE\fR, if applicable.
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fB\fBs\fR\fR
442 .ad
443 .RS 11n
444 Matches a sequence of bytes that are not white-space characters. The
445 corresponding argument must be a pointer to the initial byte of an array of
446 \fBchar\fR, \fBsigned char\fR, or \fBunsigned char\fR large enough to accept
447 the sequence and a terminating null character code, which will be added
448 automatically.
449 .sp
450 If an \fBl\fR (ell) qualifier is present, the input is a sequence of characters
451 that begins in the initial shift state. Each character is converted to a
452 wide-character as if by a call to the \fBmbrtowc\fR(3C) function, with the
453 conversion state described by an \fBmbstate_t\fR object initialized to zero
454 before the first character is converted. The corresponding argument must be a
455 pointer to an array of \fBwchar_t\fR large enough to accept the sequence and
456 the terminating null wide-character, which will be added automatically.
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fB[\fR\fR
463 .ad
464 .RS 11n
465 Matches a non-empty sequence of characters from a set of expected characters
466 (the \fIscanset\fR). The normal skip over white-space characters is suppressed
467 in this case. The corresponding argument must be a pointer to the initial byte
468 of an array of \fBchar\fR, \fBsigned char\fR, or \fBunsigned char\fR large
469 enough to accept the sequence and a terminating null byte, which will be added
470 automatically.
471 .sp
472 If an \fBl\fR (ell) qualifier is present, the input is a sequence of characters
473 that begins in the initial shift state. Each character in the sequence is
474 converted to a wide-character as if by a call to the \fBmbrtowc()\fR function,
475 with the conversion state described by an \fBmbstate_t\fR object initialized to
476 zero before the first character is converted. The corresponding argument must
477 be a pointer to an array of \fBwchar_t\fR large enough to accept the sequence
478 and the terminating null wide-character, which will be added automatically.
479 .sp
480 The conversion specification includes all subsequent characters in the
481 \fIformat\fR string up to and including the matching right square bracket
482 (\fB]\fR). The characters between the square brackets (the \fIscanlist\fR)
483 comprise the scanset, unless the character after the left square bracket is a
484 circumflex (\fB^\fR), in which case the scanset contains all characters that do
485 not appear in the scanlist between the circumflex and the right square bracket.
486 If the conversion specification begins with \fB[\|]\fR or \fB[^]\fR, the right
487 square bracket is included in the scanlist and the next right square bracket is
488 the matching right square bracket that ends the conversion specification;
489 otherwise the first right square bracket is the one that ends the conversion
490 specification. If a \fB-\fR is in the scanlist and is not the first character,
491 nor the second where the first character is a \fB^\fR, nor the last character,
492 it indicates a range of characters to be matched.
493 .RE
495 .sp
496 .ne 2
497 .na
498 \fB\fBc\fR\fR
499 .ad
500 .RS 11n
501 Matches a sequence of characters of the number specified by the field width (1
502 if no field width is present in the conversion specification). The
503 corresponding argument must be a pointer to the initial byte of an array of
504 \fBchar\fR, \fBsigned char\fR, or \fBunsigned char\fR large enough to accept
505 the sequence. No null byte is added. The normal skip over white-space
506 characters is suppressed in this case.
507 .sp
508 If an \fBl\fR (ell) qualifier is present, the input is a sequence of characters
509 that begins in the initial shift state. Each character in the sequence is
510 converted to a wide-character as if by a call to the \fBmbrtowc()\fR function,
511 with the conversion state described by an \fBmbstate_t\fR object initialized to
512 zero before the first character is converted. The corresponding argument must
513 be a pointer to an array of \fBwchar_t\fR large enough to accept the resulting
514 sequence of wide-characters. No null wide-character is added.
515 .RE
517 .sp
518 .ne 2
519 .na
520 \fB\fBp\fR\fR
521 .ad
522 .RS 11n
523 Matches the set of sequences that is the same as the set of sequences that is
524 produced by the \fB%p\fR conversion of the corresponding \fBprintf\fR(3C)
525 functions. The corresponding argument must be a pointer to a pointer to
526 \fBvoid\fR. If the input item is a value converted earlier during the same
527 program execution, the pointer that results will compare equal to that value;
528 otherwise the behavior of the \fB%p\fR conversion is undefined.
529 .RE
531 .sp
532 .ne 2
533 .na
534 \fB\fBn\fR\fR
535 .ad
536 .RS 11n
537 No input is consumed. The corresponding argument must be a pointer to the
538 integer into which is to be written the number of bytes read from the input so
539 far by this call to the \fBscanf()\fR functions. Execution of a \fB%n\fR
540 conversion specification does not increment the assignment count returned at
541 the completion of execution of the function.
542 .RE
544 .sp
545 .ne 2
546 .na
547 \fB\fBC\fR\fR
548 .ad
549 .RS 11n
550 Same as \fBlc\fR.
551 .RE
553 .sp
554 .ne 2
555 .na
556 \fB\fBS\fR\fR
557 .ad
558 .RS 11n
559 Same as \fBls\fR.
560 .RE
562 .sp
563 .ne 2
564 .na
565 \fB\fB%\fR\fR
566 .ad
567 .RS 11n
568 Matches a single \fB%\fR; no conversion or assignment occurs. The complete
569 conversion specification must be \fB%%\fR.
570 .RE
572 .sp
573 .LP
574 If a conversion specification is invalid, the behavior is undefined.
575 .sp
576 .LP
577 The conversion characters \fBA\fR, \fBE\fR, \fBF\fR, \fBG\fR, and \fBX\fR are
578 also valid and behave the same as, respectively, \fBa\fR, \fBe\fR, \fBf\fR,
579 \fBg\fR, and \fBx\fR.
580 .sp
581 .LP
582 If end-of-file is encountered during input, conversion is terminated. If
583 end-of-file occurs before any bytes matching the current conversion
584 specification (except for \fB%n\fR) have been read (other than leading
585 white-space characters, where permitted), execution of the current conversion
586 specification terminates with an input failure. Otherwise, unless execution of
587 the current conversion specification is terminated with a matching failure,
588 execution of the following conversion specification (if any) is terminated with
589 an input failure.
590 .sp
591 .LP
592 Reaching the end of the string in \fBsscanf()\fR is equivalent to encountering
593 end-of-file for \fBfscanf()\fR.
594 .sp
595 .LP
596 If conversion terminates on a conflicting input, the offending input is left
597 unread in the input. Any trailing white space (including newline characters) is
598 left unread unless matched by a conversion specification. The success of
599 literal matches and suppressed assignments is only directly determinable via
600 the \fB%n\fR conversion specification.
601 .sp
602 .LP
603 The \fBfscanf()\fR and \fBscanf()\fR functions may mark the \fBst_atime\fR
604 field of the file associated with \fIstream\fR for update. The \fBst_atime\fR
605 field will be marked for update by the first successful execution of
606 \fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfread\fR(3C), \fBfscanf(\|),\fR
607 \fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), or \fBscanf()\fR using
608 \fIstream\fR that returns data not supplied by a prior call to
609 \fBungetc\fR(3C).
610 .SH RETURN VALUES
611 .sp
612 .LP
613 Upon successful completion, these functions return the number of successfully
614 matched and assigned input items; this number can be 0 in the event of an early
615 matching failure. If the input ends before the first matching failure or
616 conversion, \fBEOF\fR is returned. If a read error occurs the error indicator
617 for the stream is set, \fBEOF\fR is returned, and \fBerrno\fR is set to
618 indicate the error.
619 .SH ERRORS
620 .sp
621 .LP
622 For the conditions under which the \fBscanf()\fR functions will fail and may
623 fail, refer to \fBfgetc\fR(3C) or \fBfgetwc\fR(3C).
624 .sp
625 .LP
626 In addition, \fBfscanf()\fR may fail if:
627 .sp
628 .ne 2
629 .na
630 \fB\fBEILSEQ\fR\fR
631 .ad
632 .RS 10n
633 Input byte sequence does not form a valid character.
634 .RE
636 .sp
637 .ne 2
638 .na
639 \fB\fBEINVAL\fR\fR
640 .ad
641 .RS 10n
642 There are insufficient arguments.
643 .RE
645 .SH USAGE
646 .sp
647 .LP
648 If the application calling the \fBscanf()\fR functions has any objects of type
649 \fBwint_t\fR or \fBwchar_t,\fR it must also include the header \fB<wchar.h>\fR
650 to have these objects defined.
651 .SH EXAMPLES
652 .LP
653 \fBExample 1 \fRThe call:
654 .sp
655 .in +2
656 .nf
657 int i, n; float x; char name[50];
658 n = scanf("%d%f%s", &i, &x, name)
659 .fi
660 .in -2
662 .sp
663 .LP
664 with the input line:
666 .sp
667 .in +2
668 .nf
669 25 54.32E-1 Hamster
670 .fi
671 .in -2
673 .sp
674 .LP
675 will assign to \fIn\fR the value 3, to \fIi\fR the value 25, to \fIx\fR the
676 value 5.432, and \fIname\fR will contain the string Hamster.
678 .LP
679 \fBExample 2 \fRThe call:
680 .sp
681 .in +2
682 .nf
683 int i; float x; char name[50];
684 (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);
685 .fi
686 .in -2
688 .sp
689 .LP
690 with input:
692 .sp
693 .in +2
694 .nf
695 56789 0123 56a72
696 .fi
697 .in -2
699 .sp
700 .LP
701 will assign 56 to \fIi\fR, 789.0 to \fIx\fR, skip 0123, and place the string
702 56\e0 in \fIname\fR. The next call to \fBgetchar\fR(3C) will return the
703 character \fBa\fR.
705 .SH ATTRIBUTES
706 .sp
707 .LP
708 See \fBattributes\fR(5) for descriptions of the following attributes:
709 .sp
711 .sp
712 .TS
713 box;
714 l | l
715 l | l .
716 ATTRIBUTE TYPE ATTRIBUTE VALUE
717 _
718 CSI Enabled
719 _
720 Interface Stability Committed
721 _
722 MT-Level MT-Safe
723 _
724 Standard See \fBstandards\fR(5).
725 .TE
727 .SH SEE ALSO
728 .sp
729 .LP
730 \fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfread\fR(3C),
731 \fBisspace\fR(3C), \fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBstrtod\fR(3C),
732 \fBstrtol\fR(3C), \fBstrtoul\fR(3C), \fBwcrtomb\fR(3C), \fBungetc\fR(3C),
733 \fBattributes\fR(5), \fBstandards\fR(5)
734 .SH NOTES
735 .sp
736 .LP
737 The behavior of the conversion specifier "%%" has changed for all of the
738 functions described on this manual page. Previously the "%%" specifier accepted
739 a "%" character from input only if there were no preceding whitespace
740 characters. The new behavior accepts "%" even if there are preceding
741 whitespace characters. This new behavior now aligns with the description on
742 this manual page and in various standards. If the old behavior is desired, the
743 conversion specification "%*[%]" can be used.