VxWorks Reference Manual : Libraries
fioLib - formatted I/O library
fioLibInit( ) - initialize the formatted I/O support library
printf( ) - write a formatted string to the standard output stream (ANSI)
printErr( ) - write a formatted string to the standard error stream
fdprintf( ) - write a formatted string to a file descriptor
sprintf( ) - write a formatted string to a buffer (ANSI)
vprintf( ) - write a string formatted with a variable argument list to standard output (ANSI)
vfdprintf( ) - write a string formatted with a variable argument list to a file descriptor
vsprintf( ) - write a string formatted with a variable argument list to a buffer (ANSI)
fioFormatV( ) - convert a format string
fioRead( ) - read a buffer
fioRdString( ) - read a string from a file
sscanf( ) - read and convert characters from an ASCII string (ANSI)
This library provides the basic formatting and scanning I/O functions. It includes some routines from the ANSI-compliant printf( )/scanf( ) family of routines. It also includes several utility routines.
If the floating-point format specifications e, E, f, g, and G are to be used with these routines, the routine floatInit( ) must be called first. If the configuration macro INCLUDE_FLOATING_POINT is defined, floatInit( ) is called by the root task, usrRoot( ), in usrConfig.c.
These routines do not use the buffered I/O facilities provided by the standard I/O facility. Thus, they can be invoked even if the standard I/O package has not been included. This includes printf( ), which in most UNIX systems is part of the buffered standard I/O facilities. Because printf( ) is so commonly used, it has been implemented as an unbuffered I/O function. This allows minimal formatted I/O to be achieved without the overhead of the entire standard I/O package. For more information, see the manual entry for ansiStdio.
fioLib.h, stdio.h
fioLib, ansiStdio, floatLib, VxWorks Programmer's Guide: I/O System
fioLibInit( ) - initialize the formatted I/O support library
void fioLibInit (void)
This routine initializes the formatted I/O support library. It should be called once in usrRoot( ) when formatted I/O functions such as printf( ) and scanf( ) are used.
N/A
printf( ) - write a formatted string to the standard output stream (ANSI)
int printf ( const char * fmt /* format string to write */ )
This routine writes output to standard output 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.
- WARNING: 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.
fioLib.h
The number of characters written, or a negative value if an output error occurs.
fioLib, fprintf( ), American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)
VARARGS1
printErr( ) - write a formatted string to the standard error stream
int printErr ( const char * fmt /* format string to write */ )
This routine writes a formatted string to standard error. Its function and syntax are otherwise identical to printf( ).
The number of characters output, or ERROR if there is an error during output.
VARARGS1
fdprintf( ) - write a formatted string to a file descriptor
int fdprintf ( int fd, /* file descriptor to write to */ const char * fmt /* format string to write */ )
This routine writes a formatted string to a specified file descriptor. Its function and syntax are otherwise identical to printf( ).
The number of characters output, or ERROR if there is an error during output.
VARARGS2
sprintf( ) - write a formatted string to a buffer (ANSI)
int sprintf ( char * buffer, /* buffer to write to */ const char * fmt /* format string */ )
This routine copies a formatted string to a specified buffer, which is null-terminated. Its function and syntax are otherwise identical to printf( ).
The number of characters copied to buffer, not including the NULL terminator.
fioLib, printf( ), American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)
VARARGS2
vprintf( ) - write a string formatted with a variable argument list to standard output (ANSI)
int vprintf ( const char * fmt, /* format string to write */ va_list vaList /* arguments to format */ )
This routine prints a string formatted with a variable argument list to standard output. It is identical to printf( ), except that it takes the variable arguments to be formatted as a list vaList of type va_list rather than as in-line arguments.
The number of characters output, or ERROR if there is an error during output.
fioLib, printf( ), American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)
vfdprintf( ) - write a string formatted with a variable argument list to a file descriptor
int vfdprintf ( int fd, /* file descriptor to print to */ const char * fmt, /* format string for print */ va_list vaList /* optional arguments to format */ )
This routine prints a string formatted with a variable argument list to a specified file descriptor. It is identical to fdprintf( ), except that it takes the variable arguments to be formatted as a list vaList of type va_list rather than as in-line arguments.
The number of characters output, or ERROR if there is an error during output.
vsprintf( ) - write a string formatted with a variable argument list to a buffer (ANSI)
int vsprintf ( char * buffer, /* buffer to write to */ const char * fmt, /* format string */ va_list vaList /* optional arguments to format */ )
This routine copies a string formatted with a variable argument list to a specified buffer. This routine is identical to sprintf( ), except that it takes the variable arguments to be formatted as a list vaList of type va_list rather than as in-line arguments.
The number of characters copied to buffer, not including the NULL terminator.
fioLib, sprintf( ), American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)
fioFormatV( ) - convert a format string
int fioFormatV ( const char * fmt, /* format string */ va_list vaList, /* pointer to varargs list */ FUNCPTR outRoutine, /* handler for args as they're formatted */ int outarg /* argument to routine */ )
This routine is used by the printf( ) family of routines to handle the actual conversion of a format string. The first argument is a format string, as described in the entry for printf( ). The second argument is a variable argument list vaList that was previously established.
As the format string is processed, the result will be passed to the output routine whose address is passed as the third parameter, outRoutine. This output routine may output the result to a device, or put it in a buffer. In addition to the buffer and length to output, the fourth argument, outarg, will be passed through as the third parameter to the output routine. This parameter could be a file descriptor, a buffer address, or any other value that can be passed in an "int".
The output routine should be declared as follows:
STATUS outRoutine ( char *buffer, /* buffer passed to routine */ int nchars, /* length of buffer */ int outarg /* arbitrary arg passed to fmt routine */ )The output routine should return OK if successful, or ERROR if unsuccessful.
The number of characters output, or ERROR if the output routine returned ERROR.
fioRead( ) - read a buffer
int fioRead ( int fd, /* file descriptor of file to read */ char * buffer, /* buffer to receive input */ int maxbytes /* maximum number of bytes to read */ )
This routine repeatedly calls the routine read( ) until maxbytes have been read into buffer. If EOF is reached, the number of bytes read will be less than maxbytes.
The number of bytes read, or ERROR if there is an error during the read operation.
fioRdString( ) - read a string from a file
int fioRdString ( int fd, /* fd of device to read */ char string[], /* buffer to receive input */ int maxbytes /* max no. of chars to read */ )
This routine puts a line of input into string. The specified input file descriptor is read until maxbytes, an EOF, an EOS, or a newline character is reached. A newline character or EOF is replaced with EOS, unless maxbytes characters have been read.
The length of the string read, including the terminating EOS; or EOF if a read error occurred or end-of-file occurred without reading any other character.
sscanf( ) - read and convert characters from an ASCII string (ANSI)
int sscanf ( const char * str, /* string to scan */ const char * fmt /* format string */ )
This routine reads characters from the string str, 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.
- WARNING: 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 sscanf( ) routine executes each directive of the format in turn. If a directive fails, as detailed below, sscanf( ) 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 sscanf( ) is written. Execution of a %n directive does not increment the assignment count returned when sscanf( ) 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.
fioLib.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.
fioLib, fscanf( ), scanf( ), American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)
VARARGS2