This appendix provides a reference for 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:
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.
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.
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
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:
Expands to the current instruction set architecture (ISA) name: sparc, sparcv9, i386, or amd64.
Expands to the old value of the path being modified. This is useful for appending or prepending directories to an existing path.
Expands to the current platform string (either uname -i or the platform string stored in the process core file or crash dump).
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.
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 32-bit mdb is:%r/usr/platform/%p/lib/adb:%r/usr/lib/adb
The default include path for 64-bit mdb is:%r/usr/platform/%p/lib/adb/%i:%r/usr/lib/adb/%i
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.
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.
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.
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.
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.
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:
Enable stricter adb(1) compatibility. The prompt is set to the empty string and many mdb features, such as the output pager, are disabled.
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.
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.
Set the debugger behavior for following an exec(2) system call. The mode should be one of the following named constants:
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.
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 Interaction with exec.
The debugger stops after the exec() system call returns. The stop behavior is discussed in more detail under Interaction with exec.
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:
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.
The debugger follows the parent process, and detaches from the child process and sets the child process running.
The debugger follows the child process, and detaches from the parent process and sets the parent process running.
The debugger does not exit when an
(^D) is entered at the terminal. The ::quit dcmd
must be used to quit.
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 Process Attach and Release.
The output pager is enabled (default).
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.
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 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.
Attaches to and stops the specified process id. mdb uses the /proc/pid/object/a.out file as the executable file path name.
Sets the command prompt. The default prompt is '> '.
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.
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.
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.
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.
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.
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.
Opens the specified object and core files for writing.
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.
The following operands are supported:
Specifies an ELF format object file to examine. mdb provides the ability to examine and edit ELF format executables (ET_EXEC), ELF dynamic library files (ET_DYN), ELF relocatable object files (ET_REL), and operating system unix.X symbol table files.
Specifies an ELF process core file (ET_CORE), or an operating system crash dump vmcore.X file. If an ELF core file operand is provided without a corresponding object file, mdb will attempt to infer the name of the executable file that produced the core using several different algorithms. If no executable is found, mdb will still execute, but some symbol information may be unavailable.
Specifies the numeric suffix that represents a pair of operating system crash dump files. For example, if the suffix is 3, then mdb should examine the files unix.3 and vmcore.3. If these files do not exist, but vmdump.3 does exist, then a message displays telling you to first run the following command to uncompress the dump file.
# savecore -f vmdump.3
The string of digits is not interpreted as a suffix if an actual file of the same name is present in the current directory.
The following exit values are returned:
Debugger completed execution successfully.
A fatal error occurred.
Invalid command line options were specified.
The following environment variables are supported:
This variable is used to determine the maximum length of the command history list. If this variable is not present, the default length is 128.
This variable is used to determine the pathname of the user's home directory, where a .mdbrc file may reside. If this variable is not present, no .mdbrc processing will occur.
This variable is used to determine the pathname of the shell used to process shell escapes requested using the ! meta-character. If this variable is not present, /bin/sh is used.