 |
Index for
Section 9r |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
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
format
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.
var_arglist
Specifies the argument list.
DESCRIPTION
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 -).
blank
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:
b Allows decoding of error registers.
c Prints the character argument.
d Converts the integer argument to decimal.
o Converts the integer argument to octal.
x Converts the integer argument to hexadecimal.
s 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.
u 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:
<base> The output base expressed as a control character. For example, \10
gives octal and \20 gives hexadecimal.
<arg> 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:
r Allows formatted printing of bit fields. This code produces a string of
the format:
""<bit field descriptions>""
R 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:
rd_mask Specifies an appropriate mask to isolate the bit field within a
word and val argument (AND).
rd_shift
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.
rd_name 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.
rd_format
If non-NULL, specifies that the shifted bit field value is printed
using this format.
rd_values
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.
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 provided. 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
|
Index for
Section 9r |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|