diff options
Diffstat (limited to 'static/plan9-4e/man2/fscanf.2')
| -rw-r--r-- | static/plan9-4e/man2/fscanf.2 | 402 |
1 files changed, 402 insertions, 0 deletions
diff --git a/static/plan9-4e/man2/fscanf.2 b/static/plan9-4e/man2/fscanf.2 new file mode 100644 index 00000000..bb94924f --- /dev/null +++ b/static/plan9-4e/man2/fscanf.2 @@ -0,0 +1,402 @@ +.TH FSCANF 2 +.SH NAME +fscanf, scanf, sscanf, vfscanf \- scan formatted input +.SH SYNOPSIS +.B "#include <stdio.h>" +.PP +.B +int fscanf(FILE *f, char *format, ...) +.PP +.B +int scanf(char *format, ... ) +.PP +.B +int sscanf(char *s, char *format, ...) +.PP +.B +int vfscanf(FILE *stream, char *format, char *args) +.SH DESCRIPTION +.I Fscanf +reads from the named input stream +.I f +(see +.IR fopen (2)) +under control of the string pointed to by +.I format +that specifies the admissible input sequences and how they are to be converted +for assignment, using subsequent arguments as pointers to the objects +to receive the converted input. +If there are insufficient arguments for the format, the behavior is undefined. +If the format is exhausted while arguments remain, the excess arguments +are evaluated (as always) but are otherwise ignored. +.PP +.I Scanf +and +.I sscanf +are the same, but they read from +.I stdin +and the character string +.IR s , +respectively. +.I Vfscanf +is like +.IR scanf , +except the +.I args +argument is a pointer to an argument in an argument list of the +calling function and the effect is as if the calling function's +argument list from that point on is passed to the scanf routines. +.PP +The format is composed of zero or more directives: +one or more white-space characters; an ordinary character (not +.BR % ); +or a conversion specification. +Each conversion specification is introduced by the character +.BR %. +After the +.BR % , +the following appear in sequence: +.PP +.RS +An optional assignment-suppressing character +.BR * . +.PP +An optional decimal integer that specifies the maximum field width. +.PP +An optional +.BR h , +.B l +(ell) or +.B L +indicating the size of the receiving object. +The conversion specifiers +.BR d , +.BR i , +and +.B n +shall be preceded by +.B h +if the corresponding argument is a pointer to +.B short +rather than a pointer to +.BR int , +or by +.B l +if it is a pointer to +.BR long . +Similarly, the conversion specifiers +.BR o , +.BR u , +and +.B x +shall be preceded by +.B h +if the corresponding argument is a pointer to +.B unsigned +.B short +rather than a pointer to +.BR unsigned , +or by +.B l +if it is a pointer to +.B unsigned +.BR long . +Finally, the conversion specifiers +.BR e , +.BR f , +and +.B g +shall be preceded by +.B l +if the corresponding argument is a pointer to +.B double +rather than a pointer to +.BR float , +or by +.B L +if it is a pointer to +.B long +.BR double . +If an +.BR h , +.BR l , +or +.B L +appears with any other conversion specifier, the behavior is undefined. +.PP +A character that specifies the type of conversion to be applied. +The valid conversion specifiers are described below. +.RE +.PP +.I Fscanf +executes each directive of the format in turn. +If a directive fails, as detailed below, +.I fscanf +returns. +Failures are described as input failures (due to the unavailability +of input), +or matching failures (due to inappropriate input). +.PP +A directive composed of white space is executed by reading input up +to the first non-white-space character (which remains unread), +or until no more characters can be read. +.PP +A directive that is an ordinary character is executed by reading +the next character from the stream. +If if differs from the one comprising the directive, +the directive fails, and the differing and subsequent characters +remain unread. +.PP +A directive that is a conversion specification defines a set of +matching input sequences, as described below for each specifier. +A conversion specification is executed in the following steps: +.PP +Input white-space characters (as specified by +.IR isspace , +see +.IR ctype (2)) +are skipped, unless the specification includes a +.BR [ , +.BR c , +or +.B n +specifier. +.PP +An input item is read from the stream, +unless the specification includes an +.B n +specifier. +An input item is defined as the longest sequence of input characters +(up to any specified maximum field width) which is an initial +subsequence of a matching sequence. +The first character, if any, after the input item remains unread. +If the length of the input item is zero, the execution of +the directive fails: this condition is a matching failure, +unless an error prevented input from the stream, +in which case it is an input failure. +.PP +Except in the case of a +.B % +specifier, the input item (or, in the case of a +.B %n +directive, the count of input characters) +is converted to a type appropriate to the conversion specifier. +If the input item is not a matching sequence, the execution of +the directive fails: this condition is a matching failure. +Unless assignment suppression was indicated by a +.BR * , +the result of the conversion is placed in the object pointed to by the +first argument following the +.I format +argument that has not already received a conversion result. +If this object does not have an appropriate type, +or if the result of the conversion cannot be represented +in the space provided, the behavior is undefined. +.PP +The following conversion specifiers are valid: +.TP 6 +.B d +Matches an optionally signed decimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtol +(see +.IR atof (2)) +function with 10 for the +.B base +argument. +The corresponding argument shall be a pointer to +.BR int . +.TP +.B i +Matches an optionally signed decimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtol +function with 0 for the +.B base +argument. +The corresponding argument shall be a pointer to +.BR int . +.TP +.B o +Matches an optionally signed octal integer, +whose format is the same as expected for the subject sequence +of the +.I strtoul +(see +.IR atof (2)) +function with 8 for the +.B base +argument. +The corresponding argument shall be a pointer to +.B unsigned +.BR int . +.TP +.B u +Matches an optionally signed decimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtoul +function with 10 for the +.B base +argument. +The corresponding argument shall be a pointer to +.B unsigned +.BR int . +.TP +.B x +Matches an optionally signed hexadecimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtoul +function with 16 for the +.B base +argument. +The corresponding argument shall be a pointer to +.B unsigned +.BR int . +.TP +.BR e , f , g +Matches an optionally signed floating-point number, whose format is +the same as expected for the subject string of the +.I strtod +(see +.IR atof (2)) +function. +The corresponding argument shall be a pointer to +.BR float . +.TP +.B s +Matches a sequence of non-white-space characters. +The corresponding argument shall be a pointer to the initial +character of an array large enough to accept the sequence +and a terminating NUL (0) character, which will be added automatically. +.TP +.B [ +Matches a nonempty sequence of characters from a set of expected +characters (the +.IR scanset ). +The corresponding argument shall be a pointer to the initial +character of an array large enough to accept the sequence and a terminating +NUL character, which will be added automatically. +The conversion specifier includes all subsequent characters in the +.I format +string, up to and including the matching right brace +.RB ( ] ). +The characters between the brackets (the +.IR scanlist ) +comprise the scanset, unless the character after the left bracket +is a circumflex +.RB ( ^ ), +in which case the scanset contains all characters that do not appear +in the scanlist between the circumflex and the right bracket. +As a special case, if the conversion specifier begins with +.B [] +or +.BR [^] , +the right bracket character is in the scanlist and the next +right bracket character is the matching right bracket +that ends the specification. +If a +.B - +character is in the scanlist and is not the first, nor the second +where the first character is a +.BR ^ , +nor the last character, the behavior is implementation-defined +(in Plan 9: the scanlist includes all characters in the +.SM ASCII +(sic) +range between the two characters on either side of the +.BR - ). +.TP +.B c +Matches a sequence of characters of the number specified by the field width +(1 if no field width is present in the directive). +The corresponding argument shall be a pointer to the initial character +of an array large enough to accept the sequence. +No NUL character is added. +.TP +.B P +Matches an implementation-defined set of sequences, +which should be the same as the set of sequences that may be +produced by the +.B %P +conversion of the +.IR fprintf (2) +function +(in Plan 9, a hexadecimal number). +The corresponding argument shall be a pointer to a pointer to +.BR void . +The interpretation of the input item is implementation defined; +however, for any input item other than a value converted earlier +during the same program execution, the behavior of the +.B %P +conversion is undefined. +.TP +.B n +No input is consumed. +The corresponding argument shall be a pointer to integer into which +is written the number of characters read from the input stream so far +by this call to +.IR fscanf . +Execution of a +.B %n +directive does not increment the assignment count returned at the +completion of +.IR fscanf . +.TP +.B % +Matches a single +.BR % ; +no conversion or assignment occurs. +The complete conversion specification shall be +.BR %% . +.PD +.PP +If a conversion specification is invalid, the behavior is undefined. +.PP +The conversion specifiers +.BR E , +.BR G , +and +.B X +are also valid and behave the same as, respectively, +.BR e , +.BR g , +and +.BR x . +.PP +If end-of-file is encountered during input, conversion is terminated. +If end-of-file occurs before any characters matching the current +directive have been read (other than leading white space, +where permitted), execution of the current directive terminates with +an input failure; +otherwise, unless execution of the current directive is terminated +with a matching failure, execution of the following directive +(if any) is terminated with an input failure. +.PP +If conversion terminates on a conflicting input character, +the offending input character is left unread in the input stream. +Trailing white space (including newline characters) is left unread +unless matched by a directive. +The success of literal matches and suppressed assignments is not +directly determinable other than via the +.B %n +directive. +.PP +The return value from +.I fscanf +is the number of input items assigned, which can be fewer than +provided for, or even zero, in the event of an early matching failure. +However, if an input failure occurs before any conversion, +.B EOF +is returned. +.SH SOURCE +.B /sys/src/libstdio +.SH "SEE ALSO" +.IR fopen (2), +.IR fgetc (2) +.SH BUGS +Does not know about +.SM UTF. |