VxWorks Reference Manual : Libraries
ansiStdio - ANSI stdio documentation
clearerr( ) - clear end-of-file and error flags for a stream (ANSI)
fclose( ) - close a stream (ANSI)
fdopen( ) - open a file specified by a file descriptor (POSIX)
feof( ) - test the end-of-file indicator for a stream (ANSI)
ferror( ) - test the error indicator for a file pointer (ANSI)
fflush( ) - flush a stream (ANSI)
fgetc( ) - return the next character from a stream (ANSI)
fgetpos( ) - store the current value of the file position indicator for a stream (ANSI)
fgets( ) - read a specified number of characters from a stream (ANSI)
fileno( ) - return the file descriptor for a stream (POSIX)
fopen( ) - open a file specified by name (ANSI)
fprintf( ) - write a formatted string to a stream (ANSI)
fputc( ) - write a character to a stream (ANSI)
fputs( ) - write a string to a stream (ANSI)
fread( ) - read data into an array (ANSI)
freopen( ) - open a file specified by name (ANSI)
fscanf( ) - read and convert characters from a stream (ANSI)
fseek( ) - set the file position indicator for a stream (ANSI)
fsetpos( ) - set the file position indicator for a stream (ANSI)
ftell( ) - return the current value of the file position indicator for a stream (ANSI)
fwrite( ) - write from a specified array (ANSI)
getc( ) - return the next character from a stream (ANSI)
getchar( ) - return the next character from the standard input stream (ANSI)
gets( ) - read characters from the standard input stream (ANSI)
getw( ) - read the next word (32-bit integer) from a stream
perror( ) - map an error number in errno to an error message (ANSI)
putc( ) - write a character to a stream (ANSI)
putchar( ) - write a character to the standard output stream (ANSI)
puts( ) - write a string to the standard output stream (ANSI)
putw( ) - write a word (32-bit integer) to a stream
rewind( ) - set the file position indicator to the beginning of a file (ANSI)
scanf( ) - read and convert characters from the standard input stream (ANSI)
setbuf( ) - specify the buffering for a stream (ANSI)
setbuffer( ) - specify buffering for a stream
setlinebuf( ) - set line buffering for standard output or standard error
setvbuf( ) - specify buffering for a stream (ANSI)
stdioInit( ) - initialize standard I/O support
stdioFp( ) - return the standard input/output/error FILE of the current task
stdioShowInit( ) - initialize the standard I/O show facility
stdioShow( ) - display file pointer internals
tmpfile( ) - create a temporary binary file (Unimplemented) (ANSI)
tmpnam( ) - generate a temporary file name (ANSI)
ungetc( ) - push a character back into an input stream (ANSI)
vfprintf( ) - write a formatted string to a stream (ANSI)
The header stdio.h declares three types, several macros, and many functions for performing input and output.
The types declared are size_t and:.SS
- FILE
- object type capable of recording all the information needed to control a stream, including its file position indicator, a pointer to its associated buffer (if any), an error indicator that records whether a read/write error has occurred, and an end-of-file indicator that records whether the end of the file has been reached.
- fpos_t
- object type capable of recording all the information needed to specify uniquely every position within a file.
Macros The macros are NULL and:
- _IOFBF, _IOLBF, _IONBF
- expand to integral constant expressions with distinct values, suitable for use as the third argument to setvbuf( ).
- BUFSIZ
- expands to an integral constant expression that is the size of the buffer used by setbuf( ).
- EOF
- expands to a negative integral constant expression that is returned by several functions to indicate end-of-file, that is, no more input from a stream.
- FOPEN_MAX
- expands to an integral constant expression that is the minimum number of the files that the system guarantees can be open simultaneously.
- FILENAME_MAX
- expands to an integral constant expression that is the size needed for an array of char large enough to hold the longest file name string that can be used.
- L_tmpnam
- expands to an integral constant expression that is the size needed for an array of char large enough to hold a temporary file name string generated by tmpnam( ).
- SEEK_CUR, SEEK_END, SEEK_SET
- expand to integral constant expressions with distinct values suitable for use as the third argument to fseek( ).
- TMP_MAX
- expands to an integral constant expression that is the minimum number of file names generated by tmpnam( ) that will be unique.
- `stderr, stdin, stdout'
- expressions of type "pointer to FILE" that point to the FILE objects associated, respectively, with the standard error, input, and output streams.
Input and output, whether to or from physical devices such as terminals and tape drives, or whether to or from files supported on structured storage devices, are mapped into logical data streams, whose properties are more uniform than their various inputs and outputs. Two forms of mapping are supported: for text streams and for binary streams.
A text stream is an ordered sequence of characters composed into lines, each line consisting of zero or more characters plus a terminating new-line character. Characters may have to be added, altered, or deleted on input and output to conform to differing conventions for representing text in the host environment. Thus, there is no need for a one-to-one correspondence between the characters in a stream and those in the external representation. Data read in from a text stream will necessarily compare equal to the data that were earlier written out to that stream only if: the data consists only of printable characters and the control characters horizontal tab and new-line; no new-line character is immediately preceded by space characters; and the last character is a new-line character. Space characters are written out immediately before a new-line character appears.
A binary stream is an ordered sequence of characters that can transparently record internal data. Data read in from a binary stream should compare equal to the data that was earlier written out to that stream, under the same implementation. However, such a stream may have a number of null characters appended to the end of the stream.
VxWorks supports text files with lines containing at least 254 characters, including the terminating new-line character. The value of the macro BUFSIZ is 1024.
A stream is associated with an external file (which may be a physical device) by opening a file, which may involve creating a new file. Creating an existing file causes its former contents to be discarded, if necessary. If a file can support positioning requests (such as a disk file, as opposed to a terminal), then a file position indicator associated with the stream is positioned at the start (character number zero) of the file. The file position indicator is maintained by subsequent reads, writes, and positioning requests, to facilitate an orderly progression through the file. All input takes place as if characters were read by successive calls to fgetc( ); all output takes place as if characters were written by successive calls to fputc( ).
Binary files are not truncated, except as defined in fopen( ) documentation.
When a stream is unbuffered, characters are intended to appear from the source or at the destination as soon as possible. Otherwise characters may be accumulated and transmitted to or from the host environment as a block. When a stream is fully buffered, characters are intended to be transmitted to or from the host environment as a block when the buffer is filled. When a stream is line buffered, characters are intended to be transmitted to or from the host environment as a block when a new-line character is encountered. Furthermore, characters are intended to be transmitted as a block to the host environment when a buffer is filled, when input is requested on an unbuffered stream, or when input is requested on a line-buffered stream that requires the transmission of characters from the host environment. VxWorks supports these characteristics via the setbuf( ) and setvbuf( ) functions.
A file may be disassociated from a controlling stream by closing the file. Output streams are flushed (any unwritten buffer contents are transmitted to the host environment) before the stream is disassociated from the file. The value of a pointer to a FILE object is indeterminate after the associated file is closed (including the standard text streams).
The file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it can be repositioned at its start).
ANSI specifies that if the main function returns to its original caller or if exit( ) is called, all open files are closed (and hence all output streams are flushed) before program termination. This does not happen in VxWorks. The exit( ) function does not close all files opened for that task. A file opened by one task may be used and closed by another. Unlike in UNIX, when a VxWorks task exits, it is the responsibility of the task to fclose( ) its file pointers, except stdin, stdout, and stderr. If a task is to be terminated asynchronously, use kill( ) and arrange for a signal handler to clean up.
The address of the FILE object used to control a stream may be significant; a copy of a FILE object may not necessarily serve in place of the original.
At program startup, three text streams are predefined and need not be opened explicitly: standard input (for reading conventional input), standard output (for writing conventional output), and standard error (for writing diagnostic output). When opened, the standard error stream is not fully buffered; the standard input and standard output streams are fully buffered if and only if the stream can be determined not to refer to an interactive device.
Functions that open additional (non-temporary) files require a file name, which is a string. VxWorks allows the same file to be open multiple times simultaneously. It is up to the user to maintain synchronization between different tasks accessing the same file.
Several routines normally considered part of standard I/O -- printf( ), sprintf( ), vprintf( ), vsprintf( ), and sscanf( ) -- are not implemented as part of the buffered standard I/O library; they are instead implemented in fioLib. They do not use the standard I/O buffering scheme. They are self-contained, formatted, but unbuffered I/O functions. This allows a limited amount of formatted I/O to be achieved without the overhead of the standard I/O library.
ansiStdio, fioLib, American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)
clearerr( ) - clear end-of-file and error flags for a stream (ANSI)
void clearerr ( FILE * fp /* stream to clear EOF and ERROR flags for */ )
This routine clears the end-of-file and error flags for a specified stream.
stdio.h
N/A
fclose( ) - close a stream (ANSI)
int fclose ( FILE * fp /* stream to close */ )
This routine flushes a specified stream and closes the associated file. Any unwritten buffered data is delivered to the host environment to be written to the file; any unread buffered data is discarded. The stream is disassociated from the file. If the associated buffer was allocated automatically, it is deallocated.
stdio.h
Zero if the stream is closed successfully, or EOF if errors occur.
EBADF
fdopen( ) - open a file specified by a file descriptor (POSIX)
FILE * fdopen ( int fd, /* file descriptor */ const char * mode /* mode to open with */ )
This routine opens the file specified by the file descriptor fd and associates a stream with it. The mode argument is used just as in the fopen( ) function.
stdio.h
A pointer to a stream, or a null pointer if an error occurs, with errno set to indicate the error.
EINVAL
ansiStdio, fopen( ), freopen( ), .br Information Technology - POSIX - Part 1: System API [C Language], IEEE Std 1003.1
feof( ) - test the end-of-file indicator for a stream (ANSI)
int feof ( FILE * fp /* stream to test */ )
This routine tests the end-of-file indicator for a specified stream.
stdio.h
Non-zero if the end-of-file indicator is set for fp.
ferror( ) - test the error indicator for a file pointer (ANSI)
int ferror ( FILE * fp /* stream to test */ )
This routine tests the error indicator for the stream pointed to by fp.
stdio.h
Non-zero if the error indicator is set for fp.
fflush( ) - flush a stream (ANSI)
int fflush ( FILE * fp /* stream to flush */ )
This routine writes to the file any unwritten data for a specified output or update stream for which the most recent operation was not input; for an input stream the behavior is undefined.
ANSI specifies that if fp is a null pointer, fflush( ) performs the flushing action on all streams for which the behavior is defined; however, this is not implemented in VxWorks.
stdio.h
Zero, or EOF if a write error occurs.
EBADF
fgetc( ) - return the next character from a stream (ANSI)
int fgetc ( FILE * fp /* stream to read from */ )
This routine returns the next character (converted to an int) from the specified stream, and advances the file position indicator for the stream.
If the stream is at end-of-file, the end-of-file indicator for the stream is set; if a read error occurs, the error indicator is set.
stdio.h
The next character from the stream, or EOF if the stream is at end-of-file or a read error occurs.
fgetpos( ) - store the current value of the file position indicator for a stream (ANSI)
int fgetpos ( FILE * fp, /* stream */ fpos_t * pos /* where to store position */ )
This routine stores the current value of the file position indicator for a specified stream fp in the object pointed to by pos. The value stored contains unspecified information usable by fsetpos( ) for repositioning the stream to its position at the time fgetpos( ) was called.
stdio.h
Zero, or non-zero if unsuccessful, with errno set to indicate the error.
fgets( ) - read a specified number of characters from a stream (ANSI)
char * fgets ( char * buf, /* where to store characters */ size_t n, /* no. of bytes to read + 1 */ FILE * fp /* stream to read from */ )
This routine stores in the array buf up to n-1 characters from a specified stream. No additional characters are read after a new-line or end-of-line. A null character is written immediately after the last character read into the array.
If end-of-file is encountered and no characters have been read, the contents of the array remain unchanged. If a read error occurs, the array contents are indeterminate.
stdio.h
A pointer to buf, or a null pointer if an error occurs or end-of-file is encountered and no characters have been read.
fileno( ) - return the file descriptor for a stream (POSIX)
int fileno ( FILE * fp /* stream */ )
This routine returns the file descriptor associated with a specified stream.
stdio.h
The file descriptor, or -1 if an error occurs, with errno set to indicate the error.
ansiStdio, .br Information Technology - POSIX - Part 1: System API [C Language], IEEE Std 1003.1
fopen( ) - open a file specified by name (ANSI)
FILE * fopen ( const char * file, /* name of file */ const char * mode /* mode */ )
This routine opens a file whose name is the string pointed to by file and associates a stream with it. The argument mode points to a string beginning with one of the following sequences:
- r
- open text file for reading
- w
- truncate to zero length or create text file for writing
- a
- append; open or create text file for writing at end-of-file
- rb
- open binary file for reading
- wb
- truncate to zero length or create binary file for writing
- ab
- append; open or create binary file for writing at end-of-file
- r+
- open text file for update (reading and writing)
- w+
- truncate to zero length or create text file for update.
- a+
- append; open or create text file for update, writing at end-of-file
- r+b / rb+
- open binary file for update (reading and writing)
- w+b / wb+
- truncate to zero length or create binary file for update
- a+b / ab+
- append; open or create binary file for update, writing at end-of-file
Opening a file with read mode (r as the first character in the mode argument) fails if the file does not exist or cannot be read.
Opening a file with append mode (a as the first character in the mode argument) causes all subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening calls to fseek( ). In some implementations, opening a binary file with append mode (b as the second or third character in the mode argument) may initially position the file position indicator for the stream beyond the last data written, because of null character padding. In VxWorks, whether append mode is supported is device-specific.
When a file is opened with update mode (+ as the second or third character in the mode argument), both input and output may be performed on the associated stream. However, output may not be directly followed by input without an intervening call to fflush( ) or to a file positioning function (fseek( ), fsetpos( ), or rewind( )), and input may not be directly followed by output without an intervening call to a file positioning function, unless the input operation encounters end-of-file. Opening (or creating) a text file with update mode may instead open (or create) a binary stream in some implementations.
When opened, a stream is fully buffered if and only if it can be determined not to refer to an interactive device. The error and end-of-file indicators for the stream are cleared.
stdio.h
A pointer to the object controlling the stream, or a null pointer if the operation fails.
ansiStdio, fdopen( ), freopen( )
fprintf( ) - write a formatted string to a stream (ANSI)
int fprintf ( FILE * fp, /* stream to write to */ const char * fmt /* format string */ )
This routine writes output to a specified stream under control of the string fmt. The string fmt contains ordinary characters, which are written unchanged, plus conversion specifications, which cause the arguments that follow fmt to be converted and printed as part of the formatted string.
The number of arguments for the format is arbitrary, but they must correspond to the conversion specifications in fmt. If there are insufficient arguments, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. The routine returns when the end of the format string is encountered.
The format is a multibyte character sequence, beginning and ending in its initial shift state. The format is composed of zero or more directives: ordinary multibyte characters (not %) that are copied unchanged to the output stream; and conversion specification, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the % character. After the %, the following appear in sequence:
- Zero or more flags (in any order) that modify the meaning of the conversion specification.
- An optional minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces (by default) on the left (or right, if the left adjustment flag, described later, has been given) to the field width. The field width takes the form of an asterisk (*) (described later) or a decimal integer.
- An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point character for e, E, and f conversions, the maximum number of significant digits for the g and G conversions, or the maximum number of characters to be written from a string in the s conversion. The precision takes the form of a period (.) followed either by an asterisk (*) (described later) or by an optional decimal integer; if only the period is specified, the precision is taken as zero. If a precision appears with any other conversion specifier, the behavior is undefined.
- An optional h specifying that a following d, i, o, u, x, and X conversion specifier applies to a short int or unsigned short int argument (the argument will have been promoted according to the integral promotions, and its value converted to short int or unsigned short int before printing); an optional h specifying that a following n conversion specifier applies to a pointer to a short int argument; an optional l (el) specifying that a following d, i, o, u, x, and X conversion specifier applies to a long int or unsigned long int argument; or an optional l specifying that a following n conversion specifier applies to a pointer to a long int argument. If an h or l appears with any other conversion specifier, the behavior is undefined.
ANSI C also specifies an optional L in some of the same contexts as l above, corresponding to a long double argument. However, the current release of the VxWorks libraries does not support long double data; using the optional L gives unpredictable results.
A character that specifies the type of conversion to be applied.
As noted above, a field width, or precision, or both, can be indicated by an asterisk (*). In this case, an int argument supplies the field width or precision. The arguments specifying field width, or precision, or both, should appear (in that order) before the argument (if any) to be converted. A negative field width argument is taken as a - flag followed by a positive field width. A negative precision argument is taken as if the precision were omitted.
The flag characters and their meanings are:
- -
- The result of the conversion will be left-justified within the field. (it will be right-justified if this flag is not specified.)
- +
- The result of a signed conversion will always begin with a plus or minus sign. (It will begin with a sign only when a negative value is converted if this flag is not specified.)
- space
- If the first character of a signed conversion is not a sign, or if a signed conversion results in no characters, a space will be prefixed to the result. If the space and + flags both appear, the space flag will be ignored.
- #
- The result is to be converted to an "alternate form." For o conversion it increases the precision to force the first digit of the result to be a zero. For x (or X) conversion, a non-zero result will have "0x" (or "0X") prefixed to it. For e, E, f, g, and G conversions, the result will always contain a decimal-point character, even if no digits follow it. (Normally, a decimal-point character appears in the result of these conversions only if no digit follows it). For g and G conversions, trailing zeros will not be removed from the result. For other conversions, the behavior is undefined.
- 0
- For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros (following any indication of sign or base) are used to pad to the field width; no space padding is performed. If the 0 and - flags both appear, the 0 flag will be ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag will be ignored. For other conversions, the behavior is undefined.
The conversion specifiers and their meanings are:
- d, i
- The int argument is converted to signed decimal in the style [-]dddd. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it will be expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is no characters.
- o, u, x, X
- The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the letters abcdef are used for x conversion and the letters ABCDEF for X conversion. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it will be expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is no characters.
- f
- The double argument is converted to decimal notation in the style [-]ddd.ddd, where the number of digits after the decimal point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is zero and the # flag is not specified, no decimal-point character appears. If a decimal-point character appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.
- e, E
- The double argument is converted in the style [-]d.ddde+/-dd, where there is one digit before the decimal-point character (which is non-zero if the argument is non-zero) and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero and the # flag is not specified, no decimal-point character appears. The value is rounded to the appropriate number of digits. The E conversion specifier will produce a number with E instead of e introducing the exponent. The exponent always contains at least two digits. If the value is zero, the exponent is zero.
- g, G
- The double argument is converted in style f or e (or in style E in the case of a G conversion specifier), with the precision specifying the number of significant digits. If the precision is zero, it is taken as 1. The style used depends on the value converted; style e (or E) will be used only if the exponent resulting from such a conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional portion of the result; a decimal-point character appears only if it is followed by a digit.
- c
- The int argument is converted to an unsigned char, and the resulting character is written.
- s
- The argument should be a pointer to an array of character type. Characters from the array are written up to (but not including) a terminating null character; if the precision is specified, no more than that many characters are written. If the precision is not specified or is greater than the size of the array, the array will contain a null character.
- p
- The argument should be a pointer to void. The value of the pointer is converted to a sequence of printable characters, in hexadecimal representation (prefixed with "0x").
- n
- The argument should be a pointer to an integer into which the number of characters written to the output stream so far by this call to fprintf( ) is written. No argument is converted.
- %
- A % is written. No argument is converted. The complete conversion specification is %%.
If a conversion specification is invalid, the behavior is undefined.
If any argument is, or points to, a union or an aggregate (except for an array of character type using s conversion, or a pointer using p conversion), the behavior is undefined.
In no case does a non-existent or small field width cause truncation of a field if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.
stdio.h
The number of characters written, or a negative value if an output error occurs.
fputc( ) - write a character to a stream (ANSI)
int fputc ( int c, /* character to write */ FILE * fp /* stream to write to */ )
This routine writes a character c to a specified stream, at the position indicated by the stream's file position indicator (if defined), and advances the indicator appropriately.
If the file cannot support positioning requests, or if the stream was opened in append mode, the character is appended to the output stream.
stdio.h
The character written, or EOF if a write error occurs, with the error indicator set for the stream.
fputs( ) - write a string to a stream (ANSI)
int fputs ( const char * s, /* string */ FILE * fp /* stream to write to */ )
This routine writes the string s, minus the terminating NULL character, to a specified stream.
stdio.h
A non-negative value, or EOF if a write error occurs.
fread( ) - read data into an array (ANSI)
int fread ( void * buf, /* where to copy data */ size_t size, /* element size */ size_t count, /* no. of elements */ FILE * fp /* stream to read from */ )
This routine reads, into the array buf, up to count elements of size size, from a specified stream fp. The file position indicator for the stream (if defined) is advanced by the number of characters successfully read. If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate.
stdio.h
The number of elements successfully read, which may be less than count if a read error or end-of-file is encountered; or zero if size or count is zero, with the contents of the array and the state of the stream remaining unchanged.
freopen( ) - open a file specified by name (ANSI)
FILE * freopen ( const char * file, /* name of file */ const char * mode, /* mode */ FILE * fp /* stream */ )
This routine opens a file whose name is the string pointed to by file and associates it with a specified stream fp. The mode argument is used just as in the fopen( ) function.
This routine first attempts to close any file that is associated with the specified stream. Failure to close the file successfully is ignored. The error and end-of-file indicators for the stream are cleared.
Typically, freopen( ) is used to attach the already-open streams stdin, stdout, and stderr to other files.
stdio.h
The value of fp, or a null pointer if the open operation fails.
fscanf( ) - read and convert characters from a stream (ANSI)
int fscanf ( FILE * fp, /* stream to read from */ char const * fmt /* format string */ )
This routine reads characters from a specified stream, and interprets them according to format specifications in the string fmt, which 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 but are otherwise ignored.
The format is a multibyte character sequence, beginning and ending in its initial shift state. The format is composed of zero or more directives: one or more white-space characters; an ordinary multibyte character (neither % nor a white-space character); or a conversion specification. Each conversion specification is introduced by the % character. After the %, the following appear in sequence:
- An optional assignment-suppressing character *.
- An optional non-zero decimal integer that specifies the maximum field width.
- An optional h or l (el) indicating the size of the receiving object. The conversion specifiers d, i, and n should be preceded by h if the corresponding argument is a pointer to short int rather than a pointer to int, or by l if it is a pointer to long int. Similarly, the conversion specifiers o, u, and x shall be preceded by h if the corresponding argument is a pointer to unsigned short int rather than a pointer to unsigned int, or by l if it is a pointer to unsigned long int. Finally, the conversion specifiers e, f, and g shall be preceded by l if the corresponding argument is a pointer to double rather than a pointer to float. If an h or l appears with any other conversion specifier, the behavior is undefined.
ANSI C also specifies an optional L in some of the same contexts as l above, corresponding to a long double * argument. However, the current release of the VxWorks libraries does not support long double data; using the optional L gives unpredictable results.
A character that specifies the type of conversion to be applied. The valid conversion specifiers are described below.
The fscanf( ) routine executes each directive of the format in turn. If a directive fails, as detailed below, fscanf( ) returns. Failures are described as input failures (due to the unavailability of input characters), or matching failures (due to inappropriate input).
A directive composed of white-space character(s) is executed by reading input up to the first non-white-space character (which remains unread), or until no more characters can be read.
A directive that is an ordinary multibyte character is executed by reading the next characters of the stream. If one of the characters differs from one comprising the directive, the directive fails, and the differing and subsequent characters remain unread.
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:
Input white-space characters (as specified by the isspace( ) function) are skipped, unless the specification includes a [, c, or n specifier.
An input item is read from the stream, unless the specification includes an n specifier. An input item is defined as the longest matching sequence of input characters, unless that exceeds a specified field width, in which case it is the initial subsequence of that length in the 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.
Except in the case of a % specifier, the input item 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 *, the result of the conversion is placed in the object pointed to by the first argument following the fmt 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.
The following conversion specifiers are valid:
- d
- Matches an optionally signed decimal integer whose format is the same as expected for the subject sequence of the strtol( ) function with the value 10 for the base argument. The corresponding argument should be a pointer to int.
- i
- Matches an optionally signed integer, whose format is the same as expected for the subject sequence of the strtol( ) function with the value 0 for the base argument. The corresponding argument should be a pointer to int.
- o
- Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence of the strtoul( ) function with the value 8 for the base argument. The corresponding argument should be a pointer to unsigned int.
- u
- Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the strtoul( ) function with the value 10 for the base argument. The corresponding argument should be a pointer to unsigned int.
- x
- Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence of the strtoul( ) function with the value 16 for the base argument. The corresponding argument should be a pointer to unsigned int.
- e, f, g
- Match an optionally signed floating-point number, whose format is the same as expected for the subject string of the strtod( ) function. The corresponding argument should be a pointer to float.
- s
- Matches a sequence of non-white-space characters. The corresponding argument should be a pointer to the initial character of an array large enough to accept the sequence and a terminating null character, which will be added automatically.
- [
- Matches a non-empty sequence of characters from a set of expected characters (the scanset). The corresponding argument should be a pointer to the initial character of an array large enough to accept the sequence and a terminating null character, which is added automatically. The conversion specifier includes all subsequent character in the format string, up to and including the matching right bracket (]). The characters between the brackets (the scanlist) comprise the scanset, unless the character after the left 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 bracket. If the conversion specifier begins with "[]" or "[^]", the right bracket character is in the scanlist and the next right bracket character is the matching right bracket that ends the specification; otherwise the first right bracket character is the one that ends the specification.
- 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 should be a pointer to the initial character of an array large enough to accept the sequence. No null character is added.
- p
- Matches an implementation-defined set of sequences, which should be the same as the set of sequences that may be produced by the %p conversion of the fprintf( ) function. The corresponding argument should be a pointer to a pointer to void. VxWorks defines its pointer input field to be consistent with pointers written by the fprintf( ) function ("0x" hexadecimal notation). If the input item is a value converted earlier during the same program execution, the pointer that results should compare equal to that value; otherwise the behavior of the %p conversion is undefined.
- n
- No input is consumed. The corresponding argument should be a pointer to int into which the number of characters read from the input stream so far by this call to fscanf( ) is written. Execution of a %n directive does not increment the assignment count returned when fscanf( ) completes execution.
- %
- Matches a single %; no conversion or assignment occurs. The complete conversion specification is %%.
If a conversion specification is invalid, the behavior is undefined.
The conversion specifiers E, G, and X are also valid and behave the same as e, g, and x, respectively.
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.
If conversion terminates on a conflicting input character, the offending input character is left unread in the input stream. Trailing white space (including new-line 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 %n directive.
stdio.h
The number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure; or EOF if an input failure occurs before any conversion.
ansiStdio, scanf( ), sscanf( )
fseek( ) - set the file position indicator for a stream (ANSI)
int fseek ( FILE * fp, /* stream */ long offset, /* offset from whence */ int whence /* position to offset from: SEEK_SET = beginning SEEK_CUR */ /* current position SEEK_END = end-of-file */ )
This routine sets the file position indicator for a specified stream. For a binary stream, the new position, measured in characters from the beginning of the file, is obtained by adding offset to the position specified by whence, whose possible values are:
- SEEK_SET
- the beginning of the file.
- SEEK_CUR
- the current value of the file position indicator.
- SEEK_END
- the end of the file.
A binary stream does not meaningfully support fseek( ) calls with a whence value of SEEK_END.
For a text stream, either offset is zero, or offset is a value returned by an earlier call to ftell( ) on the stream, in which case whence should be SEEK_SET.
A successful call to fseek( ) clears the end-of-file indicator for the stream and undoes any effects of ungetc( ) on the same stream. After an fseek( ) call, the next operation on an update stream can be either input or output.
stdio.h
Non-zero only for a request that cannot be satisfied.
EINVAL
fsetpos( ) - set the file position indicator for a stream (ANSI)
int fsetpos ( FILE * iop, /* stream */ const fpos_t * pos /* position, obtained by fgetpos() */ )
This routine sets the file position indicator for a specified stream iop according to the value of the object pointed to by pos, which is a value obtained from an earlier call to fgetpos( ) on the same stream.
A successful call to fsetpos( ) clears the end-of-file indicator for the stream and undoes any effects of ungetc( ) on the same stream. After an fsetpos( ) call, the next operation on an update stream may be either input or output.
stdio.h
Zero, or non-zero if the call fails, with errno set to indicate the error.
ftell( ) - return the current value of the file position indicator for a stream (ANSI)
long ftell ( FILE * fp /* stream */ )
This routine returns the current value of the file position indicator for a specified stream. For a binary stream, the value is the number of characters from the beginning of the file. For a text stream, the file position indicator contains unspecified information, usable by fseek( ) for returning the file position indicator to its position at the time of the ftell( ) call; the difference between two such return values is not necessary a meaningful measure of the number of characters written or read.
stdio.h
The current value of the file position indicator, or -1L if unsuccessful, with errno set to indicate the error.
fwrite( ) - write from a specified array (ANSI)
int fwrite ( const void * buf, /* where to copy from */ size_t size, /* element size */ size_t count, /* no. of elements */ FILE * fp /* stream to write to */ )
This routine writes, from the array buf, up to count elements whose size is size, to a specified stream. The file position indicator for the stream (if defined) is advanced by the number of characters successfully written. If an error occurs, the resulting value of the file position indicator for the stream is indeterminate.
stdio.h
The number of elements successfully written, which will be less than count only if a write error is encountered.
getc( ) - return the next character from a stream (ANSI)
int getc ( FILE * fp /* input stream */ )
This routine is equivalent to fgetc( ), except that if it is implemented as a macro, it may evaluate fp more than once; thus the argument should never be an expression with side effects.
If the stream is at end-of-file, the end-of-file indicator for the stream is set; if a read error occurs, the error indicator is set.
stdio.h
The next character from the stream, or EOF if the stream is at end-of-file or a read error occurs.
getchar( ) - return the next character from the standard input stream (ANSI)
int getchar (void)
This routine returns the next character from the standard input stream and advances the file position indicator.
It is equivalent to getc( ) with the stream argument stdin.
If the stream is at end-of-file, the end-of-file indicator is set; if a read error occurs, the error indicator is set.
stdio.h
The next character from the standard input stream, or EOF if the stream is at end-of-file or a read error occurs.
gets( ) - read characters from the standard input stream (ANSI)
char * gets ( char * buf /* output array */ )
This routine reads characters from the standard input stream into the array buf until end-of-file is encountered or a new-line is read. Any new-line character is discarded, and a null character is written immediately after the last character read into the array.
If end-of-file is encountered and no characters have been read, the contents of the array remain unchanged. If a read error occurs, the array contents are indeterminate.
stdio.h
A pointer to buf, or a null pointer if (1) end-of-file is encountered and no characters have been read, or (2) there is a read error.
getw( ) - read the next word (32-bit integer) from a stream
int getw ( FILE * fp /* stream to read from */ )
This routine reads the next 32-bit quantity from a specified stream. It returns EOF on end-of-file or an error; however, this is also a valid integer, thus feof( ) and ferror( ) must be used to check for a true end-of-file.
This routine is provided for compatibility with earlier VxWorks releases.
stdio.h
A 32-bit number from the stream, or EOF on either end-of-file or an error.
perror( ) - map an error number in errno to an error message (ANSI)
void perror ( const char * __s /* error string */ )
This routine maps the error number in the integer expression errno to an error message. It writes a sequence of characters to the standard error stream as follows: first (if <__s> is not a null pointer and the character pointed to by <__s> is not the null character), the string pointed to by <__s> followed by a colon (:) and a space; then an appropriate error message string followed by a new-line character. The contents of the error message strings are the same as those returned by strerror( ) with the argument errno.
stdio.h
N/A
putc( ) - write a character to a stream (ANSI)
int putc ( int c, /* character to write */ FILE * fp /* stream to write to */ )
This routine writes a character c to a specified stream, at the position indicated by the stream's file position indicator (if defined), and advances the indicator appropriately.
This routine is equivalent to fputc( ), except that if it is implemented as a macro, it may evaluate fp more than once; thus, the argument should never be an expression with side effects.
stdio.h
The character written, or EOF if a write error occurs, with the error indicator set for the stream.
putchar( ) - write a character to the standard output stream (ANSI)
int putchar ( int c /* character to write */ )
This routine writes a character c to the standard output stream, at the position indicated by the stream's file position indicator (if defined), and advances the indicator appropriately.
This routine is equivalent to putc( ) with a second argument of stdout.
stdio.h
The character written, or EOF if a write error occurs, with the error indicator set for the standard output stream.
puts( ) - write a string to the standard output stream (ANSI)
int puts ( char const * s /* string to write */ )
This routine writes to the standard output stream a specified string s, minus the terminating null character, and appends a new-line character to the output.
stdio.h
A non-negative value, or EOF if a write error occurs.
putw( ) - write a word (32-bit integer) to a stream
int putw ( int w, /* word (32-bit integer) */ FILE * fp /* output stream */ )
This routine appends the 32-bit quantity w to a specified stream.
This routine is provided for compatibility with earlier VxWorks releases.
stdio.h
The value written.
rewind( ) - set the file position indicator to the beginning of a file (ANSI)
void rewind ( FILE * fp /* stream */ )
This routine sets the file position indicator for a specified stream to the beginning of the file.
It is equivalent to:
(void) fseek (fp, 0L, SEEK_SET);except that the error indicator for the stream is cleared.
stdio.h
N/A
scanf( ) - read and convert characters from the standard input stream (ANSI)
int scanf ( char const * fmt /* format string */ )
This routine reads input from the standard input stream under the control of the string fmt. It is equivalent to fscanf( ) with an fp argument of stdin.
stdio.h
The number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure; or EOF if an input failure occurs before any conversion.
ansiStdio, fscanf( ), sscanf( )
setbuf( ) - specify the buffering for a stream (ANSI)
void setbuf ( FILE * fp, /* stream to set buffering for */ char * buf /* buffer to use */ )
Except that it returns no value, this routine is equivalent to setvbuf( ) invoked with the mode _IOFBF (full buffering) and size BUFSIZ, or (if buf is a null pointer), with the mode _IONBF (no buffering).
stdio.h
N/A
setbuffer( ) - specify buffering for a stream
void setbuffer ( FILE * fp, /* stream to set buffering for */ char * buf, /* buffer to use */ int size /* buffer size */ )
This routine specifies a buffer buf to be used for a stream in place of the automatically allocated buffer. If buf is NULL, the stream is unbuffered. This routine should be called only after the stream has been associated with an open file and before any other operation is performed on the stream.
This routine is provided for compatibility with earlier VxWorks releases.
stdio.h
N/A
setlinebuf( ) - set line buffering for standard output or standard error
int setlinebuf ( FILE * fp /* stream - stdout or stderr */ )
This routine changes stdout or stderr streams from block-buffered or unbuffered to line-buffered. Unlike setbuf( ), setbuffer( ), or setvbuf( ), it can be used at any time the stream is active.
A stream can be changed from unbuffered or line-buffered to fully buffered using freopen( ). A stream can be changed from fully buffered or line-buffered to unbuffered using freopen( ) followed by setbuf( ) with a buffer argument of NULL.
This routine is provided for compatibility with earlier VxWorks releases.
stdio.h
OK, or ERROR if fp is not a valid stream.
setvbuf( ) - specify buffering for a stream (ANSI)
int setvbuf ( FILE * fp, /* stream to set buffering for */ char * buf, /* buffer to use (optional) */ int mode, /* _IOFBF = fully buffered _IOLBF = line buffered _IONBF = */ size_t size /* buffer size */ )
This routine sets the buffer size and buffering mode for a specified stream. It should be called only after the stream has been associated with an open file and before any other operation is performed on the stream. The argument mode determines how the stream will be buffered, as follows:
- _IOFBF
- input/output is to be fully buffered.
- _IOLBF
- input/output is to be line buffered.
- _IONBF
- input/output is to be unbuffered.
If buf is not a null pointer, the array it points to may be used instead of a buffer allocated by setvbuf( ). The argument size specifies the size of the array. The contents of the array at any time are indeterminate.
stdio.h
Zero, or non-zero if mode is invalid or the request cannot be honored.
stdioInit( ) - initialize standard I/O support
STATUS stdioInit (void)
This routine installs standard I/O support. It must be called before using stdio buffering. If INCLUDE_STDIO is defined in configAll.h, it is called automatically by the root task usrRoot( ) in usrConfig.c.
OK, or ERROR if the standard I/O facilities cannot be installed.
stdioFp( ) - return the standard input/output/error FILE of the current task
FILE * stdioFp ( int stdFd /* fd of standard FILE to return (0,1,2) */ )
This routine returns the specified standard FILE structure address of the current task. It is provided primarily to give access to standard input, standard output, and standard error from the shell, where the usual stdin, stdout, stderr macros cannot be used.
stdio.h
The standard FILE structure address of the specified file descriptor, for the current task.
stdioShowInit( ) - initialize the standard I/O show facility
STATUS stdioShowInit (void)
This routine links the file pointer show routine into the VxWorks system. It is called automatically when this show facility is configured into VxWorks using either of the following methods:
- If you use the configuration header files, define INCLUDE_SHOW_ROUTINES in config.h.
- If you use the Tornado project facility, select INCLUDE_STDIO_SHOW.
OK, or ERROR if an error occurs installing the file pointer show routine.
stdioShow( ) - display file pointer internals
STATUS stdioShow ( FILE * fp, /* stream */ int level /* level */ )
This routine displays information about a specified stream.
OK, or ERROR if the file pointer is invalid.
tmpfile( ) - create a temporary binary file (Unimplemented) (ANSI)
FILE * tmpfile (void)
This routine is not be implemented because VxWorks does not close all open files at task exit.
stdio.h
NULL
tmpnam( ) - generate a temporary file name (ANSI)
char * tmpnam ( char * s /* name buffer */ )
This routine generates a string that is a valid file name and not the same as the name of an existing file. It generates a different string each time it is called, up to TMP_MAX times.
If the argument is a null pointer, tmpnam( ) leaves its result in an internal static object and returns a pointer to that object. Subsequent calls to tmpnam( ) may modify the same object. If the argument is not a null pointer, it is assumed to point to an array of at least L_tmpnam chars; tmpnam( ) writes its result in that array and returns the argument as its value.
stdio.h
A pointer to the file name.
ungetc( ) - push a character back into an input stream (ANSI)
int ungetc ( int c, /* character to push */ FILE * fp /* input stream */ )
This routine pushes a character c (converted to an unsigned char) back into the specified input stream. The pushed-back characters will be returned by subsequent reads on that stream in the reverse order of their pushing. A successful intervening call on the stream to a file positioning function (fseek( ), fsetpos( ), or rewind( )) discards any pushed-back characters for the stream. The external storage corresponding to the stream is unchanged.
One character of push-back is guaranteed. If ungetc( ) is called too many times on the same stream without an intervening read or file positioning operation, the operation may fail.
If the value of c equals EOF, the operation fails and the input stream is unchanged.
A successful call to ungetc( ) clears the end-of-file indicator for the stream. The value of the file position indicator for the stream after reading or discarding all pushed-back characters is the same as it was before the character were pushed back. For a text stream, the value of its file position indicator after a successful call to ungetc( ) is unspecified until all pushed-back characters are read or discarded. For a binary stream, the file position indicator is decremented by each successful call to ungetc( ); if its value was zero before a call, it is indeterminate after the call.
stdio.h
The pushed-back character after conversion, or EOF if the operation fails.
vfprintf( ) - write a formatted string to a stream (ANSI)
int vfprintf ( FILE * fp, /* stream to write to */ const char * fmt, /* format string */ va_list vaList /* arguments to format string */ )
This routine is equivalent to fprintf( ), except that it takes the variable arguments to be formatted from a list vaList of type va_list rather than from in-line arguments.
stdio.h
The number of characters written, or a negative value if an output error occurs.