sys/man/2/fscanf

   1 .TH FSCANF 2
   2 .SH NAME
   3 fscanf, scanf, sscanf, vfscanf \- scan formatted input
   4 .SH SYNOPSIS
   5 .B "#include <u.h>
   6 .br
   7 .B "#include <stdio.h>"
   8 .PP
   9 .B
  10 int fscanf(FILE *f, char *format, ...)
  11 .PP
  12 .B
  13 int scanf(char *format, ... )
  14 .PP
  15 .B
  16 int sscanf(char *s, char *format, ...)
  17 .PP
  18 .B
  19 int vfscanf(FILE *stream, char *format, char *args)
  20 .SH DESCRIPTION
  21 .I Fscanf
  22 reads from the named input stream
  23 .I f
  24 (see
  25 .IR fopen (2))
  26 under control of the string pointed to by
  27 .I format
  28 that specifies the admissible input sequences and how they are to be converted
  29 for assignment, using subsequent arguments as pointers to the objects
  30 to receive the converted input.
  31 If there are insufficient arguments for the format, the behavior is undefined.
  32 If the format is exhausted while arguments remain, the excess arguments
  33 are evaluated (as always) but are otherwise ignored.
  34 .PP
  35 .I Scanf
  36 and
  37 .I sscanf
  38 are the same, but they read from
  39 .I stdin
  40 and the character string
  41 .IR s ,
  42 respectively.
  43 .I Vfscanf
  44 is like
  45 .IR scanf ,
  46 except the
  47 .I args
  48 argument is a pointer to an argument in an argument list of the
  49 calling function and the effect is as if the calling function's
  50 argument list from that point on is passed to the scanf routines.
  51 .PP
  52 The format is composed of zero or more directives:
  53 one or more white-space characters; an ordinary character (not
  54 .BR % );
  55 or a conversion specification.
  56 Each conversion specification is introduced by the character
  57 .BR %.
  58 After the
  59 .BR % ,
  60 the following appear in sequence:
  61 .PP
  62 .RS
  63 An optional assignment-suppressing character
  64 .BR * .
  65 .PP
  66 An optional decimal integer that specifies the maximum field width.
  67 .PP
  68 An optional
  69 .BR h ,
  70 .B l
  71 (ell) or
  72 .B L
  73 indicating the size of the receiving object.
  74 The conversion specifiers
  75 .BR d ,
  76 .BR i ,
  77 and
  78 .B n
  79 shall be preceded by
  80 .B h
  81 if the corresponding argument is a pointer to
  82 .B short
  83 rather than a pointer to
  84 .BR int ,
  85 or by
  86 .B l
  87 if it is a pointer to
  88 .BR long .
  89 Similarly, the conversion specifiers
  90 .BR o ,
  91 .BR u ,
  92 and
  93 .B x
  94 shall be preceded by
  95 .B h
  96 if the corresponding argument is a pointer to
  97 .B unsigned
  98 .B short
  99 rather than a pointer to
 100 .BR unsigned ,
 101 or by
 102 .B l
 103 if it is a pointer to
 104 .B unsigned
 105 .BR long .
 106 Finally, the conversion specifiers
 107 .BR e ,
 108 .BR f ,
 109 and
 110 .B g
 111 shall be preceded by
 112 .B l
 113 if the corresponding argument is a pointer to
 114 .B double
 115 rather than a pointer to
 116 .BR float ,
 117 or by
 118 .B L
 119 if it is a pointer to
 120 .B long
 121 .BR double .
 122 If an
 123 .BR h ,
 124 .BR l ,
 125 or
 126 .B L
 127 appears with any other conversion specifier, the behavior is undefined.
 128 .PP
 129 A character that specifies the type of conversion to be applied.
 130 The valid conversion specifiers are described below.
 131 .RE
 132 .PP
 133 .I Fscanf
 134 executes each directive of the format in turn.
 135 If a directive fails, as detailed below,
 136 .I fscanf
 137 returns.
 138 Failures are described as input failures (due to the unavailability
 139 of input),
 140 or matching failures (due to inappropriate input).
 141 .PP
 142 A directive composed of white space is executed by reading input up
 143 to the first non-white-space character (which remains unread),
 144 or until no more characters can be read.
 145 .PP
 146 A directive that is an ordinary character is executed by reading
 147 the next character from the stream.
 148 If if differs from the one comprising the directive,
 149 the directive fails, and the differing and subsequent characters
 150 remain unread.
 151 .PP
 152 A directive that is a conversion specification defines a set of
 153 matching input sequences, as described below for each specifier.
 154 A conversion specification is executed in the following steps:
 155 .PP
 156 Input white-space characters (as specified by
 157 .IR isspace ,
 158 see
 159 .IR ctype (2))
 160 are skipped, unless the specification includes a
 161 .BR [ ,
 162 .BR c ,
 163 or
 164 .B n
 165 specifier.
 166 .PP
 167 An input item is read from the stream,
 168 unless the specification includes an
 169 .B n
 170 specifier.
 171 An input item is defined as the longest sequence of input characters
 172 (up to any specified maximum field width) which is an initial
 173 subsequence of a matching sequence.
 174 The first character, if any, after the input item remains unread.
 175 If the length of the input item is zero, the execution of
 176 the directive fails: this condition is a matching failure,
 177 unless an error prevented input from the stream,
 178 in which case it is an input failure.
 179 .PP
 180 Except in the case of a
 181 .B %
 182 specifier, the input item (or, in the case of a
 183 .B %n
 184 directive, the count of input characters)
 185 is converted to a type appropriate to the conversion specifier.
 186 If the input item is not a matching sequence, the execution of
 187 the directive fails: this condition is a matching failure.
 188 Unless assignment suppression was indicated by a
 189 .BR * ,
 190 the result of the conversion is placed in the object pointed to by the
 191 first argument following the
 192 .I format
 193 argument that has not already received a conversion result.
 194 If this object does not have an appropriate type,
 195 or if the result of the conversion cannot be represented
 196 in the space provided, the behavior is undefined.
 197 .PP
 198 The following conversion specifiers are valid:
 199 .TP 6
 200 .B d
 201 Matches an optionally signed decimal integer,
 202 whose format is the same as expected for the subject sequence
 203 of the
 204 .I strtol
 205 (see
 206 .IR atof (2))
 207 function with 10 for the
 208 .B base
 209 argument.
 210 The corresponding argument shall be a pointer to
 211 .BR int .
 212 .TP
 213 .B i
 214 Matches an optionally signed decimal integer,
 215 whose format is the same as expected for the subject sequence
 216 of the
 217 .I strtol
 218 function with 0 for the
 219 .B base
 220 argument.
 221 The corresponding argument shall be a pointer to
 222 .BR int .
 223 .TP
 224 .B o
 225 Matches an optionally signed octal integer,
 226 whose format is the same as expected for the subject sequence
 227 of the
 228 .I strtoul
 229 (see
 230 .IR atof (2))
 231 function with 8 for the
 232 .B base
 233 argument.
 234 The corresponding argument shall be a pointer to
 235 .B unsigned
 236 .BR int .
 237 .TP
 238 .B u
 239 Matches an optionally signed decimal integer,
 240 whose format is the same as expected for the subject sequence
 241 of the
 242 .I strtoul
 243 function with 10 for the
 244 .B base
 245 argument.
 246 The corresponding argument shall be a pointer to
 247 .B unsigned
 248 .BR int .
 249 .TP
 250 .B x
 251 Matches an optionally signed hexadecimal integer,
 252 whose format is the same as expected for the subject sequence
 253 of the
 254 .I strtoul
 255 function with 16 for the
 256 .B base
 257 argument.
 258 The corresponding argument shall be a pointer to
 259 .B unsigned
 260 .BR int .
 261 .TP
 262 .BR e , f , g
 263 Matches an optionally signed floating-point number, whose format is
 264 the same as expected for the subject string of the
 265 .I strtod
 266 (see
 267 .IR atof (2))
 268 function.
 269 The corresponding argument shall be a pointer to
 270 .BR float .
 271 .TP
 272 .B s
 273 Matches a sequence of non-white-space characters.
 274 The corresponding argument shall be a pointer to the initial
 275 character of an array large enough to accept the sequence
 276 and a terminating NUL (0) character, which will be added automatically.
 277 .TP
 278 .B [
 279 Matches a nonempty sequence of characters from a set of expected
 280 characters (the
 281 .IR scanset ).
 282 The corresponding argument shall be a pointer to the initial
 283 character of an array large enough to accept the sequence and a terminating
 284 NUL character, which will be added automatically.
 285 The conversion specifier includes all subsequent characters in the
 286 .I format
 287 string, up to and including the matching right brace
 288 .RB ( ] ).
 289 The characters between the brackets (the
 290 .IR scanlist )
 291 comprise the scanset, unless the character after the left bracket
 292 is a circumflex
 293 .RB ( ^ ),
 294 in which case the scanset contains all characters that do not appear
 295 in the scanlist between the circumflex and the right bracket.
 296 As a special case, if the conversion specifier begins with
 297 .B []
 298 or
 299 .BR [^] ,
 300 the right bracket character is in the scanlist and the next
 301 right bracket character is the matching right bracket
 302 that ends the specification.
 303 If a
 304 .B -
 305 character is in the scanlist and is not the first, nor the second
 306 where the first character is a
 307 .BR ^ ,
 308 nor the last character, the behavior is implementation-defined
 309 (in Plan 9: the scanlist includes all characters in the
 310 .SM ASCII
 311 (sic)
 312 range between the two characters on either side of the
 313 .BR - ).
 314 .TP
 315 .B c
 316 Matches a sequence of characters of the number specified by the field width
 317 (1 if no field width is present in the directive).
 318 The corresponding argument shall be a pointer to the initial character
 319 of an array large enough to accept the sequence.
 320 No NUL character is added.
 321 .TP
 322 .B P
 323 Matches an implementation-defined set of sequences,
 324 which should be the same as the set of sequences that may be
 325 produced by the
 326 .B %P
 327 conversion of the
 328 .IR fprintf (2)
 329 function
 330 (in Plan 9, a hexadecimal number).
 331 The corresponding argument shall be a pointer to a pointer to
 332 .BR void .
 333 The interpretation of the input item is implementation defined;
 334 however, for any input item other than a value converted earlier
 335 during the same program execution, the behavior of the
 336 .B %P
 337 conversion is undefined.
 338 .TP
 339 .B n
 340 No input is consumed.
 341 The corresponding argument shall be a pointer to integer into which
 342 is written the number of characters read from the input stream so far
 343 by this call to
 344 .IR fscanf .
 345 Execution of a
 346 .B %n
 347 directive does not increment the assignment count returned at the
 348 completion of
 349 .IR fscanf .
 350 .TP
 351 .B %
 352 Matches a single
 353 .BR % ;
 354 no conversion or assignment occurs.
 355 The complete conversion specification shall be
 356 .BR %% .
 357 .PD
 358 .PP
 359 If a conversion specification is invalid, the behavior is undefined.
 360 .PP
 361 The conversion specifiers
 362 .BR E ,
 363 .BR G ,
 364 and
 365 .B X
 366 are also valid and behave the same as, respectively,
 367 .BR e ,
 368 .BR g ,
 369 and
 370 .BR x .
 371 .PP
 372 If end-of-file is encountered during input, conversion is terminated.
 373 If end-of-file occurs before any characters matching the current
 374 directive have been read (other than leading white space,
 375 where permitted), execution of the current directive terminates with
 376 an input failure;
 377 otherwise, unless execution of the current directive is terminated
 378 with a matching failure, execution of the following directive
 379 (if any) is terminated with an input failure.
 380 .PP
 381 If conversion terminates on a conflicting input character,
 382 the offending input character is left unread in the input stream.
 383 Trailing white space (including newline characters) is left unread
 384 unless matched by a directive.
 385 The success of literal matches and suppressed assignments is not
 386 directly determinable other than via the
 387 .B %n
 388 directive.
 389 .PP
 390 The return value from
 391 .I fscanf
 392 is the number of input items assigned, which can be fewer than
 393 provided for, or even zero, in the event of an early matching failure.
 394 However, if an input failure occurs before any conversion,
 395 .B EOF
 396 is returned.
 397 .SH SOURCE
 398 .B /sys/src/libstdio
 399 .SH "SEE ALSO"
 400 .IR fopen (2),
 401 .IR fgetc (2)
 402 .SH BUGS
 403 Does not know about
 404 .SM UTF.