Debugging a Program With dbx

Chapter 2 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 `.dbxrc` File

The dbx initialization file, .dbxrc, 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. Remember, if you customize dbx from the command line while you are debugging, those settings apply only to the current debugging session.

During startup, dbx searches for .dbxrc first. The search order is:

Current directory ./.dbxrc
Home directory $HOME/.dbxrc

If .dbxrc is not found, dbx prints a warning message and searches for .dbxinit (dbx mode).

The search order is:

Current directory ./.dbxinit
Home directory $HOME/.dbxinit

Creating a `.dbxrc` File

To suppress the warning message and create a .dbxrc file that contains common customizations and aliases, type in the command pane:

help .dbxrc>$HOME/.dbxrc

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

A Sample Initialization File

Here is a sample .dbxrc file:

dbxenv case input_case_sensitive false
catch FPE

The first line changes the default setting for the case sensitivity control. dbxenv refers to the set of debugging environment attributes. input_case_sensitive refers to the matching control. false is the control setting.

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.

`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 environemnt varaible by prefixing it with DBX_. For example

dbxenv stack_verbose

and

echo $DBX_stack_verbose

yield the same output.

Customizing `dbx` in Sun WorkShop

If you use dbx through the Dbx Commands window in Sun WorkShop Debugging as well as from the command line in a shell, you can customize dbx most effectively by taking advantage of the customization features in Sun WorkShop Debugging.

Setting Debugging Options

If you use dbx primarily in the Dbx Commands window in Sun WorkShop Debugging, you can and should set most dbx environment variables using the Debugging Options dialog box (see the Using Sun WorkShop manual and the "Customizing Your Debugging Environment" section in the Sun WorkShop online help).

When you set debugging options using the Debugging Options dialog box, the dbxenv commands for the corresponding environment variables are stored in the Sun WorkShop configuration file .workshoprc. When you start to debug a program in the Sun WorkShop Debugging window, any settings in your .dbxrc file that conflict with those in your .workshoprc take precedence.

Maintaining a Unified Set of Options

If you use dbx both from the command line in a shell and from within Sun WorkShop, you can create a unified set of options that customizes dbx for both modes:

In the Sun WorkShop Debugging window, choose Debug Æ Debugging Options.

Click Save as Defaults to make your current option settings your defaults.

Open your .dbxrc file in an editor window.

Near the top, add the line source $HOME/.workshoprc.

Move the relevant dbxenv commands to a location after the source line, or delete them, or comment them out.

Save the file.

Any changes made through the Debugging Options dialog box are now available to dbx through both Sun WorkShop and when running in a shell.

Maintaining Two Sets of Options

To maintain different options settings for running dbx within Sun WorkShop and from the command line in a shell, you can use the havegui variable in your .dbxrc file to conditionalize your dbxenv commands. For example:

 if $havegui
   then
      dbxenv follow_fork_mode ask
      dbxenv stack_verbose on
   else
       dbxenv follow_fork_mode parent
       dbxenv stack_verbose off

Storing Custom Buttons

Sun WorkShop Debugging includes the Button Editor for adding. removing, and editing buttons in the Custom Buttons window. You no longer need to use the button command to store buttons in your .dbxrc file. You cannot add buttons to, or remove buttons from, your .dbxrc file with the Button Editor.

You cannot permanently delete a button stored in your .dbxrc file with the Button Editor. The button will reappear in your next debugging session. You can remove such a button by editing your .dbxrc file.

Command Reference

To display the value of a specific variable::

dbxenv variable

To show all variables and their values:

dbxenv

To set the value of a variable:

dbxenv variable  value

Note -

Each variable has a corresponding ksh environment variable such as DBX_trace_speed. The variable may be assigned directly, or the dbxenv command may be used; they are equivalent.

Table 2-1 shows all of the dbx environment variables that you can set:

Table 2-1 dbx Environment Variables


`dbx` Environemnt Variable	What the Variable Does
`allow_critical_exclusion [on\|off]`	Normally `loadobject -x` disallows the exclusion of certain shared libraries critical to dbx functionality. By setting this variable to on that restriction is defeated. While this variable is on only corefiles can be debugged. Default: $DBX_allow_critical_exclusion
`aout_cache_size` `num`	Size of `a.out` loadobject cache; set this to `num` when debugging `num` programs serially from a single `dbx`. A `num` of zero still allows caching of shared objects. See entry for `locache_enable`. Default: 1
`array_bounds_check [on\|off]`	If on, `dbx` checks the array bounds. Default: on
`cfront_demangling [on\|off]`	Governs demangling of Cfront (SC 2.0 and SC 2.0.1) names while loading a program. It is necessary to set this parameter to `on` or start `dbx` with the `-F` option if debugging programs compiled with Cfront or programs linked with Cfront compiled libraries. If set to `off`, `dbx` loads the program approximately 15% faster. Default: off
`delay_xs [on\|off]`	Governs whether debugging information for modules compiled with the `-xs` option is loaded at `dbx` startup or delayed. Default: on
`disassembler_version [autodetect\|v8\|v9\|v9vis]`	SPARC: Set the version of `dbx`'s built-in disassembler for SPARC V8, V9, or V9 with the Visual Instruction set. Default is `autodetect`, which sets the mode dynamically depending on the type of the machine a.out is running on. Non-SPARC platforms: Only valid choice is `autodetect`.
`fix_verbose [on\|off]`	Governs the printing of compilation line during a `fix`. Default: off
`follow_fork_inherit [on\|off]`	When following a child, inherit or do not inherit events. Default: off
`follow_fork_mode ...`	When process executes a fork/vfork/fork1 ... Default: parent
`follow_fork_mode parent`	... stay with parent.
`follow_fork_mode child`	... follow child.
`follow_fork_mode both`	... follow both parent and child (Sun WorkShop only).
`follow_fork_mode ask`	... ask which of the above the user wants.
`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 77 or Fortran 90 files, otherwise `true`. If `true`, case matters in variable and function names; otherwise, case is not significant. Default: autodetect
`language_mode [autodetect\|main\|c\| ansic\|c++\|objc\|fortran\| fortran90\|native_java]`	Governs the language used for parsing and evaluating expressions. `autodetect`: sets to language of current file. Useful if debugging programs with mixed languages (default mode). `main`: sets language of the main routine in the program. Useful if debugging homogeneous programs. `c`, `c++`, `ansic`, `c++`, `objc`, `fortran`, `fortran90`, `native_java`: sets to selected language.
`locache_enable [on\|off]`	Enable or disable loadobject cache entirely. Default: on
`mt_watchpoints [on\|off]`	Allow or disallow watchpoint facility for multithreaded programs. Default: off. Warning: Be aware that when using watchpoints on a multithreaded program that the application may deadlock if a semaphore occurs on a page that is being watched.
`output_auto_flush [on\|off]`	Automatically call 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_dynamic_type [on\|off]`	When on, `-d` is the default for printing, displaying and inspecting. Default: off
`output_inherited_members [on\|off]`	When 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` `num`	Set # of chars printed for `char *`s. Default: 512
`output_pretty_print [on\|off]`	Sets `-p` as the default for printing, displaying and inspecting. Default: off.
`output_short_file_name [on\|off]`	Display short pathnames for files. Default: on
`overload_function [on\|off]`	For C++, if `on`, do automatic function overload resolution. Default: on
`overload_operator [on\|off]`	For C++, if `on`, do automatic operator overload resolution. Default: on
`pop_auto_destruct [on\|off]`	If `on`, automatically call appropriate destructors for locals when `pop`ping a frame. 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 `on`, an RTC error at a given location is reported only once. Default: off
`rtc_biu_at_exit [on\|off\|verbose]`	Used when `check -memuse` 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` `num`	Number of RTC errors to be reported. Default: 1000
`rtc_error_log_file_name` `filename`	Name of file where RTC errors are logged if `rtc_auto_continue` is set. Default: `/tmp/dbx.errlog.uniqueID`
`rtc_mel_at_exit [on\|off\|verbose]`	Used when leaks 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 `on` with no active program, `step`, `next`, `stepi`, and `nexti` implicitly run the program and stop at the language-dependent `main` routine. If `on`, `cont` implies `run` when necessary. Default: off
`run_io [stdio\|pty]`	Governs whether the user program's I/O is redirected to `dbx`'s `stdio` or a specific pty. The pty is provided via `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 GUI wrappers.
`run_quick [on\|off]`	If 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 debuggee; useful when debugging editors and shells. Try setting to `on` if dbx gets SIGTTIN or SIGTTOU and pops back into the shell. Try setting to `off` to gain a slight speed advantage. The setting is irrelevant if dbx is attached to the debugee or is running under Sun WorkShop. Default: on
`run_setpgrp [on\|off]`	If `on`, when a program is `run` `setgprp(2)`is called right after the fork. Default: off
`scope_global_enums [on\|off]`	If `on`, enumerators are put in global scope and not in file scope. Should be set before debugging information is processed (~/`.dbxrc`). Default: off
`scope_look_aside [on\|off]`	Find file static symbols, even when not in scope. Default: on
`session_log_file_name` `filename`	Name of file where `dbx` logs all commands and their output. Output is appended to the file. Default: "" (no session logging)
`stack_max_size` `num`	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_events [on\|off]`	Allows breakpoints while stepping and nexting.Default: off
`suppress_startup_message` n`um`	Sets the release level below which the startup message is not printed. Default: 3.01
`symbol_info_compression [on\|off]`	Reads debugging information for each `include` file only once. Default: on
`trace_speed` `num`	Sets the speed of tracing execution. Value is the number of seconds to pause between steps. Default: 0.50

Chapter 2 Customizing dbx

Using the .dbxrc File

Creating a .dbxrc File