System Event Specifications

The following are event specifications for system events.

dlopen [ lib-path ] dlclose [ lib-path ]

These events occur after a dlopen()() call or a dlclose()() call succeeds. A dlopen()() call or dlclose()() call can cause more than one library to be loaded. The list of these libraries is always available in the predefined variable $dllist. The first shell word in $dllist is a “+” or a “-”, indicating whether the list of libraries is being added or deleted.

lib-path is the name of a shared library. If it is specified, the event occurs only if the given library was loaded or unloaded. In that case, $dlobj contains the name of the library. $dllist is still available.

If lib-path begins with a /, a full string match is performed. Otherwise, only the tails of the paths are compared.

If lib-path is not specified, then the events always occur whenever there is any dl-activity. In this case, $dlobj is empty but $dllist is valid.

fault fault

The fault event occurs when the specified fault is encountered. The faults are architecture-dependent. The following set of faults known to dbx is defined in the proc(4) man page.

BPT, TRACE, and BOUNDS are used by dbx to implement breakpoints and single-stepping. Handling them might interfere with how dbx works.

FLTBPT and FLTTRACE are ignored because they would interfere with basic dbx functionality such as breakpoints and single-stepping (see Event Safety).

These faults are taken from /sys/fault.h. fault can be any of those listed above, in uppercase or lowercase, with or without the FLT- prefix, or the actual numerical code.

The fault event is not available on Linux platforms.

lwp_exit

The lwp_exit event occurs when lwp has been exited. $lwp contains the id of the exited LWP (lightweight process) for the duration of the event handler.

The lwpexit event is not available on Linux platforms.

sig signal

The sig signal event occurs when the signal is first delivered to the program being debugged. signal can be either a decimal number or the signal name in uppercase or lowercase; the prefix is optional. This is completely independent of the catch command and ignore command, although the catch command can be implemented as follows:

function simple_catch {
    when sig $1 {
            stop;
            echo Stopped due to $sigstr $sig
            whereami
    }
}

When the sig event is received, the process has not seen it yet. Only if you continue the process with the specified signal is the signal forwarded to it.

sig signal sub-code

When the specified signal with the specified sub-code is first delivered to the child, the sig signal sub-code event occurs. As with signals, you can type the sub-code as a decimal number, in uppercase or lowercase; the prefix is optional.

sysin code | name

The specified system call has just been initiated, and the process has entered kernel mode.

The concept of system call supported by dbx is that provided by traps into the kernel as enumerated in /usr/include/sys/syscall.h.

This is not the same as the ABI notion of system calls. Some ABI system calls are partially implemented in user mode and use non-ABI kernel traps. However, most of the generic system calls (the main exception being signal handling) are the same between syscall.h and the ABI.

The sysin event is not available on Linux platforms.

The list of kernel system call traps in /usr/include/sys/syscall.h is part of a private interface in the Solaris OS that changes from release to release. The list of trap names (codes) and trap numbers that dbx accepts includes all of those supported by any of the versions of the Solaris OS that dbx supports. It is unlikely that the names supported by dbx exactly match those of any particular release of the Solaris OS, and some of the names in syscall.h might not be available. Any trap number (code) is accepted by dbx and works as expected, but a warning is issued if it does not correspond to a known system call trap.

sysout code | name

The specified system call is finished, and the process is about to return to user mode.

The sysout event is not available on Linux platforms.

sysin | sysout

Without arguments, all system calls are traced. Certain dbx features, for example, the modify event and runtime checking, cause the child to execute system calls for its own purposes and show up if traced.