.TH FSCANF 2.SH NAMEfscanf, scanf, sscanf, vfscanf \- scan formatted input.SH SYNOPSIS.B "#include <u.h>.br.B "#include <stdio.h>".PP.Bint fscanf(FILE *f, char *format, ...).PP.Bint scanf(char *format, ... ).PP.Bint sscanf(char *s, char *format, ...).PP.Bint vfscanf(FILE *stream, char *format, char *args).SH DESCRIPTION.I Fscanfreads from the named input stream.I f(see.IR fopen (2))under control of the string pointed to by.I formatthat specifies the admissible input sequences and how they are to be convertedfor assignment, using subsequent arguments as pointers to the objectsto 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 argumentsare evaluated (as always) but are otherwise ignored..PP.I Scanfand.I sscanfare the same, but they read from.I stdinand the character string.IR s ,respectively..I Vfscanfis like.IR scanf ,except the.I argsargument is a pointer to an argument in an argument list of thecalling function and the effect is as if the calling function'sargument list from that point on is passed to the scanf routines..PPThe 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.RSAn optional assignment-suppressing character.BR * ..PPAn optional decimal integer that specifies the maximum field width..PPAn optional.BR h ,.B l(ell) or.B Lindicating the size of the receiving object.The conversion specifiers.BR d ,.BR i ,and.B nshall be preceded by.B hif the corresponding argument is a pointer to.B shortrather than a pointer to.BR int ,or by.B lif it is a pointer to.BR long .Similarly, the conversion specifiers.BR o ,.BR u ,and.B xshall be preceded by.B hif the corresponding argument is a pointer to.B unsigned.B shortrather than a pointer to.BR unsigned ,or by.B lif it is a pointer to.B unsigned.BR long .Finally, the conversion specifiers.BR e ,.BR f ,and.B gshall be preceded by.B lif the corresponding argument is a pointer to.B doublerather than a pointer to.BR float ,or by.B Lif it is a pointer to.B long.BR double .If an.BR h ,.BR l ,or.B Lappears with any other conversion specifier, the behavior is undefined..PPA character that specifies the type of conversion to be applied.The valid conversion specifiers are described below..RE.PP.I Fscanfexecutes each directive of the format in turn.If a directive fails, as detailed below,.I fscanfreturns.Failures are described as input failures (due to the unavailabilityof input),or matching failures (due to inappropriate input)..PPA directive composed of white space is executed by reading input upto the first non-white-space character (which remains unread),or until no more characters can be read..PPA directive that is an ordinary character is executed by readingthe next character from the stream.If if differs from the one comprising the directive,the directive fails, and the differing and subsequent charactersremain unread..PPA directive that is a conversion specification defines a set ofmatching input sequences, as described below for each specifier.A conversion specification is executed in the following steps:.PPInput white-space characters (as specified by.IR isspace ,see.IR ctype (2))are skipped, unless the specification includes a.BR [ ,.BR c ,or.B nspecifier..PPAn input item is read from the stream,unless the specification includes an.B nspecifier.An input item is defined as the longest sequence of input characters(up to any specified maximum field width) which is an initialsubsequence 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 ofthe directive fails: this condition is a matching failure,unless an error prevented input from the stream,in which case it is an input failure..PPExcept in the case of a.B %specifier, the input item (or, in the case of a.B %ndirective, 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 ofthe 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 thefirst argument following the.I formatargument 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 representedin the space provided, the behavior is undefined..PPThe following conversion specifiers are valid:.TP 6.B dMatches an optionally signed decimal integer,whose format is the same as expected for the subject sequenceof the.I strtol(see.IR atof (2))function with 10 for the.B baseargument.The corresponding argument shall be a pointer to.BR int ..TP.B iMatches an optionally signed decimal integer,whose format is the same as expected for the subject sequenceof the.I strtolfunction with 0 for the.B baseargument.The corresponding argument shall be a pointer to.BR int ..TP.B oMatches an optionally signed octal integer,whose format is the same as expected for the subject sequenceof the.I strtoul(see.IR atof (2))function with 8 for the.B baseargument.The corresponding argument shall be a pointer to.B unsigned.BR int ..TP.B uMatches an optionally signed decimal integer,whose format is the same as expected for the subject sequenceof the.I strtoulfunction with 10 for the.B baseargument.The corresponding argument shall be a pointer to.B unsigned.BR int ..TP.B xMatches an optionally signed hexadecimal integer,whose format is the same as expected for the subject sequenceof the.I strtoulfunction with 16 for the.B baseargument.The corresponding argument shall be a pointer to.B unsigned.BR int ..TP.BR e , f , gMatches an optionally signed floating-point number, whose format isthe 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 sMatches a sequence of non-white-space characters.The corresponding argument shall be a pointer to the initialcharacter of an array large enough to accept the sequenceand a terminating NUL (0) character, which will be added automatically..TP.B [Matches a nonempty sequence of characters from a set of expectedcharacters (the.IR scanset ).The corresponding argument shall be a pointer to the initialcharacter of an array large enough to accept the sequence and a terminatingNUL character, which will be added automatically.The conversion specifier includes all subsequent characters in the.I formatstring, 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 bracketis a circumflex.RB ( ^ ),in which case the scanset contains all characters that do not appearin 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 nextright bracket character is the matching right bracketthat ends the specification.If a.B -character is in the scanlist and is not the first, nor the secondwhere 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 cMatches 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 characterof an array large enough to accept the sequence.No NUL character is added..TP.B PMatches an implementation-defined set of sequences,which should be the same as the set of sequences that may beproduced by the.B %Pconversion 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 earlierduring the same program execution, the behavior of the.B %Pconversion is undefined..TP.B nNo input is consumed.The corresponding argument shall be a pointer to integer into whichis written the number of characters read from the input stream so farby this call to.IR fscanf .Execution of a.B %ndirective does not increment the assignment count returned at thecompletion of.IR fscanf ..TP.B %Matches a single.BR % ;no conversion or assignment occurs.The complete conversion specification shall be.BR %% ..PD.PPIf a conversion specification is invalid, the behavior is undefined..PPThe conversion specifiers.BR E ,.BR G ,and.B Xare also valid and behave the same as, respectively,.BR e ,.BR g ,and.BR x ..PPIf end-of-file is encountered during input, conversion is terminated.If end-of-file occurs before any characters matching the currentdirective have been read (other than leading white space,where permitted), execution of the current directive terminates withan input failure;otherwise, unless execution of the current directive is terminatedwith a matching failure, execution of the following directive(if any) is terminated with an input failure..PPIf 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 unreadunless matched by a directive.The success of literal matches and suppressed assignments is notdirectly determinable other than via the.B %ndirective..PPThe return value from.I fscanfis the number of input items assigned, which can be fewer thanprovided for, or even zero, in the event of an early matching failure.However, if an input failure occurs before any conversion,.B EOFis returned..SH SOURCE.B /sys/src/libstdio.SH "SEE ALSO".IR fopen (2),.IR fgetc (2).SH BUGSDoes not know about.SM UTF.