Sun Studio 12: Debugging a Program With dbx

Chapter 3 Customizing `dbx`

This chapter describes the dbx environment variables you can use to customize certain attributes of your debugging environment, and how to use the initialization file, .dbxrc, to preserve your changes and adjustments from session to session.

This chapter is organized into the following sections:

Using the `dbx` Initialization File

The dbx initialization file stores dbx commands that are executed each time you start dbx. Typically, the file contains commands that customize your debugging environment, but you can place any dbx commands in the file. If you customize dbx from the command line while you are debugging, those settings apply only to the current debugging session.

Note –

A . dbxrc file should not contain commands that execute your code. However, you can put such commands in a file, and then use the dbx source command to execute the commands in that file.

During startup, the search order is:

Installation directory (unless you specify the -S option to the dbx command) /installation_directory/lib/dbxrc (the default installation_directory is /opt/SUNWspro on Solaris platforms and /opt/sun/sunstudio12 on Linux platform). If your Sun Studio software is not installed in the default installation_directory, dbx derives the path to the dbxrc file from the path to the dbx executable.
Current directory ./.dbxrc
Home directory $HOME/.dbxrc

Creating a `.dbxrc` File

To create a .dbxrc file that contains common customizations and aliases, type:

(dbx) help .dbxrc>$HOME/.dbxrc

You can then customize the resulting file by using your text editor to uncomment the entries you want to have executed.

Initialization File Sample

Here is a sample .dbxrc file:

dbxenv input_case_sensitive false
catch FPE

The first line changes the default setting for the case sensitivity control:

dbxenv is the command used to set dbx environment variables. (For a complete list of dbx environment variables, see Setting dbx Environment Variables.)
input_case_sensitive is the dbx environment variable that controls case sensitivity.
false is the setting for input_case_sensitive.

The next line is a debugging command, catch, which adds a system signal, FPE, to the default list of signals to which dbx responds, stopping the program.

Setting `dbx` Environment Variables

You can use the dbxenv command to set the dbx environment variables that customize your dbx sessions.

To display the value of a specific variable, type:

(dbx) dbxenv variable

To show all variables and their values, type:

(dbx) dbxenv

To set the value of a variable, type:

(dbx) dbxenv variable value

Table 3–1 shows all of the dbx environment variables that you can set:

Table 3–1 dbx Environment Variables


`dbx` Environment Variable	What the Variable Does
`array_bounds_check on\|off`	If set to `on`, `dbx` checks the array bounds. Default: `on`.
`CLASSPATHX`	Lets you specify to `dbx` a path for Java class files that are loaded by custom class loaders
`core_lo_pathmap on\|off`	Controls whether `dbx` uses pathmap settings to locate the correct libraries for a “mismatched” core file. Default: `off`.
`debug_file_directory`	Sets global debug file directory. Default: `/usr/lib/debug.`
`disassembler_version` `autodetect\|v8\|v9\|x86_32\|x86-64`	SPARC platform: Sets the version of `dbx`’s built-in disassembler for SPARC V8 or V9. Default is `autodetect`, which sets the mode dynamically depending on the type of the machine `a.out` is running on. x86 platforms: The valid choice is `autodetect`.
`event_safety`	Protects `dbx` against unsafe use of events.
`fix_verbose on\|off`	Governs the printing of compilation line during a `fix`. Default: `off`
`follow_fork_inherit on\|off`	When following a child, inherits or does not inherit breakpoints. Default: `off`
`follow_fork_mode parent\|child\|both\|ask`	Determines which process is followed after a fork; that is, when the current process executes a `fork`, `vfork`, or `fork1`. If set to `parent`, the process follows the parent. If set to `child`, it follows the child. If set to `both`, it follows the child, but the parent process remains active. If set to `ask`, you are asked which process to follow whenever a fork is detected. Default: `parent`.
`follow_fork_mode_inner unset\|` `parent\|child\|both`	Of relevance after a fork has been detected if `follow_fork_mode` was set to `ask`, and you chose `stop`. By setting this variable, you need not use `cont -follow`.
`input_case_sensitive autodetect\|` `true\|false`	If set to `autodetect`, `dbx` automatically selects case sensitivity based on the language of the file: `false` for Fortran files, otherwise `true`. If `true`, case matters in variable and function names; otherwise, case is not significant. Default: `autodetect.`
`JAVASRCPATH`	Specifies the directories in which `dbx` should look for Java source files.
`jdbx_mode` `java`\| `jni\|` `native`	Stores the current `dbx` mode. It can have the following settings: `java`, `jni,` or `native`.
`jvm_invocation`	The `jvm_invocation` environment variable lets you customize the way the JVM^TM software is started. (The terms “Java virtual machine” and “JVM” mean a virtual machine for the Java^TM platform.) For more information, see Customizing Startup of the JVM Software.
`language_mode autodetect\|main\|c\| c++\|fortran\|fortran90`	Governs the language used for parsing and evaluating expressions. `autodetect` sets the expression language to the language of the current file. Useful if debugging programs with mixed languages (default). `main` sets the expression language to the language of the main routine in the program. Useful if debugging homogeneous programs. `c`, `c++`, `c++`, `fortran`, or `fortran90` sets the expression language to the selected language.
`mt_scalable on\|off`	When enabled, `dbx` will be more conservative in its resource usage and will be able to debug processes with upwards of 300 LWPs. The down side is significant slowdown. Default: `off`.
`optim_local_vars` `on\|off`	When enabled, you can evaluate local variables in optimized functions. Default: `off`.
`output_auto_flush on\|off`	Automatically calls `fflush()` after each `call`. Default: `on`
`output_base 8\|10\|16\|automatic`	Default base for printing integer constants. Default: `automatic` (pointers in hexadecimal characters, all else in decimal).
`output_class_prefix on \| off`	Used to cause a class member to be prefixed with classname(s) when its value or declaration is printed. If set to `on`, it causes the class member to be prefixed. Default: `on`.
`output_dynamic_type on\|off`	When set to `on`, `-d` is the default for printing watches and displaying. Default: `off`.
`output_inherited_members on\|off`	When set to `on`, `-r` is the default for printing, displaying, and inspecting. Default: `off`.
`output_list_size` `num`	Governs the default number of lines to print in the `list` command. Default: 10.
`output_log_file_name` `filename`	Name of the command logfile. Default: `/tmp/dbx.log.uniqueID`
`output_max_string_length` `number`	Sets `number` of characters printed for `char *s`. Default: 512.
`output_no_literal`	When enabled, if the expression is a string (`char *`), print the address only, do not print the literal. Default: `off`.
`output_pretty_print on\|off`	Sets `-p` as the default for printing watches and displaying. Default: `off`.
`output_pretty_print_fallback`	By default, pretty-printing reverts to regular printing if problems occur. If you want to diagnose a pretty-printing problem, set this variable to off to prevent the fallback. Default: `on`
`output_short_file_name on\|off`	Displays short path names for files. Default: `on`.
`overload_function on\|off`	For C++, if set to `on`, does automatic function overload resolution. Default: `on`.
`overload_operator on\|off`	For C++, if set to `on`, does automatic operator overload resolution. Default: `on`.
`pop_auto_destruct on\|off`	If set to `on`, automatically calls appropriate destructors for locals when popping a frame. Default: `on`.
`proc_exclusive_attach on\|off`	If set to `on`, keeps `dbx` from attaching to a process if another tool is already attached. Warning: be aware that if more than one tool attaches to a process and tries to control it chaos ensues. Default: `on`.
`rtc_auto_continue on\|off`	Logs errors to `rtc_error_log_file_name` and continue. Default: `off`.
`rtc_auto_suppress on\|off`	If set to `on`, an RTC error at a given location is reported only once. Default: `off`.
`rtc_biu_at_exit on\|off\|verbose`	Used when memory use checking is on explicitly or via `check -all`. If the value is `on`, a non-verbose memory use (blocks in use) report is produced at program exit. If the value is `verbose`, a verbose memory use report is produced at program exit. The value `off` causes no output. Default: `on`.
`rtc_error_limit` `number`	`Number` of RTC errors to be reported. Default: 1000.
`rtc_error_log_file_name` `filename`	Name of file to which RTC errors are logged if `rtc_auto_continue` is set. Default: `/tmp/dbx.errlog.uniqueID`
`rtc_error_stack on\|off`	If set to `on`, stack traces show frames corresponding to RTC internal mechanisms. Default: `off`.
`rtc_inherit on\|off`	If set to `on`, enables runtime checking on child processes that are executed from the debugged program and causes the `LD_PRELOAD` environment variable to be inherited. Default: `off`.
`rtc_mel_at_exit on\|off\|verbose`	Used when memory leak checking is `on`. If the value is `on`, a non-verbose memory leak report is produced at program exit. If the value is `verbose`, a verbose memory leak report is produced at program exit. The value `off` causes no output. Default: `on`.
`run_autostart on\|off`	If set to `on` with no active program, `step`, `next`, `stepi`, and `nexti` implicitly run the program and stop at the language-dependent `main` routine. If set to `on`, `cont` implies `run` when necessary. Default: `off`.
`run_io` `stdio\|pty`	Governs whether the user program’s input/output is redirected to `dbx`’s `stdio` or a specific pty. The pty is provided by `run_pty`. Default: `stdio`.
`run_pty` `ptyname`	Sets the name of the pty to use when `run_io` is set to `pty`. Ptys are used by graphical user interface wrappers.
`run_quick on\|off`	If set to `on`, no symbolic information is loaded. The symbolic information can be loaded on demand using `prog -readsysms`. Until then, `dbx` behaves as if the program being debugged is stripped. Default: `off`.
`run_savetty on \| off`	Multiplexes tty settings, process group, and keyboard settings (if `-kbd` was used on the command line) between `dbx` and the program being debugged. Useful when debugging editors and shells. Set to `on` if `dbx` gets `SIGTTIN` or `SIGTTOU` and pops back into the shell. Set to `off` to gain a slight speed advantage. The setting is irrelevant if `dbx` is attached to the program being debugged or is running in the Sun Studio IDE. Default: `off`.
`run_setpgrp on \| off`	If set to `on`, when a program is run, `setpgrp(2)`is called right after the fork. Default: `off`.
`scope_global_enums on \| off`	If set to `on`, enumerators are put in global scope and not in file scope. Set before debugging information is processed (~/`.dbxrc`). Default: `off`.
`scope_look_aside on \| off`	If set to `on`, finds file static symbols, in scopes other than the current scope. Default: `on`.
`session_log_file_name` `filename`	Name of the file where `dbx` logs all commands and their output. Output is appended to the file. Default: "" (no session logging).
`stack_find_source on \| off`	When set to `on`, `dbx` attempts to find and automatically make active the first stack frame with source when the program being debugged comes to a stop in a function that is not compiled with `-g`. Default: `on`.
`stack_max_size` `number`	Sets the default size for the `where` command. Default: 100.
`stack_verbose on \| off`	Governs the printing of arguments and line information in `where`. Default: `on`.
`step_abflow stop\|ignore`	When set to stop, `dbx` stops in `longjmp()`, `siglongjmp(`), and throw statements when single stepping. When set to ignore, `dbx` does not detect abnormal control flow changes for `longjmp()` and `siglongjmp()`.
`step_events on \|off`	When set to `on`, allows breakpoints while using `step` and `next` commands to step through code. Default: `off`.
`step_granularity` `statement \| line`	Controls granularity of source line stepping. When set to `statement` the following code: `a(); b();` takes the two `next` commands to execute. When set to `line` a single `next` command executes the code. The granularity of line is particularly useful when dealing with multiline macros. Default: `statement`.
`suppress_startup_message` `number`	Sets the release level below which the startup message is not printed. Default: 3.01.
`symbol_info_compression on\|off`	When set to `on`, reads debugging information for each `include` file only once. Default: `on`.
`trace_speed` `number`	Sets the speed of tracing execution. Value is the number of seconds to pause between steps. Default: 0.50.

The `dbx` Environment Variables and the Korn Shell

Each dbx environment variable is also accessible as a ksh variable. The name of the ksh variable is derived from the dbx environment variable by prefixing it with DBX_. For example dbxenv stack_verbose and echo $DBX_stack_verbose yield the same output. You can assign the value of the variable directly or with the dbxenv command.

Chapter 3 Customizing dbx

Using the dbx Initialization File

Creating a .dbxrc File