mdb_dumpptr() and mdb_dump64()

int mdb_dumpptr(uintptr_t addr, size_t nbytes, uint_t flags,
                     mdb_dumpptr_cb_t func, void *data);
int mdb_dump64(uint64_t addr, uint64_t nbytes, uint_t flags,
                     mdb_dump64_cb_t func, void *data);

These functions can be used to generate formatted hexadecimal and ASCII data dumps that are printed to standard output. Each function accepts an addr parameter specifying the starting location, a nbytes parameter specifying the number of bytes to display, a set of flags described below, a func callback function to use to read the data to display, and a data parameter that is passed to each invocation of the callback func as its last argument. The functions are identical in every regard except that mdb_dumpptr uses uintptr_t for its address parameters and mdb_dump64 uses uint64_t. This distinction is useful when combining mdb_dump64 with mdb_pread, for example. The built-in ::dump dcmd uses these functions to perform its data display.

The flags parameter should be the bitwise OR of one or more of the following values:

mdb_one_bit()

const char *mdb_one_bit(int width, int bit, int on);

The mdb_one_bit() function can be used to print a graphical representation of a bit field in which a single bit of interest is turned on or off. This function is useful for creating verbose displays of bit fields similar to the output from snoop(1M) -v. For example, the following source code:

#define FLAG_BUSY       0x1

uint_t flags;

/* ... */

mdb_printf("%s = BUSY\n", mdb_one_bit(8, 0, flags & FLAG_BUSY));

produces this output:

.... ...1 = BUSY

Each bit in the bit field is printed as a period (.), with each 4-bit sequence separated by a white space. The bit of interest is printed as 1 or 0, depending on the setting of the on parameter. The total width of the bit field in bits is specified by the width parameter, and the bit position of the bit of interest is specified by the bit parameter. Bits are numbered starting from zero. The function returns a pointer to an appropriately sized, null-terminated string containing the formatted bit representation. The string is automatically garbage-collected upon completion of the current dcmd.

mdb_inval_bits()

const char *mdb_inval_bits(int width, int start, int stop);

The mdb_inval_bits() function is used, along with mdb_one_bit(), to print a graphical representation of a bit field. This function marks a sequence of bits as invalid or reserved by displaying an 'x' at the appropriate bit location. Each bit in the bit field is represented as a period (.), except for those bits in the range of bit positions specified by the start and stop parameters. Bits are numbered starting from zero. For example, the following source code:

mdb_printf("%s = reserved\n", mdb_inval_bits(8, 7, 7));

produces this output:

x... .... = reserved

The function returns a pointer to an appropriately sized, null-terminated string containing the formatted bit representation. The string is automatically garbage-collected upon completion of the current dcmd.

mdb_inc_indent() and mdb_dec_indent()

ulong_t mdb_inc_indent(ulong_t n);
ulong_t mdb_dec_indent(ulong_t n);

These functions increment and decrement the numbers of columns that MDB will auto-indent with white space before printing a line of output. The size of the delta is specified by n, a number of columns. Each function returns the previous absolute value of the indent. Attempts to decrement the indent below zero have no effect. Following a call to either function, subsequent calls to mdb_printf() are indented appropriately. If the dcmd completes or is forcibly terminated by the user, the indent is restored automatically to its default setting by the debugger.

mdb_eval()

int mdb_eval(const char *s);

Evaluate and execute the specified command string s, as if it had been read from standard input by the debugger. This function returns 0 for success, or -1 for error. mdb_eval() fails if the command string contains a syntax error, or if the command string executed by mdb_eval() is forcibly aborted by the user using the pager or by issuing an interrupt.

mdb_set_dot() and mdb_get_dot()

void mdb_set_dot(uintmax_t dot);
uintmax_t mdb_get_dot(void);

Set or get the current value of dot (the "." variable). Module developers might want to reposition dot so that, for example, it refers to the address following the last address read by the dcmd.

mdb_get_pipe()

void mdb_get_pipe(mdb_pipe_t *p);

Retrieve the contents of the pipeline input buffer for the current dcmd. The mdb_get_pipe() function is intended to be used by dcmds that want to consume the complete set of pipe input and execute only once, instead of being invoked repeatedly by the debugger for each pipe input element. Once mdb_get_pipe() is invoked, the dcmd will not be invoked again by the debugger as part of the current command. This can be used, for example, to construct a dcmd that sorts a set of input values.

The pipe contents are placed in an array that is garbage-collected upon termination of the dcmd, and the array pointer is stored in p->pipe_data. The length of the array is placed in p->pipe_len. If the dcmd was not executed on the right-hand side of a pipeline (that is, the DCMD_PIPE flag was not set in its flags parameter), p->pipe_data is set to NULL and p->pipe_len is set to zero.

mdb_set_pipe()

void mdb_set_pipe(const mdb_pipe_t *p);

Set the pipeline output buffer to the contents described by the pipe structure p. The pipe values are placed in the array p->pipe_data, and the length of the array is stored in p->pipe_len. The debugger makes its own copy of this information, so the caller must remember to free p->pipe_data if necessary. If the pipeline output buffer was previously non-empty, its contents are replaced by the new array. If the dcmd was not executed on the left side of a pipeline (that is, the DCMD_PIPE_OUT flag was not set in its flags parameter), this function has no effect.

mdb_get_xdata()

ssize_t mdb_get_xdata(const char *name, void *buf, size_t nbytes);

Read the contents of the target external data buffer specified by name into the buffer specified by buf. The size of buf is specified by the nbytes parameter; no more than nbytes will be copied to the caller's buffer. The total number of bytes read will be returned upon success; -1 will be returned upon error. If the caller wants to determine the size of a particular named buffer, buf should be specified as NULL and nbytes should be specified as zero. In this case, mdb_get_xdata() will return the total size of the buffer in bytes but no data will be read. External data buffers provide module writers access to target data that is not otherwise accessible through the module API. The set of named buffers exported by the current target can be viewed using the ::xdata built-in dcmd.

Additional Functions

Additionally, module writers can use the following string(3C) and bstring(3C) functions. They are guaranteed to have the same semantics as the functions described in the corresponding Solaris man page.

strcat()           strcpy()                strncpy()
strchr()           strrchr()               strcmp()
strncmp()          strcasecmp()            strncasecmp()
strlen()           bcmp()                  bcopy()
bzero()            bsearch()               qsort()