Sun Microsystems, Inc.
spacerspacer
spacer www.sun.com docs.sun.com |
spacer
black dot
 
 
9.  Module Programming API API Functions mdb_printf() Terminal Attribute Specifiers  Previous   Contents   Next 
   
 

Format Specifiers

%%

The '%' symbol is printed.

%a

Prints an address in symbolic form. The minimum size of the value associated with %a is a uintptr_t; specifying %la is not necessary. If address-to-symbol conversion is on, the debugger will attempt to convert the address to a symbol name followed by an offset in the current output radix and print this string; otherwise, the value is printed in the default output radix. If %#a is used, the alternate format adds a ':' suffix to the output.

%A

This format is identical to %a, except when an address cannot be converted to a symbol name plus an offset, nothing is printed. If %#A is used, the alternate format prints a '?' when address conversion fails.

%b

Decode and print a bit field in symbolic form. This specifier expects two consecutive arguments: the bit field value (int for %b, long for %lb, and so forth), and a pointer to an array of mdb_bitmask_t structures:

typedef struct mdb_bitmask {
		const char *bm_name;       /* String name to print */
		u_longlong_t bm_mask;      /* Mask for bits */
		u_longlong_t bm_bits;      /* Result for value & mask */
} mdb_bitmask_t;

The array should be terminated by a structure whose bm_name field is set to NULL. When %b is used, the debugger reads the value argument, then iterates through each mdb_bitmask structure checking to see if:

(value & bitmask->bm_mask) == bitmask->bm_bits

If this expression is true, the bm_name string is printed. Each string printed is separated by a comma. The following example shows how %b can be used to decode the t_flag field in a kthread_t:

const mdb_bitmask_t t_flag_bits[] = {
		{ "T_INTR_THREAD", T_INTR_THREAD, T_INTR_THREAD },
		{ "T_WAKEABLE", T_WAKEABLE, T_WAKEABLE },
		{ "T_TOMASK", T_TOMASK, T_TOMASK },
		{ "T_TALLOCSTK", T_TALLOCSTK, T_TALLOCSTK },
			...
		{ NULL, 0, 0 }
};

void
thr_dump(kthread_t *t)
{
		mdb_printf("t_flag = <%hb>\n", t->t_flag, t_flag_bits);

		...
}

If t_flag was set to 0x000a, the function would print:

t_flag = <T_WAKEABLE,T_TALLOCSTK>

If %#b is specified, the union of all bits that were not matched by an element in the bitmask array is printed as a hexadecimal value following the decoded names.

%c

Print the specified integer as an ASCII character.

%d

Print the specified integer as a signed decimal value. Same as %i. If %#d is specified, the alternate format prefixes the value with '0t'.

%e

Print the specified double in the floating-point format [+/-]d.ddddddde[+/-]dd, where there is one digit before the radix character, seven digits of precision, and at least two digits following the exponent.

%E

Print the specified double using the same rules as %e, except that the exponent character will be 'E' instead of 'e'.

%g

Print the specified double in the same floating-point format as %e, but with sixteen digits of precision. If %llg is specified, the argument is expected to be of type long double (quad-precision floating-point value).

%G

Print the specified double using the same rules as %g, except that the exponent character will be 'E' instead of 'e'.

%i

Print the specified integer as a signed decimal value. Same as %d. If %#i is specified, the alternate format prefixes the value with '0t'.

%I

Print the specified 32-bit unsigned integer as an Internet IPv4 address in dotted-decimal format (for example, the hexadecimal value 0xffffffff would print as 255.255.255.255).

%m

Print a margin of whitespace. If no field is specified, the default output margin width is used; otherwise, the field width determines the number of characters of white space that are printed.

%o

Print the specified integer as an unsigned octal value. If %#o is used, the alternate format prefixes the output with '0'.

%p

Print the specified pointer (void *) as a hexadecimal value.

%q

Print the specified integer as a signed octal value. If %#o is used, the alternate format prefixes the output with '0'.

%r

Print the specified integer as an unsigned value in the current output radix. The user can change the output radix using the $d dcmd. If %#r is specified, the alternate format prefixes the value with the appropriate base prefix: '0i' for binary, '0o' for octal, '0t' for decimal, or '0x' for hexadecimal.

%R

Print the specified integer as a signed value in the current output radix. If %#R is specified, the alternate format prefixes the value with the appropriate base prefix.

%s

Print the specified string (char *). If the string pointer is NULL, the string '<NULL>' is printed.

%t

Advance one or more tab stops. If no width is specified, output advances to the next tab stop; otherwise the field width determines how many tab stops are advanced.

%T

Advance the output column to the next multiple of the field width. If no field width is specified, no action is taken. If the current output column is not a multiple of the field width, white space is added to advance the output column.

%u

Print the specified integer as an unsigned decimal value. If %#u is specified, the alternate format prefixes the value with '0t'.

%x

Print the specified integer as a hexadecimal value. The characters a-f are used as the digits for the values 10-15. If %#x is specified, the alternate format prefixes the value with '0x'.

%X

Print the specified integer as a hexadecimal value. The characters A-F are used as the digits for the values 10-15. If %#X is specified, the alternate format prefixes the value with '0X'.

%Y

The specified time_t is printed as the string 'year month day HH:MM:SS'.

mdb_snprintf()

size_t mdb_snprintf(char *buf, size_t len, const char *format, ...);

Construct a formatted string based on the specified format string and arguments, and store the resulting string into the specified buf. The mdb_snprintf() function accepts the same format specifiers and arguments as the mdb_printf() function. The len parameter specifies the size of buf in bytes. No more than len - 1 formatted bytes are placed in buf; mdb_snprintf() always terminates buf with a null byte. The function returns the number of bytes required for the complete formatted string, not including the terminating null byte. If the buf parameter is NULL and len is set to zero, the function will not store any characters to buf and returns the number of bytes required for the complete formatted string; this technique can be used to determine the appropriate size of a buffer for dynamic memory allocation.

mdb_warn()

void mdb_warn(const char *format, ...);

Print an error or warning message to standard error. The mdb_warn() function accepts a format string and variable argument list that can contain any of the specifiers documented for mdb_printf(). However, the output of mdb_warn() is sent to standard error, which is not buffered and is not sent through the output pager or processed as part of a dcmd pipeline. All error messages are automatically prefixed with the string "mdb:".

In addition, if the format parameter does not contain a newline (\n) character, the format string is implicitly suffixed with the string ": %s\n", where %s is replaced by the error message string corresponding to the last error recorded by a module API function. For example, the following source code:

if (mdb_lookup_by_name("no_such_symbol", &sym) == -1)
       mdb_warn("lookup_by_name failed");

produces this output:

mdb: lookup_by_name failed: unknown symbol name

mdb_flush()

void mdb_flush(void);

Flush all currently buffered output. Normally, mdb's standard output is line-buffered; output generated using mdb_printf() is not flushed to the terminal (or other standard output destination) until a newline is encountered, or at the end of the current dcmd. However, in some situations you might want to explicitly flush standard output prior to printing a newline; mdb_flush() can be used for this purpose.

mdb_nhconvert()

void mdb_nhconvert(void *dst, const void *src, size_t nbytes);

Convert a sequence of nbytes bytes stored at the address specified by src from network byte order to host byte order and store the result at the address specified by dst. The src and dst parameters may be the same, in which case the object is converted in place. This function may be used to convert from host order to network order or from network order to host order, since the conversion is the same in either case.

 		 
 
  Previous   Contents   Next