printf, uprintf - General: Write formatted text to some
output device
void printf(
char *format,
va_dcl var_arglist ); void uprintf(
char *format,
va_dcl var_arglist );
Specifies a pointer to a string that contains two types of
objects. One object is ordinary characters, such as
``hello, world'', which are copied to the output stream.
The other object is a conversion specification, such as
%d, %o, or %x. Each conversion specification causes the
routines described here to convert and print for the next
argument in the var_arglist argument. The printf formats
%d and %x print 32 bits of data. To obtain 64 bits of
data, use %ld and %lx. Specifies the argument list.
The printf and uprintf routines are scaled-down versions
of the corresponding C library routines. The printf routine
prints diagnostic information directly on the console
terminal and writes ASCII text to the error logger.
Because printf is not interrupt driven, all system activities
are suspended when you call it.
The uprintf routine prints to the current user's terminal.
Interrupt service routines should never call uprintf. It
does not perform any space checking, so you should not use
this routine to print verbose messages. The uprintf routine
does not log messages to the error logger.
You introduce conversion specifications by using the percent
sign (%). Following the %, you can include: Zero or
more flags, which modify the meaning of the conversion
specification. An optional minus sign (-), which specifies
left adjustment of the converted value in the indicated
field. An optional digit string, which specifies a
field width. If the converted value has fewer characters
than the field width, the printf and uprintf routines pad
the value with blanks. By default, these routines pad the
value on the left. If the conversion string that specifies
the value is left justified, these routines pad the value
on the right. If the field width begins with a zero, these
routines pad the values with zeros instead of blanks. The
character h or l, which specifies that a following d, i,
o, u, x, or X corresponds to an integer or longword integer
argument. You can use an uppercase L or a lowercase l.
A character that indicates the type of conversion to be
applied.
A field width or precision can be an asterisk (*) instead
of a digit string. If you use an asterisk, you can include
an argument that supplies the field width or precision.
The flag characters and their meanings are as follows: The
result of the conversion is left justified within the
field. The result of a signed conversion always begins
with a sign (+ or -). If the first character of a signed
conversion is not a sign, the printf and uprintf routines
pad the value on the left with a blank. If the blank and
plus sign (+) flags both appear, these routines ignore the
blank flag. The result has been converted to a different
format. The value is to be converted to an alternative
form.
For c, d, s, and u conversions, this flag has no
effect.
For x or X conversions, the printf and uprintf routines
pad a nonzero result on the left with 0x or
0X.
These routines support the following formats which kernel
module writers find particularly useful: Allows decoding
of error registers. Prints the character argument. Converts
the integer argument to decimal. Converts the integer
argument to octal. Converts the integer argument to
hexadecimal. Prints the character argument. The printf
and uprintf routines print the argument until encountering
a null character or until printing the number of characters
specified by the precision. If the precision is zero
or the precision has not been specified, these routines
print the character argument until encountering a null
character. Converts the unsigned integer argument to a
decimal value. The result must be in the range of 0
through 4294967295, where the upper bound is defined by
MAXUINT. Prints a percent sign (%). The routines convert
no argument.
The following line shows the format of the printf routine
with the % b conversion character:
printf("reg=%b\n", regval, "<base> <arg>*");
In this case, base and arg are defined as: The output base
expressed as a control character. For example, \10 gives
octal and \20 gives hexadecimal. A sequence of characters.
The first character gives the bit number to be
inspected (origin 1). The second and subsequent characters
(up to a control character, that is, a character <=32)
give the name of the register.
The following shows a call to printf:
printf("reg=%b\n", 3, "\10 \2BITTWO\1BITONE\n");
This example would produce the following output:
reg=2<BITTWO,BITONE>
The following shows the format of the printf routine with
the % r and % R conversion characters:
printf("%r R", val, reg_desc);
The conversion characters have the following meanings:
Allows formatted printing of bit fields. This code produces
a string of the format:
""<bit field descriptions>"" Allows formatted
printing of bit fields. This code produces a string
of the format:
""0x%x<bit field descriptions>""
You use a reg_desc structure to describe the individual
bit fields. To describe multiple bit fields within a single
word, you can declare multiple reg_desc structures.
The reg_desc structure is defined as follows:
struct reg_desc {
unsigned rd_mask; /* mask to extract field
*/
int rd_shift; /* shift for extracted
*/
/* value, - >>, + <<
*/
char *rd_name; /* field name
*/
char *rd_format; /* format to print field
*/
struct reg_values *rd_values; /* symbolic names of
*/
/* values
*/ };
The members of the reg_desc structure have the following
meanings: Specifies an appropriate mask to isolate the bit
field within a word and val argument (AND). Specifies a
shift amount to be done to the isolated bit field. The
shift is done before printing the isolated bit field with
the rd_format member and before searching for symbolic
value names in the rd_values member. If non-NULL, specifies
a bit field name to label any output from rd_format
or searching rd_values. If rd_format and rd_values are
NULL, rd_name is printed only if the isolated bit field is
non-NULL. If non-NULL, specifies that the shifted bit
field value is printed using this format. If non-NULL,
specifies a pointer to a table that matches numeric values
with symbolic names. The routine searches the rd_values
member and prints the symbolic name if it finds a match.
If it does not find a match, it prints ``???''.
The following is a sample reg_desc entry:
struct reg_desc dsc[] = {
/* mask shift name format values */
{ VPNMASK, 0, "VA", "0x%x", NULL },
{ PIDMASK, PIDSHIFT, "PID", "%d", NULL },
{ 0, 0, NULL, NULL, NULL },
};
The printf and uprintf routines also accept a field number,
zero filling to length. For example:
printf(" %8x\n",regval);
The maximum field size is 11.
Some device drivers might have used the tprintf routine to
print on a specified terminal or on the system console if
no terminal was provided. It is recommended that you discontinue
use of tprintf because it will not be supported
in future releases of the operating system.
None
printf(9r)
[ Back ] |
