| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
enable_extended_FILE_stdio(3C)
posix_spawnattr_getschedparam(3C)
posix_spawnattr_getschedpolicy(3C)
posix_spawnattr_getsigdefault(3C)
posix_spawnattr_getsigignore_np(3C)
posix_spawnattr_getsigmask(3C)
posix_spawnattr_setschedparam(3C)
posix_spawnattr_setschedpolicy(3C)
posix_spawnattr_setsigdefault(3C)
posix_spawnattr_setsigignore_np(3C)
posix_spawnattr_setsigmask(3C)
posix_spawn_file_actions_addclose(3C)
posix_spawn_file_actions_addclosefrom_np(3C)
posix_spawn_file_actions_adddup2(3C)
posix_spawn_file_actions_addopen(3C)
posix_spawn_file_actions_destroy(3C)
posix_spawn_file_actions_init(3C)
pthread_attr_getdetachstate(3C)
pthread_attr_getinheritsched(3C)
pthread_attr_getschedparam(3C)
pthread_attr_getschedpolicy(3C)
pthread_attr_setdetachstate(3C)
pthread_attr_setinheritsched(3C)
pthread_attr_setschedparam(3C)
pthread_attr_setschedpolicy(3C)
pthread_barrierattr_destroy(3C)
pthread_barrierattr_getpshared(3C)
pthread_barrierattr_setpshared(3C)
pthread_condattr_getpshared(3C)
pthread_condattr_setpshared(3C)
pthread_cond_reltimedwait_np(3C)
pthread_key_create_once_np(3C)
pthread_mutexattr_getprioceiling(3C)
pthread_mutexattr_getprotocol(3C)
pthread_mutexattr_getpshared(3C)
pthread_mutexattr_getrobust(3C)
pthread_mutexattr_setprioceiling(3C)
pthread_mutexattr_setprotocol(3C)
pthread_mutexattr_setpshared(3C)
pthread_mutexattr_setrobust(3C)
pthread_mutex_getprioceiling(3C)
pthread_mutex_reltimedlock_np(3C)
pthread_mutex_setprioceiling(3C)
pthread_rwlockattr_destroy(3C)
pthread_rwlockattr_getpshared(3C)
pthread_rwlockattr_setpshared(3C)
pthread_rwlock_reltimedrdlock_np(3C)
pthread_rwlock_reltimedwrlock_np(3C)
pthread_rwlock_timedrdlock(3C)
pthread_rwlock_timedwrlock(3C)
rctlblk_get_enforced_value(3C)
- convert formatted input
#include <stdio.h>intscanf(const char *restrictformat...);
intfscanf(FILE *restrictstream,const char *restrictformat...);
intsscanf(const char *restricts,const char *restrictformat...);
#include <stdarg.h>#include <stdio.h>intvscanf(const char *format,va_listarg);
intvfscanf(FILE *stream,const char *format,va_listarg);
intvsscanf(const char *s,const char *format,va_listarg);
Thescanf() function reads from the standard input streamstdin.
Thefscanf() function reads from the named inputstream.
Thesscanf() function reads from the strings.
Thevscanf(),vfscanf(), andvsscanf() functions are equivalent to thescanf(),fscanf(),andsscanf() functions, respectively, except that instead of being called with avariable number of arguments, they are called with an argument list as definedby the <stdarg.h> header . These functions do not invoke theva_end()macro. Applications using these functions should callva_end(ap) afterwards to clean up.
Each function reads bytes, interprets them according to a format, and storesthe results in its arguments. Each expects, as arguments, a control stringformat described below, and a set ofpointer arguments indicating where theconverted input should be stored. The result is undefined if there are insufficientarguments for the format. If the format is exhausted while arguments remain,the excess arguments are evaluated but are otherwise ignored.
Conversions can be applied to thenth argument after theformat inthe argument list, rather than to the next unused argument. In thiscase, the conversion character% (see below) is replaced by the sequence%n$, wheren is a decimal integer in the range [1,NL_ARGMAX].This feature provides for the definition of format strings that select argumentsin an order appropriate to specific languages. In format strings containing the%n$ form of conversion specifications, it is unspecified whether numbered arguments inthe argument list can be referenced from the format string more thanonce.
Theformat can contain either form of a conversion specification, that is,% or%n$, but the two forms cannot normally be mixed withina singleformat string. The only exception to this is that%% or%* can be mixed with the%n$ form.
Thescanf() function in all its forms allows for detection of alanguage-dependent radix character in the input string. The radix character isdefined in the program's locale (categoryLC_NUMERIC). In the POSIX locale, orin a locale where the radix character is not defined, the radix characterdefaults to a period (.).
The format is a character string, beginning and ending in its initialshift state, if any, composed of zero or more directives. Each directiveis composed of one of the following:
one or morewhite-space characters (space, tab, newline, vertical-tab or form-feed characters);
anordinary character (neither% nor a white-space character); or
aconversion specification.
Each conversion specification is introduced by the character% or the charactersequence%n$, after which the following appear in sequence:
An optional assignment-suppressing character*.
An optional non-zero decimal integer that specifies the maximum field width.
An option length modifier that specifies the size of the receiving object.
A conversion specifier character that specifies the type of conversion to be applied. The valid conversion characters are described below.
Thescanf() functions execute each directive of the format in turn. If a directive fails, as detailed below, the function returns. Failuresare described as input failures (due to the unavailability of input bytes)or matching failures (due to inappropriate input).
A directive composed of one or more white-space characters is executed byreading input until no more valid input can be read, or upto the first byte which is not a white-space character which remainsunread.
A directive that is an ordinary character is executed as follows. Thenext byte is read from the input and compared with the bytethat comprises the directive; if the comparison shows that they are notequivalent, the directive fails, and the differing and subsequent bytes remain unread.
A directive that is a conversion specification defines a set of matchinginput sequences, as described below for each conversion character. A conversion specificationis executed in the following steps:
Input white-space characters (as specified byisspace(3C)) are skipped, unless the conversionspecification includes a[,c,C, orn conversion character.
An item is read from the input unless the conversion specification includesann conversion character. The length of the item read is limitedto any specified maximum field width, which is interpreted in either charactersor bytes depending on the conversion character. In Solaris default mode, the inputitem is defined as the longest sequence of input bytes that formsa matching sequence. In some cases,scanf() might need to read severalextra characters beyond the end of the input item to find theend of a matching sequence. In C99/SUSv3 mode, the input item is definedas the longest sequence of input bytes that is, or is aprefix of, a matching sequence. With this definition,scanf() need only readat most one character beyond the end of the input item. Therefore,in C99/SUSv3 mode, some sequences that are acceptable tostrtod(3C),strtol(3C), and similarfunctions are unacceptable toscanf(). In either mode,scanf() attempts to pushback any excess bytes read usingungetc(3C). Assuming all such attempts succeed,the first byte, if any, after the input item remains unread. Ifthe length of the input item is 0, the conversion fails. Thiscondition is a matching failure unless end-of-file, an encoding error, or aread error prevented input from the stream, in which case it is aninput failure.
Except in the case of a% conversion character, the input item(or, in the case of a%n conversion specification, the count ofinput bytes) is converted to a type appropriate to the conversion character.If the input item is not a matching sequence, the execution of theconversion specification fails; this condition is a matching failure. Unless assignment suppressionwas indicated by a*, the result of the conversion is placedin the object pointed to by the first argument following theformatargument that has not already received a conversion result if the conversion specificationis introduced by%, or in thenth argument if introduced bythe character sequence%n$. If this object does not have an appropriate type,or if the result of the conversion cannot be represented in thespace provided, the behavior is undefined.
The length modifiers and their meanings are:
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tosigned char orunsigned char.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer toshort orunsigned short.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tolong orunsigned long; that a followinga,A,e,E,f,F,g, orG conversion specifier applies to an argument with type pointer todouble; or that a followingc,s, or[ conversion specifier applies to an argument with type pointer towchar_t.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tolong long orunsigned long long.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tointmax_t oruintmax_t.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tosize_t or the corresponding signed integer type.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer toptrdiff_t or the correspondingunsigned type.
Specifies that a followinga,A,e,E,f,F,g, orG conversion specifier applies to an argument with type pointer tolong double.
If a length modifier appears with any conversion specifier other than asspecified above, the behavior is undefined.
The following conversion characters are valid:
Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence ofstrtol(3C) with the value 10 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer toint.
Matches an optionally signed integer, whose format is the same as expected for the subject sequence ofstrtol() with 0 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer toint.
Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence ofstrtoul(3C) with the value 8 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer tounsigned int.
Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence ofstrtoul() with the value 10 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer tounsigned int.
Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence ofstrtoul() with the value 16 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer tounsigned int.
Matches an optionally signed floating-point number, infinity, or NaN, whose format is the same as expected for the subject sequence ofstrtod(3C). In the absence of a size modifier, the corresponding argument must be a pointer tofloat. Thee,f, andg specifiers match hexadecimal floating point values only in C99/SUSv3 (seestandards(5)) mode, but thea specifier always matches hexadecimal floating point values.
These conversion specifiers match any subject sequence accepted bystrtod(3C), including the INF, INFINITY, NAN, and NAN(n-char-sequence) forms. The result of the conversion is the same as that of callingstrtod() (orstrtof() orstrtold()) with the matching sequence, including the raising of floating point exceptions and the setting oferrno toERANGE, if applicable.
Matches a sequence of bytes that are not white-space characters. The corresponding argument must be a pointer to the initial byte of an array ofchar,signed char, orunsigned char large enough to accept the sequence and a terminating null character code, which will be added automatically.
If anl (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each character is converted to a wide-character as if by a call to thembrtowc(3C) function, with the conversion state described by anmbstate_t object initialized to zero before the first character is converted. The corresponding argument must be a pointer to an array ofwchar_t large enough to accept the sequence and the terminating null wide-character, which will be added automatically.
Matches a non-empty sequence of characters from a set of expected characters (thescanset). The normal skip over white-space characters is suppressed in this case. The corresponding argument must be a pointer to the initial byte of an array ofchar,signed char, orunsigned char large enough to accept the sequence and a terminating null byte, which will be added automatically.
If anl (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each character in the sequence is converted to a wide-character as if by a call to thembrtowc() function, with the conversion state described by anmbstate_t object initialized to zero before the first character is converted. The corresponding argument must be a pointer to an array ofwchar_t large enough to accept the sequence and the terminating null wide-character, which will be added automatically.
The conversion specification includes all subsequent characters in theformat string up to and including the matching right square bracket (]). The characters between the square brackets (thescanlist) comprise the scanset, unless the character after the left square bracket is a circumflex (^), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right square bracket. If the conversion specification begins with[ ] or[^], 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– is in the scanlist and is not the first character, nor the second where the first character is a^, nor the last character, it indicates a range of characters to be matched.
Matches a sequence of characters of the number specified by the field width (1 if no field width is present in the conversion specification). The corresponding argument must be a pointer to the initial byte of an array ofchar,signed char, orunsigned char large enough to accept the sequence. No null byte is added. The normal skip over white-space characters is suppressed in this case.
If anl (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each character in the sequence is converted to a wide-character as if by a call to thembrtowc() function, with the conversion state described by anmbstate_t object initialized to zero before the first character is converted. The corresponding argument must be a pointer to an array ofwchar_t large enough to accept the resulting sequence of wide-characters. No null wide-character is added.
Matches the set of sequences that is the same as the set of sequences that is produced by the%p conversion of the correspondingprintf(3C) functions. The corresponding argument must be a pointer to a pointer tovoid. If the input item is a value converted earlier during the same program execution, the pointer that results will compare equal to that value; otherwise the behavior of the%p conversion is undefined.
No input is consumed. The corresponding argument must be a pointer to the integer into which is to be written the number of bytes read from the input so far by this call to thescanf() functions. Execution of a%n conversion specification does not increment the assignment count returned at the completion of execution of the function.
Same aslc.
Same asls.
Matches a single%; no conversion or assignment occurs. The complete conversion specification must be%%.
If a conversion specification is invalid, the behavior is undefined.
The conversion charactersA,E,F,G, andX are also validand behave the same as, respectively,a,e,f,g, andx.
If end-of-file is encountered during input, conversion is terminated. If end-of-file occursbefore any bytes matching the current conversion specification (except for%n) havebeen read (other than leading white-space characters, where permitted), execution of thecurrent conversion specification terminates with an input failure. Otherwise, unless execution ofthe current conversion specification is terminated with a matching failure, execution ofthe following conversion specification (if any) is terminated with an input failure.
Reaching the end of the string insscanf() is equivalent to encounteringend-of-file forfscanf().
If conversion terminates on a conflicting input, the offending input is leftunread in the input. Any trailing white space (including newline characters) isleft unread unless matched by a conversion specification. The success of literalmatches and suppressed assignments is only directly determinable via the%n conversion specification.
Thefscanf() andscanf() functions may mark thest_atime field of thefile associated withstream for update. Thest_atime field will be markedfor update by the first successful execution offgetc(3C),fgets(3C),fread(3C),fscanf(),getc(3C),getdelim(3C),getline(3C),getchar(3C),gets(3C), orscanf() usingstream that returns data notsupplied by a prior call toungetc(3C).
Upon successful completion, these functions return the number of successfully matched andassigned input items; this number can be 0 in the event ofan early matching failure. If the input ends before the firstmatching failure or conversion,EOF is returned. If a read error occursthe error indicator for the stream is set,EOF is returned, anderrno is set to indicate the error.
For the conditions under which thescanf() functions will fail and mayfail, refer tofgetc(3C) orfgetwc(3C).
In addition,fscanf() may fail if:
Input byte sequence does not form a valid character.
There are insufficient arguments.
If the application calling thescanf() functions has any objects of typewint_t orwchar_t, it must also include the header<wchar.h> to havethese objects defined.
Example 1 The call:
int i, n; float x; char name[50];n = scanf("%d%f%s", &i, &x, name)with the input line:
25 54.32E–1 Hamster
will assign ton the value 3, toi the value 25,tox the value 5.432, andname will contain the string Hamster.
Example 2 The call:
int i; float x; char name[50];(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);with input:
56789 0123 56a72
will assign 56 toi, 789.0 tox, skip 0123, and placethe string 56\0 inname. The next call togetchar(3C) will returnthe charactera.
Seeattributes(5) for descriptions of the following attributes:
|
fgetc(3C),fgets(3C),fgetwc(3C),fread(3C),getdelim(3C),getline(3C),isspace(3C),printf(3C),setlocale(3C),strtod(3C),strtol(3C),strtoul(3C),wcrtomb(3C),ungetc(3C),attributes(5),standards(5)
The behavior of the conversion specifier “%%” has changed for all ofthe functions described on this manual page. Previously the “%%” specifier accepteda “%” character from input only if there were no preceding whitespacecharacters. The new behavior accepts “%” even if there are preceding whitespacecharacters. This new behavior now aligns with the description on this manualpage and in various standards. If the old behavior is desired, theconversion specification “%*[%]” can be used.
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |