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