]>
Commit | Line | Data |
---|---|---|
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 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) | |
9 | .\" Redistribution and use in source and binary forms, with or without | |
10 | .\" modification, are permitted provided that the following conditions | |
11 | .\" are met: | |
12 | .\" 1. Redistributions of source code must retain the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer. | |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
15 | .\" notice, this list of conditions and the following disclaimer in the | |
16 | .\" documentation and/or other materials provided with the distribution. | |
17 | .\" 3. All advertising materials mentioning features or use of this software | |
18 | .\" must display the following acknowledgement: | |
19 | .\" This product includes software developed by the University of | |
20 | .\" California, Berkeley and its contributors. | |
21 | .\" 4. Neither the name of the University nor the names of its contributors | |
22 | .\" may be used to endorse or promote products derived from this software | |
23 | .\" without specific prior written permission. | |
24 | .\" | |
25 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
26 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
27 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
28 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
29 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
30 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
31 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
32 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
33 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
34 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
35 | .\" SUCH DAMAGE. | |
36 | .\" %%%LICENSE_END | |
37 | .\" | |
38 | .\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 | |
39 | .\" | |
40 | .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu | |
41 | .\" modified to resemble the GNU libio setup used in the Linux libc | |
42 | .\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de | |
43 | .\" Modified, aeb, 970121 | |
44 | .\" 2005-07-14, mtk, added description of %n$ form; various text | |
45 | .\" incorporated from the GNU C library documentation ((C) The | |
46 | .\" Free Software Foundation); other parts substantially rewritten. | |
47 | .\" | |
48 | .\" 2008-06-23, mtk | |
49 | .\" Add ERRORS section. | |
50 | .\" Document the 'a' and 'm' modifiers for dynamic string allocation. | |
51 | .\" | |
52 | .TH SCANF 3 2017-09-15 "GNU" "Linux Programmer's Manual" | |
53 | .SH NAME | |
54 | scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion | |
55 | .SH SYNOPSIS | |
56 | .nf | |
57 | .B #include <stdio.h> | |
58 | .PP | |
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 ", ...);" | |
62 | ||
63 | .B #include <stdarg.h> | |
64 | .PP | |
65 | .BI "int vscanf(const char *" format ", va_list " ap ); | |
66 | .BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap ); | |
67 | .BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap ); | |
68 | .fi | |
69 | .PP | |
70 | .in -4n | |
71 | Feature Test Macro Requirements for glibc (see | |
72 | .BR feature_test_macros (7)): | |
73 | .in | |
74 | .ad l | |
75 | .PP | |
76 | .BR vscanf (), | |
77 | .BR vsscanf (), | |
78 | .BR vfscanf (): | |
79 | .RS 4 | |
80 | _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L | |
81 | .ad | |
82 | .RE | |
83 | .SH DESCRIPTION | |
84 | The | |
85 | .BR scanf () | |
86 | family of functions scans input according to | |
87 | .I format | |
88 | as described below. | |
89 | This format may contain | |
90 | .IR "conversion specifications" ; | |
91 | the results from such conversions, if any, | |
92 | are stored in the locations pointed to by the | |
93 | .I pointer | |
94 | arguments that follow | |
95 | .IR format . | |
96 | Each | |
97 | .I pointer | |
98 | argument must be of a type that is appropriate for the value returned | |
99 | by the corresponding conversion specification. | |
100 | .PP | |
101 | If the number of conversion specifications in | |
102 | .I format | |
103 | exceeds the number of | |
104 | .I pointer | |
105 | arguments, the results are undefined. | |
106 | If the number of | |
107 | .I pointer | |
108 | arguments exceeds the number of conversion specifications, then the excess | |
109 | .I pointer | |
110 | arguments are evaluated, but are otherwise ignored. | |
111 | .PP | |
112 | The | |
113 | .BR scanf () | |
114 | function reads input from the standard input stream | |
115 | .IR stdin , | |
116 | .BR fscanf () | |
117 | reads input from the stream pointer | |
118 | .IR stream , | |
119 | and | |
120 | .BR sscanf () | |
121 | reads its input from the character string pointed to by | |
122 | .IR str . | |
123 | .PP | |
124 | The | |
125 | .BR vfscanf () | |
126 | function is analogous to | |
127 | .BR vfprintf (3) | |
128 | and reads input from the stream pointer | |
129 | .I stream | |
130 | using a variable argument list of pointers (see | |
131 | .BR stdarg (3). | |
132 | The | |
133 | .BR vscanf () | |
134 | function scans a variable argument list from the standard input and the | |
135 | .BR vsscanf () | |
136 | function scans it from a string; these are analogous to the | |
137 | .BR vprintf (3) | |
138 | and | |
139 | .BR vsprintf (3) | |
140 | functions respectively. | |
141 | .PP | |
142 | The | |
143 | .I format | |
144 | string consists of a sequence of | |
145 | .I directives | |
146 | which describe how to process the sequence of input characters. | |
147 | If processing of a directive fails, no further input is read, and | |
148 | .BR scanf () | |
149 | returns. | |
150 | A "failure" can be either of the following: | |
151 | .IR "input failure" , | |
152 | meaning that input characters were unavailable, or | |
153 | .IR "matching failure" , | |
154 | meaning that the input was inappropriate (see below). | |
155 | .PP | |
156 | A directive is one of the following: | |
157 | .TP | |
158 | \(bu | |
159 | A sequence of white-space characters (space, tab, newline, etc.; see | |
160 | .BR isspace (3)). | |
161 | This directive matches any amount of white space, | |
162 | including none, in the input. | |
163 | .TP | |
164 | \(bu | |
165 | An ordinary character (i.e., one other than white space or \(aq%\(aq). | |
166 | This character must exactly match the next character of input. | |
167 | .TP | |
168 | \(bu | |
169 | A conversion specification, | |
170 | which commences with a \(aq%\(aq (percent) character. | |
171 | A sequence of characters from the input is converted according to | |
172 | this specification, and the result is placed in the corresponding | |
173 | .I pointer | |
174 | argument. | |
175 | If the next item of input does not match the conversion specification, | |
176 | the conversion fails\(emthis is a | |
177 | .IR "matching failure" . | |
178 | .PP | |
179 | Each | |
180 | .I conversion specification | |
181 | in | |
182 | .I format | |
183 | begins with either the character \(aq%\(aq or the character sequence | |
184 | "\fB%\fP\fIn\fP\fB$\fP" | |
185 | (see below for the distinction) followed by: | |
186 | .TP | |
187 | \(bu | |
188 | An optional \(aq*\(aq assignment-suppression character: | |
189 | .BR scanf () | |
190 | reads input as directed by the conversion specification, | |
191 | but discards the input. | |
192 | No corresponding | |
193 | .I pointer | |
194 | argument is required, and this specification is not | |
195 | included in the count of successful assignments returned by | |
196 | .BR scanf (). | |
197 | .TP | |
198 | \(bu | |
199 | For decimal conversions, an optional quote character (\(aq). | |
200 | This specifies that the input number may include thousands' | |
201 | separators as defined by the | |
202 | .BR LC_NUMERIC | |
203 | category of the current locale. | |
204 | (See | |
205 | .BR setlocale (3).) | |
206 | The quote character may precede or follow the \(aq*\(aq | |
207 | assignment-suppression character. | |
208 | .TP | |
209 | \(bu | |
210 | An optional \(aqm\(aq character. | |
211 | This is used with string conversions | |
212 | .RI ( %s , | |
213 | .IR %c , | |
214 | .IR %[ ), | |
215 | and relieves the caller of the | |
216 | need to allocate a corresponding buffer to hold the input: instead, | |
217 | .BR scanf () | |
218 | allocates a buffer of sufficient size, | |
219 | and assigns the address of this buffer to the corresponding | |
220 | .I pointer | |
221 | argument, which should be a pointer to a | |
222 | .I "char\ *" | |
223 | variable (this variable does not need to be initialized before the call). | |
224 | The caller should subsequently | |
225 | .BR free (3) | |
226 | this buffer when it is no longer required. | |
227 | .TP | |
228 | \(bu | |
229 | An optional decimal integer which specifies the | |
230 | .IR "maximum field width" . | |
231 | Reading of characters stops either when this maximum is reached or | |
232 | when a nonmatching character is found, whichever happens first. | |
233 | Most conversions discard initial white space characters (the exceptions | |
234 | are noted below), | |
235 | and these discarded characters don't count toward the maximum field width. | |
236 | String input conversions store a terminating null byte (\(aq\\0\(aq) | |
237 | to mark the end of the input; | |
238 | the maximum field width does not include this terminator. | |
239 | .TP | |
240 | \(bu | |
241 | An optional | |
242 | .IR "type modifier character" . | |
243 | For example, the | |
244 | .B l | |
245 | type modifier is used with integer conversions such as | |
246 | .B %d | |
247 | to specify that the corresponding | |
248 | .I pointer | |
249 | argument refers to a | |
250 | .I "long int" | |
251 | rather than a pointer to an | |
252 | .IR int . | |
253 | .TP | |
254 | \(bu | |
255 | A | |
256 | .I "conversion specifier" | |
257 | that specifies the type of input conversion to be performed. | |
258 | .PP | |
259 | The conversion specifications in | |
260 | .I format | |
261 | are of two forms, either beginning with \(aq%\(aq or beginning with | |
262 | "\fB%\fP\fIn\fP\fB$\fP". | |
263 | The two forms should not be mixed in the same | |
264 | .I format | |
265 | string, except that a string containing | |
266 | "\fB%\fP\fIn\fP\fB$\fP" | |
267 | specifications can include | |
268 | .B %% | |
269 | and | |
270 | .BR %* . | |
271 | If | |
272 | .I format | |
273 | contains \(aq%\(aq | |
274 | specifications, then these correspond in order with successive | |
275 | .I pointer | |
276 | arguments. | |
277 | In the | |
278 | "\fB%\fP\fIn\fP\fB$\fP" | |
279 | form (which is specified in POSIX.1-2001, but not C99), | |
280 | .I n | |
281 | is a decimal integer that specifies that the converted input should | |
282 | be placed in the location referred to by the | |
283 | .IR n -th | |
284 | .I pointer | |
285 | argument following | |
286 | .IR format . | |
287 | .SS Conversions | |
288 | The following | |
289 | .I "type modifier characters" | |
290 | can appear in a conversion specification: | |
291 | .TP | |
292 | .B h | |
293 | Indicates that the conversion will be one of | |
294 | \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP | |
295 | and the next pointer is a pointer to a | |
296 | .I short int | |
297 | or | |
298 | .I unsigned short int | |
299 | (rather than | |
300 | .IR int ). | |
301 | .TP | |
302 | .B hh | |
303 | As for | |
304 | .BR h , | |
305 | but the next pointer is a pointer to a | |
306 | .I signed char | |
307 | or | |
308 | .IR "unsigned char" . | |
309 | .TP | |
310 | .B j | |
311 | As for | |
312 | .BR h , | |
313 | but the next pointer is a pointer to an | |
314 | .I intmax_t | |
315 | or a | |
316 | .IR uintmax_t . | |
317 | This modifier was introduced in C99. | |
318 | .TP | |
319 | .B l | |
320 | Indicates either that the conversion will be one of | |
321 | \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP | |
322 | and the next pointer is a pointer to a | |
323 | .I long int | |
324 | or | |
325 | .I unsigned long int | |
326 | (rather than | |
327 | .IR int ), | |
328 | or that the conversion will be one of | |
329 | \fBe\fP, \fBf\fP, or \fBg\fP | |
330 | and the next pointer is a pointer to | |
331 | .I double | |
332 | (rather than | |
333 | .IR float ). | |
334 | Specifying two | |
335 | .B l | |
336 | characters is equivalent to | |
337 | .BR L . | |
338 | If used with | |
339 | .B %c | |
340 | or | |
341 | .BR %s , | |
342 | the corresponding parameter is considered | |
343 | as a pointer to a wide character or wide-character string respectively. | |
344 | .\" This use of l was introduced in Amendment 1 to ISO C90. | |
345 | .TP | |
346 | .B L | |
347 | Indicates that the conversion will be either | |
348 | \fBe\fP, \fBf\fP, or \fBg\fP | |
349 | and the next pointer is a pointer to | |
350 | .I "long double" | |
351 | or the conversion will be | |
352 | \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, or \fBx\fP | |
353 | and the next pointer is a pointer to | |
354 | .IR "long long" . | |
355 | .\" MTK, Jul 05: The following is no longer true for modern | |
356 | .\" ANSI C (i.e., C99): | |
357 | .\" (Note that long long is not an | |
358 | .\" ANSI C | |
359 | .\" type. Any program using this will not be portable to all | |
360 | .\" architectures). | |
361 | .TP | |
362 | .B q | |
363 | equivalent to | |
364 | .BR L . | |
365 | This specifier does not exist in ANSI C. | |
366 | .TP | |
367 | .B t | |
368 | As for | |
369 | .BR h , | |
370 | but the next pointer is a pointer to a | |
371 | .IR ptrdiff_t . | |
372 | This modifier was introduced in C99. | |
373 | .TP | |
374 | .B z | |
375 | As for | |
376 | .BR h , | |
377 | but the next pointer is a pointer to a | |
378 | .IR size_t . | |
379 | This modifier was introduced in C99. | |
380 | .PP | |
381 | The following | |
382 | .I "conversion specifiers" | |
383 | are available: | |
384 | .TP | |
385 | .B % | |
386 | Matches a literal \(aq%\(aq. | |
387 | That is, | |
388 | .B %\&% | |
389 | in the format string matches a | |
390 | single input \(aq%\(aq character. | |
391 | No conversion is done (but initial white space characters are discarded), | |
392 | and assignment does not occur. | |
393 | .TP | |
394 | .B d | |
395 | Matches an optionally signed decimal integer; | |
396 | the next pointer must be a pointer to | |
397 | .IR int . | |
398 | .TP | |
399 | .B D | |
400 | Equivalent to | |
401 | .IR ld ; | |
402 | this exists only for backward compatibility. | |
403 | (Note: thus only in libc4. | |
404 | In libc5 and glibc the | |
405 | .B %D | |
406 | is silently ignored, causing old programs to fail mysteriously.) | |
407 | .TP | |
408 | .B i | |
409 | Matches an optionally signed integer; the next pointer must be a pointer to | |
410 | .IR int . | |
411 | The integer is read in base 16 if it begins with | |
412 | .I 0x | |
413 | or | |
414 | .IR 0X , | |
415 | in base 8 if it begins with | |
416 | .IR 0 , | |
417 | and in base 10 otherwise. | |
418 | Only characters that correspond to the base are used. | |
419 | .TP | |
420 | .B o | |
421 | Matches an unsigned octal integer; the next pointer must be a pointer to | |
422 | .IR "unsigned int" . | |
423 | .TP | |
424 | .B u | |
425 | Matches an unsigned decimal integer; the next pointer must be a | |
426 | pointer to | |
427 | .IR "unsigned int" . | |
428 | .TP | |
429 | .B x | |
430 | Matches an unsigned hexadecimal integer; the next pointer must | |
431 | be a pointer to | |
432 | .IR "unsigned int" . | |
433 | .TP | |
434 | .B X | |
435 | Equivalent to | |
436 | .BR x . | |
437 | .TP | |
438 | .B f | |
439 | Matches an optionally signed floating-point number; the next pointer must | |
440 | be a pointer to | |
441 | .IR float . | |
442 | .TP | |
443 | .B e | |
444 | Equivalent to | |
445 | .BR f . | |
446 | .TP | |
447 | .B g | |
448 | Equivalent to | |
449 | .BR f . | |
450 | .TP | |
451 | .B E | |
452 | Equivalent to | |
453 | .BR f . | |
454 | .TP | |
455 | .B a | |
456 | (C99) Equivalent to | |
457 | .BR f . | |
458 | .TP | |
459 | .B s | |
460 | Matches a sequence of non-white-space characters; | |
461 | the next pointer must be a pointer to the initial element of a | |
462 | character array that is long enough to hold the input sequence and | |
463 | the terminating null byte (\(aq\\0\(aq), which is added automatically. | |
464 | The input string stops at white space or at the maximum field | |
465 | width, whichever occurs first. | |
466 | .TP | |
467 | .B c | |
468 | Matches a sequence of characters whose length is specified by the | |
469 | .I maximum field width | |
470 | (default 1); the next pointer must be a pointer to | |
471 | .IR char , | |
472 | and there must be enough room for all the characters | |
473 | (no terminating null byte is added). | |
474 | The usual skip of leading white space is suppressed. | |
475 | To skip white space first, use an explicit space in the format. | |
476 | .TP | |
477 | .B \&[ | |
478 | Matches a nonempty sequence of characters from the specified set of | |
479 | accepted characters; the next pointer must be a pointer to | |
480 | .IR char , | |
481 | and there must be enough room for all the characters in the string, plus a | |
482 | terminating null byte. | |
483 | The usual skip of leading white space is suppressed. | |
484 | The string is to be made up of characters in (or not in) a particular set; | |
485 | the set is defined by the characters between the open bracket | |
486 | .B [ | |
487 | character and a close bracket | |
488 | .B ] | |
489 | character. | |
490 | The set | |
491 | .I excludes | |
492 | those characters if the first character after the open bracket is a | |
493 | circumflex | |
494 | .RB ( ^ ). | |
495 | To include a close bracket in the set, make it the first character after | |
496 | the open bracket or the circumflex; any other position will end the set. | |
497 | The hyphen character | |
498 | .B \- | |
499 | is also special; when placed between two other characters, it adds all | |
500 | intervening characters to the set. | |
501 | To include a hyphen, make it the last | |
502 | character before the final close bracket. | |
503 | For instance, | |
504 | .B [^]0\-9\-] | |
505 | means | |
506 | the set "everything except close bracket, zero through nine, and hyphen". | |
507 | The string ends with the appearance of a character not in the (or, with a | |
508 | circumflex, in) set or when the field width runs out. | |
509 | .TP | |
510 | .B p | |
511 | Matches a pointer value (as printed by | |
512 | .B %p | |
513 | in | |
514 | .BR printf (3); | |
515 | the next pointer must be a pointer to a pointer to | |
516 | .IR void . | |
517 | .TP | |
518 | .B n | |
519 | Nothing is expected; instead, the number of characters consumed thus far | |
520 | from the input is stored through the next pointer, which must be a pointer | |
521 | to | |
522 | .IR int . | |
523 | This is | |
524 | .I not | |
525 | a conversion and does | |
526 | .I not | |
527 | increase the count returned by the function. | |
528 | The assignment can be suppressed with the | |
529 | .B * | |
530 | assignment-suppression character, but the effect on the | |
531 | return value is undefined. | |
532 | Therefore | |
533 | .B %*n | |
534 | conversions should not be used. | |
535 | .SH RETURN VALUE | |
536 | On success, these functions return the number of input items | |
537 | successfully matched and assigned; | |
538 | this can be fewer than provided for, | |
539 | or even zero, in the event of an early matching failure. | |
540 | .PP | |
541 | The value | |
542 | .B EOF | |
543 | is returned if the end of input is reached before either the first | |
544 | successful conversion or a matching failure occurs. | |
545 | .B EOF | |
546 | is also returned if a read error occurs, | |
547 | in which case the error indicator for the stream (see | |
548 | .BR ferror (3)) | |
549 | is set, and | |
550 | .I errno | |
551 | is set to indicate the error. | |
552 | .SH ERRORS | |
553 | .TP | |
554 | .B EAGAIN | |
555 | The file descriptor underlying | |
556 | .I stream | |
557 | is marked nonblocking, and the read operation would block. | |
558 | .TP | |
559 | .B EBADF | |
560 | The file descriptor underlying | |
561 | .I stream | |
562 | is invalid, or not open for reading. | |
563 | .TP | |
564 | .B EILSEQ | |
565 | Input byte sequence does not form a valid character. | |
566 | .TP | |
567 | .B EINTR | |
568 | The read operation was interrupted by a signal; see | |
569 | .BR signal (7). | |
570 | .TP | |
571 | .B EINVAL | |
572 | Not enough arguments; or | |
573 | .I format | |
574 | is NULL. | |
575 | .TP | |
576 | .B ENOMEM | |
577 | Out of memory. | |
578 | .TP | |
579 | .B ERANGE | |
580 | The result of an integer conversion would exceed the size | |
581 | that can be stored in the corresponding integer type. | |
582 | .SH ATTRIBUTES | |
583 | For an explanation of the terms used in this section, see | |
584 | .BR attributes (7). | |
585 | .TS | |
586 | allbox; | |
587 | lbw20 lb lb | |
588 | l l l. | |
589 | Interface Attribute Value | |
590 | T{ | |
591 | .BR scanf (), | |
592 | .BR fscanf (), | |
593 | .br | |
594 | .BR sscanf (), | |
595 | .BR vscanf (), | |
596 | .br | |
597 | .BR vsscanf (), | |
598 | .BR vfscanf () | |
599 | T} Thread safety MT-Safe locale | |
600 | .TE | |
601 | .sp 1 | |
602 | .SH CONFORMING TO | |
603 | The functions | |
604 | .BR fscanf (), | |
605 | .BR scanf (), | |
606 | and | |
607 | .BR sscanf () | |
608 | conform to C89 and C99 and POSIX.1-2001. | |
609 | These standards do not specify the | |
610 | .B ERANGE | |
611 | error. | |
612 | .PP | |
613 | The | |
614 | .B q | |
615 | specifier is the 4.4BSD notation for | |
616 | .IR "long long" , | |
617 | while | |
618 | .B ll | |
619 | or the usage of | |
620 | .B L | |
621 | in integer conversions is the GNU notation. | |
622 | .PP | |
623 | The Linux version of these functions is based on the | |
624 | .I GNU | |
625 | .I libio | |
626 | library. | |
627 | Take a look at the | |
628 | .I info | |
629 | documentation of | |
630 | .I GNU | |
631 | .I libc (glibc-1.08) | |
632 | for a more concise description. | |
633 | .SH NOTES | |
634 | .SS The 'a' assignment-allocation modifier | |
635 | Originally, the GNU C library supported dynamic allocation for string inputs | |
636 | (as a nonstandard extension) via the | |
637 | .B a | |
638 | character. | |
639 | (This feature is present at least as far back as glibc 2.0.) | |
640 | Thus, one could write the following to have | |
641 | .BR scanf () | |
642 | allocate a buffer for an input string, | |
643 | with a pointer to that buffer being returned in | |
644 | .IR *buf : | |
645 | .PP | |
646 | char *buf; | |
647 | scanf("%as", &buf); | |
648 | .PP | |
649 | The use of the letter | |
650 | .B a | |
651 | for this purpose was problematic, since | |
652 | .B a | |
653 | is also specified by the ISO C standard as a synonym for | |
654 | .B f | |
655 | (floating-point input). | |
656 | POSIX.1-2008 instead specifies the | |
657 | .B m | |
658 | modifier for assignment allocation (as documented in DESCRIPTION, above). | |
659 | .PP | |
660 | Note that the | |
661 | .B a | |
662 | modifier is not available if the program is compiled with | |
663 | .I "gcc -std=c99" | |
664 | or | |
665 | .IR "gcc -D_ISOC99_SOURCE" | |
666 | (unless | |
667 | .B _GNU_SOURCE | |
668 | is also specified), in which case the | |
669 | .B a | |
670 | is interpreted as a specifier for floating-point numbers (see above). | |
671 | .PP | |
672 | Support for the | |
673 | .B m | |
674 | modifier was added to glibc starting with version 2.7, | |
675 | and new programs should use that modifier instead of | |
676 | .BR a . | |
677 | .PP | |
678 | As well as being standardized by POSIX, the | |
679 | .B m | |
680 | modifier has the following further advantages over | |
681 | the use of | |
682 | .BR a: | |
683 | .IP * 2 | |
684 | It may also be applied to | |
685 | .B %c | |
686 | conversion specifiers (e.g., | |
687 | .BR %3mc ). | |
688 | .IP * | |
689 | It avoids ambiguity with respect to the | |
690 | .B %a | |
691 | floating-point conversion specifier (and is unaffected by | |
692 | .IR "gcc -std=c99" | |
693 | etc.). | |
694 | .SH BUGS | |
695 | All functions are fully C89 conformant, but provide the | |
696 | additional specifiers | |
697 | .B q | |
698 | and | |
699 | .B a | |
700 | as well as an additional behavior of the | |
701 | .B L | |
702 | and | |
703 | .B l | |
704 | specifiers. | |
705 | The latter may be considered to be a bug, as it changes the | |
706 | behavior of specifiers defined in C89. | |
707 | .PP | |
708 | Some combinations of the type modifiers and conversion | |
709 | specifiers defined by ANSI C do not make sense | |
710 | (e.g., | |
711 | .BR "%Ld" ). | |
712 | While they may have a well-defined behavior on Linux, this need not | |
713 | to be so on other architectures. | |
714 | Therefore it usually is better to use | |
715 | modifiers that are not defined by ANSI C at all, that is, use | |
716 | .B q | |
717 | instead of | |
718 | .B L | |
719 | in combination with | |
720 | \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP | |
721 | conversions or | |
722 | .BR ll . | |
723 | .PP | |
724 | The usage of | |
725 | .B q | |
726 | is not the same as on 4.4BSD, | |
727 | as it may be used in float conversions equivalently to | |
728 | .BR L . | |
729 | .SH EXAMPLE | |
730 | To use the dynamic allocation conversion specifier, specify | |
731 | .B m | |
732 | as a length modifier (thus | |
733 | .B %ms | |
734 | or | |
735 | \fB%m[\fP\fIrange\fP\fB]\fP). | |
736 | The caller must | |
737 | .BR free (3) | |
738 | the returned string, as in the following example: | |
739 | .PP | |
740 | .in +4n | |
741 | .EX | |
742 | char *p; | |
743 | int n; | |
744 | ||
745 | errno = 0; | |
746 | n = scanf("%m[a-z]", &p); | |
747 | if (n == 1) { | |
748 | printf("read: %s\\n", p); | |
749 | free(p); | |
750 | } else if (errno != 0) { | |
751 | perror("scanf"); | |
752 | } else { | |
753 | fprintf(stderr, "No matching characters\\n"); | |
754 | } | |
755 | .EE | |
756 | .in | |
757 | .PP | |
758 | As shown in the above example, it is necessary to call | |
759 | .BR free (3) | |
760 | only if the | |
761 | .BR scanf () | |
762 | call successfully read a string. | |
763 | .SH SEE ALSO | |
764 | .BR getc (3), | |
765 | .BR printf (3), | |
766 | .BR setlocale (3), | |
767 | .BR strtod (3), | |
768 | .BR strtol (3), | |
769 | .BR strtoul (3) |