Penguin
Recent Changes
Annotated edit history of fscanf(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 SCANF
2 !!!SCANF
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 CONVERSIONS
7 RETURN VALUE
8 SEE ALSO
9 CONFORMING TO
10 BUGS
11 ----
12 !!NAME
13
14
15 scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conversion
16 !!SYNOPSIS
17
18
19 __#include
20 __''format''__, ...__'');
21 ''__int fscanf( FILE *__''stream''__, const char *__''format''__, ...__'');
22 ''__int sscanf( const char *__''str''__, const char *__''format''__, ...__'');
23 ''__#include
24 __''format''__, va_list__ ''ap''__);
25 int vsscanf( const char *__''str''__, const char *__''format''__, va_list__ ''ap''__);
26 int vfscanf( FILE *__''stream''__, const char *__''format''__, va_list__ ''ap''__);
27 __
28 !!DESCRIPTION
29
30
31 The __scanf__ family of functions scans input according
32 to a ''format'' as described below. This format may
33 contain ''conversion specifiers''; the results from such
34 conversions, if any, are stored through the ''pointer''
35 arguments. The __scanf__ function reads input from the
36 standard input stream ''stdin'', __fscanf__ reads
37 input from the stream pointer ''stream'', and
38 __sscanf__ reads its input from the character string
39 pointed to by ''str''.
40
41
42 The __vfscanf__ function is analogous to
43 vfprintf(3) and reads input from the stream pointer
44 ''stream'' using a variable argument list of pointers
45 (see stdarg(3). The __vscanf__ function scans a
46 variable argument list from the standard input and the
47 __vsscanf__ function scans it from a string; these are
48 analogous to the __vprintf__ and __vsprintf__
49 functions respectively.
50
51
52 Each successive ''pointer'' argument must correspond
53 properly with each successive conversion specifier (but see
54 `suppression' below). All conversions are introduced by the
55 __%__ (percent sign) character. The ''format'' string
56 may also contain other characters. White space (such as
57 blanks, tabs, or newlines) in the ''format'' string match
58 any amount of white space, including none, in the input.
59 Everything else matches only itself. Scanning stops when an
60 input character does not match such a format character.
61 Scanning also stops when an input conversion cannot be made
62 (see below).
63 !!CONVERSIONS
64
65
66 Following the __%__ character introducing a conversion
67 there may be a number of ''flag'' characters, as
68 follows:
69
70
71 __*__
72
73
74 Suppresses assignment. The conversion that follows occurs as
75 usual, but no pointer is used; the result of the conversion
76 is simply discarded.
77
78
79 __a__
80
81
82 Indicates that the conversion will be __s__, the needed
83 memory space for the string will be malloc'ed and the
84 pointer to it will be assigned to the ''char'' pointer
85 variable, which does not have to be initialised before. This
86 flag does not exist in ''ANSI C''.
87
88
89 __h__
90
91
92 Indicates that the conversion will be one of __dioux__ or
93 __n__ and the next pointer is a pointer to a ''short
94 int'' (rather than ''int'').
95
96
97 __l__
98
99
100 Indicates either that the conversion will be one of
101 __dioux__ or __n__ and the next pointer is a pointer
102 to a ''long int'' (rather than ''int''), or that the
103 conversion will be one of __efg__ and the next pointer is
104 a pointer to ''double'' (rather than ''float'').
105 Specifying two __l__ flags is equivalent to the __L__
106 flag.
107
108
109 __L__
110
111
112 Indicates that the conversion will be either __efg__ and
113 the next pointer is a pointer to ''long double'' or the
114 conversion will be __dioux__ and the next pointer is a
115 pointer to ''long long''. (Note that long long is not an
116 ''ANSI C'' type. Any program using this will not be
117 portable to all architectures).
118
119
120 __q__
121
122
123 equivalent to L. This flag does not exist in ''ANSI
124 C''.
125
126
127 In addition to these flags, there may be an optional maximum
128 field width, expressed as a decimal integer, between the
129 __%__ and the conversion. If no width is given, a default
130 of `infinity' is used (with one exception, below); otherwise
131 at most this many characters are scanned in processing the
132 conversion. Before conversion begins, most conversions skip
133 white space; this white space is not counted against the
134 field width.
135
136
137 The following conversions are available:
138
139
140 __%__
141
142
143 Matches a literal `%'. That is, `%%' in the format string
144 matches a single input `%' character. No conversion is done,
145 and assignment does not occur.
146
147
148 __d__
149
150
151 Matches an optionally signed decimal integer; the next
152 pointer must be a pointer to ''int''.
153
154
155 __D__
156
157
158 Equivalent to __ld__; this exists only for backwards
159 compatibility. (Note: thus only in libc4. In libc5 and glibc
160 the %D is silently ignored, causing old programs to fail
161 mysteriously.)
162
163
164 __i__
165
166
167 Matches an optionally signed integer; the next pointer must
168 be a pointer to ''int''. The integer is read in base 16
169 if it begins with `0x' or `0X', in base 8 if it begins with
170 `0', and in base 10 otherwise. Only characters that
171 correspond to the base are used.
172
173
174 __o__
175
176
177 Matches an unsigned octal integer; the next pointer must be
178 a pointer to ''unsigned int''.
179
180
181 __u__
182
183
184 Matches an unsigned decimal integer; the next pointer must
185 be a pointer to ''unsigned int''.
186
187
188 __x__
189
190
191 Matches an unsigned hexadecimal integer; the next pointer
192 must be a pointer to ''unsigned int''.
193
194
195 __X__
196
197
198 Equivalent to __x__
199
200
201 __f__
202
203
204 Matches an optionally signed floating-point number; the next
205 pointer must be a pointer to ''float''.
206
207
208 __e__
209
210
211 Equivalent to __f__.
212
213
214 __g__
215
216
217 Equivalent to __f__.
218
219
220 __E__
221
222
223 Equivalent to __f__
224
225
226 __s__
227
228
229 Matches a sequence of non-white-space characters; the next
230 pointer must be a pointer to ''char'', and the array must
231 be large enough to accept all the sequence and the
232 terminating __NUL__ character. The input string stops at
233 white space or at the maximum field width, whichever occurs
234 first.
235
236
237 __c__
238
239
240 Matches a sequence of ''width'' count characters (default
241 1); the next pointer must be a pointer to ''char'', and
242 there must be enough room for all the characters (no
243 terminating __NUL__ is added). The usual skip of leading
244 white space is suppressed. To skip white space first, use an
245 explicit space in the format.
246
247
248 __[[__
249
250
251 Matches a nonempty sequence of characters from the specified
252 set of accepted characters; the next pointer must be a
253 pointer to ''char'', and there must be enough room for
254 all the characters in the string, plus a terminating
255 __NUL__ character. The usual skip of leading white space
256 is suppressed. The string is to be made up of characters in
257 (or not in) a particular set; the set is defined by the
258 characters between the open bracket __[[__ character and a
259 close bracket __]__ character. The set ''excludes''
260 those characters if the first character after the open
261 bracket is a circumflex __^__. To include a close bracket
262 in the set, make it the first character after the open
263 bracket or the circumflex; any other position will end the
264 set. The hyphen character __-__ is also special; when
265 placed between two other characters, it adds all intervening
266 characters to the set. To include a hyphen, make it the last
267 character before the final close bracket. For instance,
268 `[[^]0-9-]' means the set `everything except close bracket,
269 zero through nine, and hyphen'. The string ends with the
270 appearance of a character not in the (or, with a circumflex,
271 in) set or when the field width runs out.
272
273
274 __p__
275
276
277 Matches a pointer value (as printed by `%p' in
278 printf(3); the next pointer must be a pointer to
279 ''void''.
280
281
282 __n__
283
284
285 Nothing is expected; instead, the number of characters
286 consumed thus far from the input is stored through the next
287 pointer, which must be a pointer to ''int''. This is
288 ''not'' a conversion, although it can be suppressed with
289 the __*__ flag. The C standard says: `Execution of a %n
290 directive does not increment the assignment count returned
291 at the completion of execution' but the Corrigendum seems to
292 contradict this. Probably it is wise not to make any
293 assumptions on the effect of %n conversions on the return
294 value.
295 !!RETURN VALUE
296
297
298 These functions return the number of input items assigned,
299 which can be fewer than provided for, or even zero, in the
300 event of a matching failure. Zero indicates that, while
301 there was input available, no conversions were assigned;
302 typically this is due to an invalid input character, such as
303 an alphabetic character for a `%d' conversion. The value
304 __EOF__ is returned if an input failure occurs before any
305 conversion such as an end-of-file occurs. If an error or
306 end-of-file occurs after conversion has begun, the number of
307 conversions which were successfully completed is
308 returned.
309 !!SEE ALSO
310
311
312 strtol(3), strtoul(3), strtod(3),
313 getc(3), printf(3)
314 !!CONFORMING TO
315
316
317 The functions __fscanf__, __scanf__, and __sscanf__
318 conform to ANSI X3.159-1989 (``ANSI C'').
319
320
321 The __q__ flag is the ''BSD 4.4'' notation for ''long
322 long'', while __ll__ or the usage of __L__ in
323 integer conversions is the GNU notation.
324
325
326 The Linux version of these functions is based on the ''GNU
327 libio'' library. Take a look at the ''info''
328 documentation of ''GNU libc (glibc-1.08)'' for a more
329 concise description.
330 !!BUGS
331
332
333 All functions are fully ANSI X3.159-1989 conformant, but
334 provide the additional flags __q__ and __a__ as well
335 as an additional behaviour of the __L__ and __l__
336 flags. The latter may be considered to be a bug, as it
337 changes the behaviour of flags defined in ANSI
338 X3.159-1989.
339
340
341 Some combinations of flags defined by ''ANSI C'' are not
342 making sense in ''ANSI C'' (e.g. __%Ld__). While they
343 may have a well-defined behaviour on Linux, this need not to
344 be so on other architectures. Therefore it usually is better
345 to use flags that are not defined by ''ANSI C'' at all,
346 i.e. use __q__ instead of __L__ in combination with
347 __diouxX__ conversions or __ll__.
348
349
350 The usage of __q__ is not the same as on ''BSD 4.4'',
351 as it may be used in float conversions equivalently to
352 __L__.
353 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.