Go to main content

Oracle® Solaris Modular Debugger Guide

Exit Print View

Updated: October 2019
 
 

MDB Command-Line Options

This appendix provides a reference for MDB command-line options.

Summary of MDB Command-Line Options

mdb [ –fkmuwyAFMS ]  [ –o option ]  [ –p pid ]  [ –s distance]   
     [ –I path ]  [ –L path ]  [ –P prompt ]  [ –R root ]  
     [ –V dis-version ]  [ object  [ core...]  | core... | suffix ]

The following options are supported:

–A

Disables automatic loading of mdb modules. By default, mdb attempts to load debugger modules corresponding to the active shared libraries in a user process or core file, or to the loaded kernel modules in the live operating system or an operating system crash dump.

–F

Forcibly takes over the specified user process, if necessary. By default, mdb refuses to attach to a user process that is already under the control of another debugging tool, such as truss(1). With the –F option, mdb attaches to these processes anyway. This can produce unexpected interactions between mdb and the other tools attempting to control the process.

–f

Force raw file debugging mode. By default, mdb attempts to infer whether the object and core file operands refer to a user executable and core dump or to a pair of operating system crash dump files. If the file type cannot be inferred, the debugger will default to examining the files as plain binary data. The –foption forces mdb to interpret the arguments as a set of raw files to examine

–I

Sets default path for locating macro files. Macro files are read using the $< or $<< dcmds. The path is a sequence of directory names delimited by colon ( :) characters. The –I include path and –L library path (see below) can also contain any of the following tokens:

%i

Expands to the current instruction set architecture (ISA) name: sparc, sparcv9, i386, or amd64.

%o

Expands to the old value of the path being modified. This is useful for appending or prepending directories to an existing path.

%p

Expands to the current platform string (either uname –i or the platform string stored in the process core file or crash dump).

%r

Expands to the path name of the root directory. An alternate root directory can be specified using the –R option. If no –R option is present, the root directory is derived dynamically from the path to the mdb executable itself. For example, if /bin/mdb is executed, the root directory is /. If /net/hostname/bin/mdb were executed, the root directory would be derived as /net/hostname.

%t

Expands to the name of the current target. This is either the literal string 'proc' (a user process or user process core file), or 'kvm' (a kernel crash dump or the live operating system).

The default include path for 64-bit mdb is:%r/usr/platform/%p/lib/adb/%i:%r/usr/lib/adb/%i

–k

Forces kernel debugging mode. By default, mdb attempts to infer whether the object and core file operands refer to a user executable and core dump, or to a pair of operating system crash dump files. The –k option forces mdb to assume these files are operating system crash dump files. If no object or core operand is specified, but the –k option is specified, mdb defaults to an object file of /dev/ksyms and a core file of /dev/kmem. Access to /dev/kmem is restricted to group sys.

–K

Load kmdb, stop the live running operating system kernel, and proceed to the kmdb debugger prompt. This option should only be used on the system console, as the subsequent kmdb prompt will appear on the system console.

–L

Sets default path for locating debugger modules. Modules are loaded automatically on startup or by using the ::load dcmd. The path is a sequence of directory names delimited by colon (:) characters. The –L library path can also contain any of the tokens shown for –I above.

–m

Disables demand-loading of kernel module symbols. By default, mdb processes the list of loaded kernel modules and performs demand loading of per-module symbol tables. If the –m option is specified, mdb does not attempt to process the kernel module list or provide per-module symbol tables. As a result, mdb modules corresponding to active kernel modules are not loaded on startup.

–M

Preloads all kernel module symbols. By default, mdb performs demand-loading for kernel module symbols: the complete symbol table for a module is read when an address is that module's text or data section is referenced. With the –M option, mdb loads the complete symbol table of all kernel modules during startup.

–o option

Enables the specified debugger option. If the –o form of the option is used, the specified option is disabled. Unless noted below, each option is off by default. mdb recognizes the following option arguments:

adb

Enable stricter adb(1) compatibility. The prompt is set to the empty string and many mdb features, such as the output pager, are disabled.

array_mem_limit=limit

Set the default limit on the number of array members that ::print will display. If limit is the special token none, all array members will be displayed by default.

array_str_limit=limit

Set the default limit on the number of characters that ::print will attempt to display as an ASCII string when printing a char array. If limit is the special token none, the entire char array will be displayed as a string by default.

follow_exec_mode=mode

Set the debugger behavior for following an exec(2) system call. The mode should be one of the following named constants:

ask

If stdout is a terminal device, the debugger stops after the exec() system call returns and then prompts the user to decide whether to follow the exec or stop. If stdout is not a terminal device, the ask mode defaults to stop.

follow

The debugger follows the exec by automatically continuing the target process and resetting all of its mappings and symbol tables based on the new executable. The follow behavior is discussed in more detail under MDB Interaction With exec.

stop

The debugger stops after the exec() system call returns. The stop behavior is discussed in more detail under MDB Interaction With exec.

follow_fork_mode=mode

Set the debugger behavior for following a fork(2), fork1(2), or vfork(2) system call. The mode should be one of the following named constants:

ask

If stdout is a terminal device, the debugger stops after the fork() system call has returned and then prompts the user to decide whether to follow the parent or child. If stdout is not a terminal device, the ask mode defaults to parent.

parent

The debugger follows the parent process, and detaches from the child process and sets the child process running.

child

The debugger follows the child process, and detaches from the parent process and sets the parent process running.

ignoreeof

The debugger does not exit when an EOF sequence (^D) is entered at the terminal. The ::quit dcmd must be used to quit.

nostop

Do not stop a user process when attaching to it when the -p option is specified or when the ::attach or :A dcmds are applied. The nostop behavior is described in more detail under MDB Process Attach and Release.

nostrict

The debugger will not enforce the usage restrictions of dcmds.

pager

The output pager is enabled (default).

repeatlast

If a NEWLINE is entered as the complete command at the terminal, mdb repeats the previous command with the current value of dot. This option is implied by –o adb.

showlmid

MDB provides support for symbol naming and identification in user applications that make use of link maps other than LM_ID_BASE and LM_ID_LDSO, as described in MDB Symbol Name Resolution. Symbols on link maps other than LM_ID_BASE or LM_ID_LDSO will be shown as LMlmid`library`symbol, where lmid is the link-map ID in the default output radix (16). The user may optionally configure MDB to show the link-map ID scope of all symbols and objects, including those associated with LM_ID_BASE and LM_ID_LDSO, by enabling the showlmid option. Built-in dcmds that deal with object file names will display link-map IDs according to the value of showlmid above, including ::nm, ::mappings, $m, and ::objects.

–p pid

Attaches to and stops the specified process id. mdb uses the /proc/pid/object/a.out file as the executable file path name.

–P

Sets the command prompt. The default prompt is '> '.

–R

Sets root directory for path name expansion. By default, the root directory is derived from the path name of the mdb executable itself. The root directory is substituted in place of the %r token during path name expansion.

–s distance

Sets the symbol matching distance for address-to-symbol-name conversions to the specified distance. By default, mdb sets the distance to zero, which enables a smart-matching mode. Each ELF symbol table entry includes a value V and size S, representing the size of the function or data object in bytes. In smart mode, mdb matches an address A with the given symbol if A is in the range [ V, V + S ). If any non-zero distance is specified, the same algorithm is used, but S in the given expression is always the specified absolute distance and the symbol size is ignored.

–S

Suppresses processing of the user's ~/.mdbrc file. By default, mdb reads and processes the macro file .mdbrc if one is present in the user's home directory, as defined by $HOME. If the –S option is present, this file is not read.

–u

Forces user debugging mode. By default, mdb attempts to infer whether the object and core file operands refer to a user executable and core dump, or to a pair of operating system crash dump files. The –u option forces mdb to assume these files are not operating system crash dump files.

–U

Unload kmdb if it is loaded. You should unload kmdb when it is not in use to release the memory used by the kernel debugger back to the free memory available to the operating system.

–V

Sets disassembler version. By default, mdb attempts to infer the appropriate disassembler version for the debug target. The disassembler can be set explicitly using the –V option. The ::disasms dcmd lists the available disassembler versions.

–w

Opens the specified object and core files for writing.

–y

Sends explicit terminal initialization sequences for tty mode. Some terminals require explicit initialization sequences to switch into a tty mode. Without this initialization sequence, terminal features such as standout mode might not be available to mdb.