1 /*
2 * Copyright (c) 1990 The Regents of the University of California.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms are permitted
6 * provided that the above copyright notice and this paragraph are
7 * duplicated in all such forms and that any documentation,
8 * and/or other materials related to such
9 * distribution and use acknowledge that the software was developed
10 * by the University of California, Berkeley. The name of the
11 * University may not be used to endorse or promote products derived
12 * from this software without specific prior written permission.
13 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
14 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
15 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
16 */
17
18 /*
19 FUNCTION
20 <<sscanf>>, <<fscanf>>, <<scanf>>---scan and format input
21
22 INDEX
23 scanf
24 INDEX
25 _scanf_r
26 INDEX
27 fscanf
28 INDEX
29 _fscanf_r
30 INDEX
31 sscanf
32 INDEX
33 _sscanf_r
34
35 SYNOPSIS
36 #include <stdio.h>
37
38 int scanf(const char *restrict <[format]>, ...);
39 int fscanf(FILE *restrict <[fd]>, const char *restrict <[format]>, ...);
40 int sscanf(const char *restrict <[str]>, const char *restrict <[format]>, ...);
41
42 int scanf( const char *restrict <[format]>, ...);
43 int fscanf( FILE *restrict <[fd]>,
44 const char *restrict <[format]>, ...);
45 int sscanf( const char *restrict <[str]>,
46 const char *restrict <[format]>, ...);
47
48 DESCRIPTION
49 <<scanf>> scans a series of input fields from standard input,
50 one character at a time. Each field is interpreted according to
51 a format specifier passed to <<scanf>> in the format string at
52 <<*<[format]>>>. <<scanf>> stores the interpreted input from
53 each field at the address passed to it as the corresponding argument
54 following <[format]>. You must supply the same number of
55 format specifiers and address arguments as there are input fields.
56
57 There must be sufficient address arguments for the given format
58 specifiers; if not the results are unpredictable and likely
59 disasterous. Excess address arguments are merely ignored.
60
61 <<scanf>> often produces unexpected results if the input diverges from
62 an expected pattern. Since the combination of <<gets>> or <<fgets>>
63 followed by <<sscanf>> is safe and easy, that is the preferred way
64 to be certain that a program is synchronized with input at the end
65 of a line.
66
67 <<fscanf>> and <<sscanf>> are identical to <<scanf>>, other than the
68 source of input: <<fscanf>> reads from a file, and <<sscanf>>
69 from a string.
70
71 The routines <<_scanf_r>>, <<_fscanf_r>>, and <<_sscanf_r>> are reentrant
72 versions of <<scanf>>, <<fscanf>>, and <<sscanf>> that take an additional
73 first argument pointing to a reentrancy structure.
74
75 The string at <<*<[format]>>> is a character sequence composed
76 of zero or more directives. Directives are composed of
77 one or more whitespace characters, non-whitespace characters,
78 and format specifications.
79
80 Whitespace characters are blank (<< >>), tab (<<\t>>), or
81 newline (<<\n>>).
82 When <<scanf>> encounters a whitespace character in the format string
83 it will read (but not store) all consecutive whitespace characters
84 up to the next non-whitespace character in the input.
85
86 Non-whitespace characters are all other ASCII characters except the
87 percent sign (<<%>>). When <<scanf>> encounters a non-whitespace
88 character in the format string it will read, but not store
89 a matching non-whitespace character.
90
91 Format specifications tell <<scanf>> to read and convert characters
92 from the input field into specific types of values, and store then
93 in the locations specified by the address arguments.
94
95 Trailing whitespace is left unread unless explicitly
96 matched in the format string.
97
98 The format specifiers must begin with a percent sign (<<%>>)
99 and have the following form:
100
101 . %[*][<[width]>][<[size]>]<[type]>
102
103 Each format specification begins with the percent character (<<%>>).
104 The other fields are:
105 O+
106 o *
107
108 an optional marker; if present, it suppresses interpretation and
109 assignment of this input field.
110
111 o <[width]>
112
113 an optional maximum field width: a decimal integer,
114 which controls the maximum number of characters that
115 will be read before converting the current input field. If the
116 input field has fewer than <[width]> characters, <<scanf>>
117 reads all the characters in the field, and then
118 proceeds with the next field and its format specification.
119
120 If a whitespace or a non-convertable character occurs
121 before <[width]> character are read, the characters up
122 to that character are read, converted, and stored.
123 Then <<scanf>> proceeds to the next format specification.
124
125 o <[size]>
126
127 <<h>>, <<j>>, <<l>>, <<L>>, <<t>>, and <<z>> are optional size
128 characters which override the default way that <<scanf>>
129 interprets the data type of the corresponding argument.
130
131 @multitable @columnfractions 0.18 0.30 0.52
132 @headitem
133 Modifier
134 @tab
135 Type(s)
136 @tab
137 @item
138 hh
139 @tab
140 d, i, o, u, x, n
141 @tab
142 convert input to char, store in char object
143 @item
144 h
145 @tab
146 d, i, o, u, x, n
147 @tab
148 convert input to short, store in short object
149 @item
150 h
151 @tab
152 D, I, O, U, X, e, f, c, s, p
153 @tab
154 no effect
155 @item
156 j
157 @tab
158 d, i, o, u, x, n
159 @tab
160 convert input to intmax_t, store in intmax_t object
161 @item
162 j
163 @tab
164 all others
165 @tab
166 no effect
167 @item
168 l
169 @tab
170 d, i, o, u, x, n
171 @tab
172 convert input to long, store in long object
173 @item
174 l
175 @tab
176 e, f, g
177 @tab
178 convert input to double, store in a double object
179 @item
180 l
181 @tab
182 D, I, O, U, X, c, s, p
183 @tab
184 no effect
185 @item
186 ll
187 @tab
188 d, i, o, u, x, n
189 @tab
190 convert to long long, store in long long object
191 @item
192 L
193 @tab
194 d, i, o, u, x, n
195 @tab
196 convert to long long, store in long long object
197 @item
198 L
199 @tab
200 e, f, g, E, G
201 @tab
202 convert to long double, store in long double object
203 @item
204 L
205 @tab
206 all others
207 @tab
208 no effect
209 @item
210 t
211 @tab
212 d, i, o, u, x, n
213 @tab
214 convert input to ptrdiff_t, store in ptrdiff_t object
215 @item
216 t
217 @tab
218 all others
219 @tab
220 no effect
221 @item
222 z
223 @tab
224 d, i, o, u, x, n
225 @tab
226 convert input to size_t, store in size_t object
227 @item
228 z
229 @tab
230 all others
231 @tab
232 no effect
233 @end multitable
234
235 o <[type]>
236
237 A character to specify what kind of conversion
238 <<scanf>> performs. Here is a table of the conversion
239 characters:
240
241 o+
242 o %
243 No conversion is done; the percent character (<<%>>) is stored.
244
245 o c
246 Scans one character. Corresponding <[arg]>: <<(char *arg)>>.
247
248 o s
249 Reads a character string into the array supplied.
250 Corresponding <[arg]>: <<(char arg[])>>.
251
252 o [<[pattern]>]
253 Reads a non-empty character string into memory
254 starting at <[arg]>. This area must be large
255 enough to accept the sequence and a
256 terminating null character which will be added
257 automatically. (<[pattern]> is discussed in the paragraph following
258 this table). Corresponding <[arg]>: <<(char *arg)>>.
259
260 o d
261 Reads a decimal integer into the corresponding <[arg]>: <<(int *arg)>>.
262
263 o D
264 Reads a decimal integer into the corresponding
265 <[arg]>: <<(long *arg)>>.
266
267 o o
268 Reads an octal integer into the corresponding <[arg]>: <<(int *arg)>>.
269
270 o O
271 Reads an octal integer into the corresponding <[arg]>: <<(long *arg)>>.
272
273 o u
274 Reads an unsigned decimal integer into the corresponding
275 <[arg]>: <<(unsigned int *arg)>>.
276
277 o U
278 Reads an unsigned decimal integer into the corresponding <[arg]>:
279 <<(unsigned long *arg)>>.
280
281 o x,X
282 Read a hexadecimal integer into the corresponding <[arg]>:
283 <<(int *arg)>>.
284
285 o e, f, g
286 Read a floating-point number into the corresponding <[arg]>:
287 <<(float *arg)>>.
288
289 o E, F, G
290 Read a floating-point number into the corresponding <[arg]>:
291 <<(double *arg)>>.
292
293 o i
294 Reads a decimal, octal or hexadecimal integer into the
295 corresponding <[arg]>: <<(int *arg)>>.
296
297 o I
298 Reads a decimal, octal or hexadecimal integer into the
299 corresponding <[arg]>: <<(long *arg)>>.
300
301 o n
302 Stores the number of characters read in the corresponding
303 <[arg]>: <<(int *arg)>>.
304
305 o p
306 Stores a scanned pointer. ANSI C leaves the details
307 to each implementation; this implementation treats
308 <<%p>> exactly the same as <<%U>>. Corresponding
309 <[arg]>: <<(void **arg)>>.
310 o-
311
312 A <[pattern]> of characters surrounded by square brackets can be used
313 instead of the <<s>> type character. <[pattern]> is a set of
314 characters which define a search set of possible characters making up
315 the <<scanf>> input field. If the first character in the brackets is a
316 caret (<<^>>), the search set is inverted to include all ASCII characters
317 except those between the brackets. There is also a range facility
318 which you can use as a shortcut. <<%[0-9] >> matches all decimal digits.
319 The hyphen must not be the first or last character in the set.
320 The character prior to the hyphen must be lexically less than the
321 character after it.
322
323 Here are some <[pattern]> examples:
324 o+
325 o %[abcd]
326 matches strings containing only <<a>>, <<b>>, <<c>>, and <<d>>.
327
328 o %[^abcd]
329 matches strings containing any characters except <<a>>, <<b>>,
330 <<c>>, or <<d>>
331
332 o %[A-DW-Z]
333 matches strings containing <<A>>, <<B>>, <<C>>, <<D>>, <<W>>,
334 <<X>>, <<Y>>, <<Z>>
335
336 o %[z-a]
337 matches the characters <<z>>, <<->>, and <<a>>
338 o-
339
340 Floating point numbers (for field types <<e>>, <<f>>, <<g>>, <<E>>,
341 <<F>>, <<G>>) must correspond to the following general form:
342
343 . [+/-] ddddd[.]ddd [E|e[+|-]ddd]
344
345 where objects inclosed in square brackets are optional, and <<ddd>>
346 represents decimal, octal, or hexadecimal digits.
347 O-
348
349 RETURNS
350 <<scanf>> returns the number of input fields successfully
351 scanned, converted and stored; the return value does
352 not include scanned fields which were not stored.
353
354 If <<scanf>> attempts to read at end-of-file, the return
355 value is <<EOF>>.
356
357 If no fields were stored, the return value is <<0>>.
358
359 <<scanf>> might stop scanning a particular field before
360 reaching the normal field end character, or may
361 terminate entirely.
362
363 <<scanf>> stops scanning and storing the current field
364 and moves to the next input field (if any)
365 in any of the following situations:
366
367 O+
368 o The assignment suppressing character (<<*>>) appears
369 after the <<%>> in the format specification; the current
370 input field is scanned but not stored.
371
372 o <[width]> characters have been read (<[width]> is a
373 width specification, a positive decimal integer).
374
375 o The next character read cannot be converted
376 under the the current format (for example,
377 if a <<Z>> is read when the format is decimal).
378
379 o The next character in the input field does not appear
380 in the search set (or does appear in the inverted search set).
381 O-
382
383 When <<scanf>> stops scanning the current input field for one of
384 these reasons, the next character is considered unread and
385 used as the first character of the following input field, or the
386 first character in a subsequent read operation on the input.
387
388 <<scanf>> will terminate under the following circumstances:
389
390 O+
391 o The next character in the input field conflicts
392 with a corresponding non-whitespace character in the
393 format string.
394
395 o The next character in the input field is <<EOF>>.
396
397 o The format string has been exhausted.
398 O-
399
400 When the format string contains a character sequence that is
401 not part of a format specification, the same character
402 sequence must appear in the input; <<scanf>> will
403 scan but not store the matched characters. If a
404 conflict occurs, the first conflicting character remains in the input
405 as if it had never been read.
406
407 PORTABILITY
408 <<scanf>> is ANSI C.
409
410 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
411 <<lseek>>, <<read>>, <<sbrk>>, <<write>>.
412 */
413
414 #define _DEFAULT_SOURCE
415 #include <_ansi.h>
416 #include <stdio.h>
417 #include <string.h>
418 #include <stdarg.h>
419 #include "local.h"
420
421 #ifndef _REENT_ONLY
422
423 int
sscanf(const char * __restrict str,const char * fmt,...)424 sscanf (const char *__restrict str,
425 const char * fmt, ...)
426 {
427 int ret;
428 va_list ap;
429 FILE f;
430
431 f._flags = __SRD | __SSTR;
432 f._bf._base = f._p = (unsigned char *) str;
433 f._bf._size = f._r = strlen (str);
434 f._read = __seofread;
435 f._ub._base = NULL;
436 f._lb._base = NULL;
437 f._file = -1; /* No file. */
438 va_start (ap, fmt);
439 ret = _ssvfscanf ( &f, fmt, ap);
440 va_end (ap);
441 return ret;
442 }
443
444 #ifdef _NANO_FORMATTED_IO
445 int __nonnull((1)) _NOTHROW
446 siscanf (const char *, const char *, ...)
447 _ATTRIBUTE ((__alias__("sscanf")));
448 #endif
449
450 #endif /* !_REENT_ONLY */
451
