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