Built-in dcmds

[ addr ] ::bp [+/-dDestT] [-c cmd] [-n count] sym ...

addr :b [cmd ... ]

Set a breakpoint at the specified locations. The ::bp dcmd sets a breakpoint at each address or symbol specified, including an optional address specified by an explicit expression preceding the dcmd, and each string or immediate value following the dcmd. The arguments may either be symbol names or immediate values denoting a particular virtual address of interest. If a symbol name is specified, it may refer to a symbol that cannot yet be evaluated in the target process: that is, it may consist of an object name and function name in a load object that has not yet been opened. In this case, the breakpoint is deferred and it will not be active in the target until an object matching the given name is loaded. The breakpoint will be automatically enabled when the load object is opened. Breakpoints on symbols defined in a shared library should always be set using a symbol name and not using an address expression, as the address may refer to the corresponding Procedure Linkage Table (PLT) entry instead of the actual symbol definition. Breakpoints set on PLT entries may be overwritten by the run-time link-editor when the PLT entry is subsequently resolved to the actual symbol definition. The -d, -D, -e, -s, -t, -T, -c, and -n options have the same meaning as they do for the ::evset dcmd, as described later in this section. If the :b form of the dcmd is used, a breakpoint is only set at the virtual address specified by the expression preceding the dcmd. The arguments following the :b dcmd are concatenated together to form the callback string. If this string contains meta-characters, it must be quoted.

function ::call [ arg ... ]

When using kmdb only, call the specified function defined in the operating system kernel. The function expression must match the address of a defined function in a symbol table of one of the known kernel modules. If expression arguments are specified, these arguments as passed by value. If string arguments are specified, these arguments are passed by reference.

---

Note - The ::call command should be used only with extreme caution and should never be applied to a production system. The operating system kernel will not resume execution in order to execute the specified function. Therefore, the function being called must not utilize arbitrary kernel services and must not block for any reason. You must be fully aware of the side-effects of any function you call using this command.

---

::cont [SIG]

:c [SIG]

Suspend the debugger, continue the target program, and wait for it to terminate or stop following a software event of interest. If the target is already running because the debugger was attached to a running program with the -o nostop option enabled, this dcmd simply waits for the target to terminate or stop after an event of interest. If an optional signal name or number (see the signal (3HEAD) man page) is specified as an argument, the signal is immediately delivered to the target as part of resuming its execution. If the SIGINT signal is traced, control may be asynchronously returned to the debugger by typing the user-defined interrupt character (usually ^C). This SIGINT signal will be automatically cleared and will not be observed by the target the next time it is continued. If no target program is currently running, ::cont will start a new program running as if by ::run.

addr ::delete [id | all]

addr :d [id | all]

Delete the event specifiers with the given id number. The id number argument is interpreted in decimal by default. If an optional address is specified preceding the dcmd, all event specifiers that are associated with the given virtual address are deleted (e.g. all breakpoints or watchpoints affecting that address). If the special argument all is given, all event specifiers are deleted, except those that are marked sticky (T flag). The ::events dcmd displays the current list of event specifiers.

::events [-av]

$b [-av]

Display the list of software event specifiers. Each event specifier is assigned a unique ID number that can be used to delete or modify it at a later time. The debugger may also have its own internal events enabled for tracing; these will only be displayed if the -a option is present. If the -v option is present, a more verbose display including the reason for any specifier inactivity will be shown. The following ::events dcmd shows example output:

> ::events
   ID S TA HT LM Description                              Action
----- - -- -- -- ---------------------------------------- -------------
[ 1 ] - T   1  0 stop on SIGINT                           -      
[ 2 ] - T   0  0 stop on SIGQUIT                          -
[ 3 ] - T   0  0 stop on SIGILL                           -
 ...
[ 11] - T   0  0 stop on SIGXCPU                          -
[ 12] - T   0  0 stop on SIGXFSZ                          -
[ 13] -     2  0 stop at libc`printf                      ::echo printf
>

The following discussion explains the meaning of each column. A summary of this information is available using ::help events.

ID

The event specifier identifier. The identifier will be shown in square brackets [ ] if the specifier is enabled, in parentheses ( ) if the specifier is disabled, or in angle brackets < > if the target program is currently stopped on an event that matches the given specifier.

S

The event specifier state. The state will be one of the following symbols:

-

The event specifier is idle. When no target program is running, all specifiers are idle. When the target program is running, a specifier may be idle if it cannot be evaluated (such as a deferred breakpoint in a shared object that is not yet loaded).

+

The event specifier is active. When the target is continued, events of this type will be detected by the debugger.

*

The event specifier is armed. This state means that the target is currently running with instrumentation for this type of event. This state is only visible if the debugger is attached to a running program with the-o nostop option.

!

The event specifier was not armed due to an operating system error. The ::events -v option can be used to display more information about the reason the instrumentation failed.

TA

The Temporary, Sticky, and Automatic event specifier properties. One or more of the following symbols may be shown:

t

The event specifier is temporary, and will be deleted the next time the target stops, regardless of whether it is matched.

T

The event specifier is sticky, and will be not be deleted by ::delete all or :z. The specifier can be deleted by explicitly specifying its id number to::delete.

d

The event specifier will be automatically disabled when the hit count is equal to the hit limit.

D

The event specifier will be automatically deleted when the hit count is equal to the hit limit.

s

The target will automatically stop when the hit count is equal to the hit limit.

HT

The current hit count. This column displays the number of times the corresponding software event has occurred in the target since the creation of this event specifier.

LM

The current hit limit. This column displays the limit on the hit count at which the auto-disable, auto-delete, or auto-stop behavior will take effect. These behaviors can be configured using the ::evset dcmd.

Description

A description of the type of software event that is matched by the given specifier.

Action

The callback string to execute when the corresponding software event occurs. This callback is executed as if it had been typed at the command prompt.

id ::evset [+/-dDestT] [-c cmd] [-n count] id ...

Modify the properties of one or more software event specifiers. The properties are set for each specifier identified by the optional expression preceding the dcmd and an optional list of arguments following the dcmd. The argument list is interpreted as a list of decimal integers, unless an explicit radix is specified. The ::evset dcmd recognizes the following options:

-d

Disable the event specifier when the hit count reaches the hit limit. If the +d form of the option is given, this behavior is disabled. Once an event specifier is disabled, the debugger will remove any corresponding instrumentation and will ignore the corresponding software events until the specifier is subsequently re-enabled. If the -n option is not present, the specifier is disabled immediately.

-D

Delete the event specifier when the hit count reaches the hit limit. If the +D form of the option is given, this behavior is disabled. The -D option takes precedence over the -d option. The hit limit can be configured using the -n option.

-e

Enable the event specifier. If the +e form of the option is given, the specifier is disabled.

-s

Stop the target program when the hit count reaches the hit limit. If the +s form of the option is given, this behavior is disabled. The -s behavior tells the debugger to act as if ::cont were issued following each execution of the specifier's callback, except for the Nth execution, where N is the current value of the specifier's hit limit. The -s option takes precedence over both the -D option and the -d option.

-t

Mark the event specifier as temporary. Temporary specifiers are automatically deleted the next time the target stops, regardless of whether it stopped as the result of a software event corresponding to the given specifier. If the +t form of the option is given, the temporary marker is removed. The -t option takes precedence over the -T option.

-T

Mark the event specifier as sticky. Sticky specifiers will not be deleted by ::delete all or :z. They can be deleted by specifying the corresponding specifier ID as an explicit argument to ::delete. If the +T form of the option is given, the sticky property is removed. The default set of event specifiers are all initially marked sticky.

-c

Execute the specified cmd string each time the corresponding software event occurs in the target program. The current callback string can be displayed using ::events.

-n

Set the current value of the hit limit to count. If no hit limit is currently set and the -n option does not accompany -s or -D, the hit limit will be set to one.

A summary of this information is available using ::help evset.

flt ::fltbp [+/-dDestT] [-c cmd] [-n count] flt ...

Trace the specified machine faults. The faults are identified using an optional fault number preceding the dcmd, or a list of fault names or numbers (see <sys/fault.h>) following the dcmd. The -d, -D, -e, -s, -t, -T, -c, and -n options have the same meaning as they do for the ::evset dcmd. The ::fltbp command applies to user process debugging only.

signal :i

If the target is a live user process, ignore the specified signal and allow it to be delivered transparently to the target. All event specifiers that are tracing delivery of the specified signal will be deleted from the list of traced events. By default, the set of ignored signals is initialized to the complement of the set of signals that cause a process to dump core by default (see the signal(3HEAD) man page), except for SIGINT, which is traced by default. The :i command applies to user process debugging only.

$i

Display the list of signals that are ignored by the debugger and will be handled directly by the target. More information on traced signals can be obtained using the ::events dcmd. The $i command applies to user process debugging only.

::kill

:k

Forcibly terminate the target if it is a live user process. The target will also be forcibly terminated when the debugger exits if it was created by the debugger using ::run. The ::kill command applies to user process debugging only.

$l

Print the LWPID of the representative thread, if the target is a user process.

$L

Print the LWPIDs of each LWP in the target, if the target is a user process.

::next [SIG]

:e [SIG]

Step the target program one instruction, but step over subroutine calls. If an optional signal name or number (see signal(3HEAD) man page) is specified as an argument, the signal is immediately delivered to the target as part of resuming its execution. If no target program is currently running, ::next will start a new program running as if by ::run and stop at the first instruction.

::run [args ... ]

:r [args ... ]

Start a new target program running with the specified arguments and attach to it. The arguments are not interpreted by the shell. If the debugger is already examining a live running program, it will first detach from this program as if by ::release.

[signal] ::sigbp [+/-dDestT] [-c cmd] [-n count] SIG ...

[signal] :t [+/-dDestT] [-c cmd] [-n count] SIG ...

Trace delivery of the specified signals. The signals are identified using an optional signal number preceding the dcmd, or a list of signal names or numbers (see signal(3HEAD)) following the dcmd. The -d, -D, -e, -s, -t, -T, -c, and -n options have the same meaning as they do for the ::evset dcmd. Initially, the set of signals that cause the process to dump core by default (see signal(3HEAD)) and SIGINT are traced. The ::sigbp command applies to user process debugging only.

::step [branch | over | out] [SIG]

:s SIG

:u SIG

Step the target program one instruction. If an optional signal name or number (see the signal(3HEAD) man page) is specified as an argument and the target is a user process, the signal is immediately delivered to the target as part of resuming its execution. If the optional branch argument is specified, the target program will continue until the next instruction that branches the control flow of the processor. The ::step branch feature is only available when using kmdb on x86 systems with appropriate processor-specific features enabled. If the optional over argument is specified, ::step will step over subroutine calls. The ::step over argument is the same as the ::next dcmd. If the optional out argument is specified, the target program will continue until the representative thread returns from the current function. If no target program is currently running, ::step over will start a new program running as if by ::run and stop at the first instruction. The :s dcmd is the same as ::step. The :u dcmd is the same as ::step out.

[syscall] ::sysbp [+/-dDestT] [-io] [-c cmd] [-n count] syscall ...

Trace entry to or exit from the specified system calls. The system calls are identified using an optional system call number preceding the dcmd, or a list of system call names or numbers (see <sys/syscall.h>) following the dcmd. If the -i option is specified (the default), the event specifiers trigger on entry into the kernel for each system call. If the -o option is specified, the event specifiers trigger on exit out from the kernel. The -d, -D, -e, -s, -t, -T, -c, and -n options have the same meaning as they do for the ::evset dcmd. The ::sysbp command applies to user process debugging only.

addr [,len]::wp [+/-dDestT] [-rwx] [-ip] [-c cmd] [-n count]

addr [,len]:a [cmd... ]

addr [,len]:p [cmd... ]

addr [,len]:w [cmd... ]

Set a watchpoint at the specified address. The length in bytes of the watched region may be set by specifying an optional repeat count preceding the dcmd. If no length is explicitly set, the default is one byte. The ::wp dcmd allows the watchpoint to be configured to trigger on any combination of read (-r option), write (-w option), or execute (-x option) access. The -d, -D, -e, -s, -t, -T, -c, and -n options have the same meaning as they do for the ::evset dcmd. When using kmdb on x86 systems only, the -i option can be used to indicate that a watchpoint should be set on the address of an I/O port. When using kmdb only, the -p option can be used to indicate that the specified address should be interpreted as a physical address. The :a dcmd sets a read access watchpoint at the specified address. The :p dcmd sets an execute access watchpoint at the specified address. The :w dcmd sets a write access watchpoint at the specified address. The arguments following the :a. :p, and :w dcmds are concatenated together to form the callback string. If this string contains meta-characters, it must be quoted.

:z

Delete all event specifiers from the list of traced software events. Event specifiers can also be deleted using ::delete.