printf(9r)printf(9r)NAME
printf, uprintf - General: Write formatted text to some output device
SYNOPSIS
void printf(
char *format,
va_dcl var_arglist ); void uprintf(
char *format,
va_dcl var_arglist );
ARGUMENTS
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 specifi‐
cation, 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.
DESCRIPTION
The printf and uprintf routines are scaled-down versions of the corre‐
sponding 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 log‐
ger.
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 rou‐
tines pad the value on the left. If the conversion string that speci‐
fies 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 spec‐
ifies 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 sup‐
plies 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 writ‐
ers find particularly useful: Allows decoding of error registers.
Prints the character argument. Converts the integer argument to deci‐
mal. 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 charac‐
ter. 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 hexa‐
decimal. 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 mul‐
tiple reg_desc structures. The reg_desc structure is defined as fol‐
lows:
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 fill‐
ing to length. For example:
printf(" %8x\n",regval);
The maximum field size is 11.
NOTES
Some device drivers might have used the tprintf routine to print on a
specified terminal or on the system console if no terminal was pro‐
vided. It is recommended that you discontinue use of tprintf because it
will not be supported in future releases of the operating system.
RETURN VALUES
None
printf(9r)