newlib/libc/stdio/sscanf.c

   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_r(struct _reent *<[ptr]>, const char *restrict <[format]>, ...);
  43         int _fscanf_r(struct _reent *<[ptr]>, FILE *restrict <[fd]>,
  44                       const char *restrict <[format]>, ...);
  45         int _sscanf_r(struct _reent *<[ptr]>, 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 #include <_ansi.h>
 415 #include <reent.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
 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._flags2 = 0;
 433   f._bf._base = f._p = (unsigned char *) str;
 434   f._bf._size = f._r = strlen (str);
 435   f._read = __seofread;
 436   f._ub._base = NULL;
 437   f._lb._base = NULL;
 438   f._file = -1;  /* No file. */
 439   va_start (ap, fmt);
 440   ret = __ssvfscanf_r (_REENT, &f, fmt, ap);
 441   va_end (ap);
 442   return ret;
 443 }
 444
 445 #ifdef _NANO_FORMATTED_IO
 446 int
 447 siscanf (const char *, const char *, ...)
 448        _ATTRIBUTE ((__alias__("sscanf")));
 449 #endif
 450
 451 #endif /* !_REENT_ONLY */
 452
 453 int
 454 _sscanf_r (struct _reent *ptr,
 455        const char *__restrict str,
 456        const char *__restrict fmt, ...)
 457 {
 458   int ret;
 459   va_list ap;
 460   FILE f;
 461
 462   f._flags = __SRD | __SSTR;
 463   f._flags2 = 0;
 464   f._bf._base = f._p = (unsigned char *) str;
 465   f._bf._size = f._r = strlen (str);
 466   f._read = __seofread;
 467   f._ub._base = NULL;
 468   f._lb._base = NULL;
 469   f._file = -1;  /* No file. */
 470   va_start (ap, fmt);
 471   ret = __ssvfscanf_r (ptr, &f, fmt, ap);
 472   va_end (ap);
 473   return ret;
 474 }
 475
 476 #ifdef _NANO_FORMATTED_IO
 477 int
 478 _siscanf_r (struct _reent *, const char *, const char *, ...)
 479        _ATTRIBUTE ((__alias__("_sscanf_r")));
 480 #endif