diff options
Diffstat (limited to 'man3p/wscanf.3p')
| -rw-r--r-- | man3p/wscanf.3p | 517 |
1 files changed, 517 insertions, 0 deletions
diff --git a/man3p/wscanf.3p b/man3p/wscanf.3p new file mode 100644 index 000000000..322d28c53 --- /dev/null +++ b/man3p/wscanf.3p @@ -0,0 +1,517 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FWSCANF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fwscanf +.SH NAME +fwscanf, swscanf, wscanf \- convert formatted wide-character input +.SH SYNOPSIS +.LP +\fB#include <stdio.h> +.br +#include <wchar.h> +.br +.sp +int fwscanf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP +\fIformat\fP\fB, ... ); +.br +int swscanf(const wchar_t *restrict\fP \fIws\fP\fB, +.br +\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, ... ); +.br +int wscanf(const wchar_t *restrict\fP \fIformat\fP\fB, ... ); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfwscanf\fP() function shall read from the named input \fIstream\fP. +The \fIwscanf\fP() function shall read from the +standard input stream \fIstdin\fP. The \fIswscanf\fP() function shall +read from the wide-character string \fIws\fP. Each +function reads wide characters, interprets them according to a format, +and stores the results in its arguments. Each expects, as +arguments, a control wide-character string \fIformat\fP described +below, and a set of \fIpointer\fP arguments indicating where +the converted input should be stored. The result is undefined if there +are insufficient arguments for the format. If the +\fIformat\fP is exhausted while arguments remain, the excess arguments +are evaluated but are otherwise ignored. +.LP +Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP +in the argument list, rather than to the next unused +argument. In this case, the conversion specifier wide character \fB%\fP +(see below) is replaced by the sequence \fB"%n$"\fP , +where \fIn\fP is a decimal integer in the range [1,{NL_ARGMAX}]. This +feature provides for the definition of \fIformat\fP +wide-character strings that select arguments in an order appropriate +to specific languages. In \fIformat\fP wide-character strings +containing the \fB"%\fP\fIn\fP\fB$"\fP form of conversion specifications, +it is unspecified whether numbered arguments in +the argument list can be referenced from the \fIformat\fP wide-character +string more than once. +.LP +The \fIformat\fP can contain either form of a conversion specification-that +is, \fB%\fP or \fB"%\fP\fIn\fP\fB$"\fP- +but the two forms cannot normally be mixed within a single \fIformat\fP +wide-character string. The only exception to this is that +\fB%%\fP or \fB%*\fP can be mixed with the \fB"%\fP\fIn\fP\fB$"\fP +form. When numbered argument specifications are +used, specifying the \fIN\fPth argument requires that all the leading +arguments, from the first to the ( \fIN\fP-1)th, are +pointers. +.LP +The +\fIfwscanf\fP() function in all its forms allows for detection of +a language-dependent radix character in the input string, +encoded as a wide-character value. The radix character is defined +in the program's locale (category \fILC_NUMERIC ).\fP In the +POSIX locale, or in a locale where the radix character is not defined, +the radix character shall default to a period ( \fB'.'\fP +). +.LP +The \fIformat\fP is a wide-character string composed of zero or more +directives. Each directive is composed of one of the +following: one or more white-space wide characters ( <space>s, <tab>s, +<newline>s, <vertical-tab>s, or +<form-feed>s); an ordinary wide character (neither \fB'%'\fP nor a +white-space character); or a conversion specification. +Each conversion specification is introduced by a \fB'%'\fP \ or +the sequence \fB"%\fP\fIn\fP\fB$"\fP after which the following appear +in sequence: +.IP " *" 3 +An optional assignment-suppressing character \fB'*'\fP . +.LP +.IP " *" 3 +An optional non-zero decimal integer that specifies the maximum field +width. +.LP +.IP " *" 3 +An optional length modifier that specifies the size of the receiving +object. +.LP +.IP " *" 3 +A conversion specifier wide character that specifies the type of conversion +to be applied. The valid conversion specifiers are +described below. +.LP +.LP +The \fIfwscanf\fP() functions shall execute each directive of the +format in turn. If a directive fails, as detailed below, the +function shall return. Failures are described as input failures (due +to the unavailability of input bytes) or matching failures +(due to inappropriate input). +.LP +A directive composed of one or more white-space wide characters is +executed by reading input until no more valid input can be +read, or up to the first wide character which is not a white-space +wide character, which remains unread. +.LP +A directive that is an ordinary wide character shall be executed as +follows. The next wide character is read from the input and +compared with the wide character that comprises the directive; if +the comparison shows that they are not equivalent, the directive +shall fail, and the differing and subsequent wide characters remain +unread. Similarly, if end-of-file, an encoding error, or a read +error prevents a wide character from being read, the directive shall +fail. +.LP +A directive that is a conversion specification defines a set of matching +input sequences, as described below for each conversion +wide character. A conversion specification is executed in the following +steps. +.LP +Input white-space wide characters (as specified by \fIiswspace\fP() +) shall be skipped, unless the +conversion specification includes a \fB[\fP , \fBc\fP , or \fBn\fP +conversion specifier. +.LP +An item shall be read from the input, unless the conversion specification +includes an \fBn\fP conversion specifier wide +character. An input item is defined as the longest sequence of input +wide characters, not exceeding any specified field width, +which is an initial subsequence of a matching sequence. The first +wide character, if any, after the input item shall remain unread. +If the length of the input item is zero, the execution of the conversion +specification shall fail; this condition is a matching +failure, unless end-of-file, an encoding error, or a read error prevented +input from the stream, in which case it is an input +failure. +.LP +Except in the case of a \fB%\fP conversion specifier, the input item +(or, in the case of a \fB%n\fP conversion +specification, the count of input wide characters) shall be converted +to a type appropriate to the conversion wide character. If +the input item is not a matching sequence, the execution of the conversion +specification shall fail; this condition is a matching +failure. Unless assignment suppression was indicated by a \fB'*'\fP +, the result of the conversion shall be placed in the object +pointed to by the first argument following the \fIformat\fP argument +that has not already received a conversion result if the +conversion specification is introduced by \fB%\fP , \ or in the +\fIn\fPth argument if introduced by the wide-character +sequence \fB"%\fP\fIn\fP\fB$"\fP. 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. +.LP +The length modifiers and their meanings are: +.TP 7 +\fBhh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBsigned +char\fP or \fBunsigned char\fP. +.TP 7 +\fBh\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBshort\fP +or \fBunsigned short\fP. +.TP 7 +\fBl\fP\ (ell) +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBlong\fP +or \fBunsigned long\fP; that a following \fBa\fP , +\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP +conversion specifier applies to an +argument with type pointer to \fBdouble\fP; or that a following \fBc\fP +, \fBs\fP , or \fB[\fP conversion specifier +applies to an argument with type pointer to \fBwchar_t\fP. +.TP 7 +\fBll\fP\ (ell-ell) +.sp +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP conversion +specifier applies to an argument with type pointer to \fBlong long\fP +or \fBunsigned long long\fP. +.TP 7 +\fBj\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBintmax_t\fP +or \fBuintmax_t\fP. +.TP 7 +\fBz\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBsize_t\fP +or the corresponding signed integer type. +.TP 7 +\fBt\fP +Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , +\fBx\fP , \fBX\fP , or \fBn\fP +conversion specifier applies to an argument with type pointer to \fBptrdiff_t\fP +or the corresponding \fBunsigned\fP type. +.TP 7 +\fBL\fP +Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , +\fBf\fP , \fBF\fP , \fBg\fP , or +\fBG\fP conversion specifier applies to an argument with type pointer +to \fBlong double\fP. +.sp +.LP +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.LP +The following conversion specifier wide characters are valid: +.TP 7 +\fBd\fP +Matches an optionally signed decimal integer, whose format is the +same as expected for the subject sequence of \fIwcstol\fP() with the +value 10 for the \fIbase\fP argument. In the absence of a size modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBint\fP. +.TP 7 +\fBi\fP +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of \fIwcstol\fP() with 0 for the +\fIbase\fP argument. In the absence of a size modifier, the +application shall ensure that the corresponding argument is a pointer +to \fBint\fP. +.TP 7 +\fBo\fP +Matches an optionally signed octal integer, whose format is the same +as expected for the subject sequence of \fIwcstoul\fP() with the value +8 for the \fIbase\fP argument. In the absence of a size modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBu\fP +Matches an optionally signed decimal integer, whose format is the +same as expected for the subject sequence of \fIwcstoul\fP() with +the value 10 for the \fIbase\fP argument. In the absence of a size +modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBx\fP +Matches an optionally signed hexadecimal integer, whose format is +the same as expected for the subject sequence of \fIwcstoul\fP() with +the value 16 for the \fIbase\fP argument. In the absence of a size +modifier, +the application shall ensure that the corresponding argument is a +pointer to \fBunsigned\fP. +.TP 7 +\fBa\fP,\ \fBe\fP,\ \fBf\fP,\ \fBg\fP +.sp +Matches an optionally signed floating-point number, infinity, or NaN +whose format is the same as expected for the subject sequence +of \fIwcstod\fP(). In the absence of a size modifier, the application +shall ensure that the +corresponding argument is a pointer to \fBfloat\fP. +.LP +If the \fIfwprintf\fP() family of functions generates character string +representations +for infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754-1985, the +\fIfwscanf\fP() family of functions shall recognize them as input. +.TP 7 +\fBs\fP +Matches a sequence of non white-space wide characters. If no \fBl\fP +(ell) qualifier is present, characters from the input +field shall be converted as if by repeated calls to the \fIwcrtomb\fP() +function, with the +conversion state described by an \fBmbstate_t\fP object initialized +to zero before the first wide character is converted. The +application shall ensure that the corresponding argument is a pointer +to a character array large enough to accept the sequence and +the terminating null character, which shall be added automatically. +.LP +Otherwise, the application shall ensure that the corresponding argument +is a pointer to an array of \fBwchar_t\fP large enough +to accept the sequence and the terminating null wide character, which +shall be added automatically. +.TP 7 +\fB[\fP +Matches a non-empty sequence of wide characters from a set of expected +wide characters (the \fIscanset\fP). If no \fBl\fP +(ell) qualifier is present, wide characters from the input field shall +be converted as if by repeated calls to the \fIwcrtomb\fP() function, +with the conversion state described by an \fBmbstate_t\fP object +initialized to zero before the first wide character is converted. +The application shall ensure that the corresponding argument is a +pointer to a character array large enough to accept the sequence and +the terminating null character, which shall be added +automatically. +.LP +If an \fBl\fP (ell) qualifier is present, the application shall ensure +that the corresponding argument is a pointer to an +array of \fBwchar_t\fP large enough to accept the sequence and the +terminating null wide character, which shall be added +automatically. +.LP +The conversion specification includes all subsequent wide characters +in the \fIformat\fP string up to and including the +matching right square bracket ( \fB']'\fP ). The wide characters between +the square brackets (the \fIscanlist\fP) comprise the +scanset, unless the wide character after the left square bracket is +a circumflex ( \fB'^'\fP ), in which case the scanset +contains all wide characters that do not appear in the scanlist between +the circumflex and the right square bracket. If the +conversion specification begins with \fB"[]"\fP or \fB"[^]"\fP , the +right square bracket is included in the scanlist and the +next right square bracket is the matching right square bracket that +ends the conversion specification; otherwise, the first right +square bracket is the one that ends the conversion specification. +If a \fB'-'\fP is in the scanlist and is not the first wide +character, nor the second where the first wide character is a \fB'^'\fP +, nor the last wide character, the behavior is +implementation-defined. +.TP 7 +\fBc\fP +Matches a sequence of wide characters of exactly the number specified +by the field width (1 if no field width is present in the +conversion specification). +.LP +If no \fBl\fP (ell) length modifier is present, characters from the +input field shall be converted as if by repeated calls to +the \fIwcrtomb\fP() function, with the conversion state described +by an \fBmbstate_t\fP +object initialized to zero before the first wide character is converted. +The corresponding argument shall be a pointer to the +initial element of a character array large enough to accept the sequence. +No null character is added. +.LP +If an \fBl\fP (ell) length modifier is present, the corresponding +argument shall be a pointer to the initial element of an +array of \fBwchar_t\fP large enough to accept the sequence. No null +wide character is added. +.LP +Otherwise, the application shall ensure that the corresponding argument +is a pointer to an array of \fBwchar_t\fP large enough +to accept the sequence. No null wide character is added. +.TP 7 +\fBp\fP +Matches an implementation-defined set of sequences, which shall be +the same as the set of sequences that is produced by the +\fB%p\fP conversion specification of the corresponding \fIfwprintf\fP() +functions. The +application shall ensure that the corresponding argument is a pointer +to a pointer to \fBvoid\fP. The interpretation of the input +item is implementation-defined. If the input item is a value converted +earlier during the same program execution, the pointer that +results shall compare equal to that value; otherwise, the behavior +of the \fB%p\fP conversion is undefined. +.TP 7 +\fBn\fP +No input is consumed. The application shall ensure that the corresponding +argument is a pointer to the integer into which is to +be written the number of wide characters read from the input so far +by this call to the \fIfwscanf\fP() functions. Execution of a +\fB%n\fP conversion specification shall not increment the assignment +count returned at the completion of execution of the +function. No argument shall be converted, but one shall be consumed. +If the conversion specification includes an +assignment-suppressing wide character or a field width, the behavior +is undefined. +.TP 7 +\fBC\fP +Equivalent to \fBlc\fP . +.TP 7 +\fBS\fP +Equivalent to \fBls\fP . +.TP 7 +\fB%\fP +Matches a single \fB'%'\fP wide character; no conversion or assignment +shall occur. The complete conversion specification +shall be \fB%%\fP . +.sp +.LP +If a conversion specification is invalid, the behavior is undefined. +.LP +The conversion specifiers \fBA\fP , \fBE\fP , \fBF\fP , \fBG\fP , +and \fBX\fP are also valid and shall be +equivalent to, respectively, \fBa\fP , \fBe\fP , \fBf\fP , \fBg\fP +, and \fBx\fP . +.LP +If end-of-file is encountered during input, conversion is terminated. +If end-of-file occurs before any wide characters matching +the current conversion specification (except for \fB%n\fP ) have been +read (other than leading white-space, where permitted), +execution of the current conversion specification shall terminate +with an input failure. Otherwise, unless execution of the current +conversion specification is terminated with a matching failure, execution +of the following conversion specification (if any) shall +be terminated with an input failure. +.LP +Reaching the end of the string in \fIswscanf\fP() shall be equivalent +to encountering end-of-file for \fIfwscanf\fP(). +.LP +If conversion terminates on a conflicting input, the offending input +shall be left unread in the input. Any trailing white space +(including <newline>) shall be left unread unless matched by a conversion +specification. The success of literal matches and +suppressed assignments is only directly determinable via the \fB%n\fP +conversion specification. +.LP +The +\fIfwscanf\fP() and \fIwscanf\fP() functions may mark the \fIst_atime\fP +field of the file associated with \fIstream\fP for +update. The \fIst_atime\fP field shall be marked for update by the +first successful execution of \fIfgetc\fP(), \fIfgetwc\fP(), \fIfgets\fP(), +\fIfgetws\fP(), \fIfread\fP(), \fIgetc\fP(), \fIgetwc\fP(), \fIgetchar\fP(), +\fIgetwchar\fP(), \fIgets\fP(), \fIfscanf\fP(), or \fIfwscanf\fP() +using \fIstream\fP that returns data not supplied by a prior +call to \fIungetc\fP(). +.SH RETURN VALUE +.LP +Upon successful completion, these functions shall return the number +of successfully matched and assigned input items; this +number can be zero in the event of an early matching failure. If the +input ends before the first matching failure or conversion, +EOF shall be returned. If a read error occurs, the error indicator +for the stream is set, EOF shall be returned, \ and +\fIerrno\fP shall be set to indicate the error. +.SH ERRORS +.LP +For the conditions under which the \fIfwscanf\fP() functions shall +fail and may fail, refer to \fIfgetwc\fP() . +.LP +In addition, \fIfwscanf\fP() may fail if: +.TP 7 +.B EILSEQ +Input byte sequence does not form a valid character. +.TP 7 +.B EINVAL +There are insufficient arguments. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The call: +.sp +.RS +.nf + +\fBint i, n; float x; char name[50]; +n = wscanf(L"%d%f%s", &i, &x, name); +\fP +.fi +.RE +.LP +with the input line: +.sp +.RS +.nf + +\fB25 54.32E-1 Hamster +\fP +.fi +.RE +.LP +assigns to \fIn\fP the value 3, to \fIi\fP the value 25, to \fIx\fP +the value 5.432, and \fIname\fP contains the string +\fB"Hamster"\fP . +.LP +The call: +.sp +.RS +.nf + +\fBint i; float x; char name[50]; +(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); +\fP +.fi +.RE +.LP +with input: +.sp +.RS +.nf + +\fB56789 0123 56a72 +\fP +.fi +.RE +.LP +assigns 56 to \fIi\fP, 789.0 to \fIx\fP, skips 0123, and places the +string \fB"56\\0"\fP in \fIname\fP. The next call to \fIgetchar\fP() +shall return the character \fB'a'\fP . +.SH APPLICATION USAGE +.LP +In format strings containing the \fB'%'\fP form of conversion specifications, +each argument in the argument list is used +exactly once. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIgetwc\fP() , \fIfwprintf\fP() , \fIsetlocale\fP() , \fIwcstod\fP() +, \fIwcstol\fP() , +\fIwcstoul\fP() , \fIwcrtomb\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI<langinfo.h>\fP, \fI<stdio.h>\fP, +\fI<wchar.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |