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 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.

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 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 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 corre-
       sponds 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 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 char-
       acter or until printing the number of characters specified by the precision. If the precision is zero or the precision has not been  speci-
       fied, 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
", 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
", 3, "10 2BITTWO1BITONE
");

       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 iso-
       lated 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
",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)