DBX(1)

NAME
dbx - source-level debugger

SYNOPSIS
dbx [ -f fcount ] [ -i ] [ -Idir ] [ -k ] [ -kbd ]
[ -P fd ] [ -r ] [ -s startup ] [ -sr tstartup ]
[ objfile [ corefile | process-id ] ]

AVAILABILITY
This command is available with the Debugging software installation option. Refer to for information on how to install optional software.

DESCRIPTION

dbx is a utility for source-level debugging and execution of programs written in C, or other supported languages such as Pascal and FORTRAN 77. dbx accepts the same commands as dbxtool(1), but uses a standard terminal (tty) interface.

objfile is an object file, produced by cc(1V) or another compiler, with the -g option to include a symbol table. This symbol table contains the names of all the source files used to create it, and these files are available for perusal while using the debugger.

If no objfile is specified, you can use dbx's debug command to specify the program to debug.

If there is a file named core in the current directory, or a corefile argument is specified, you can use dbx to examine the state of the program when the core file was produced.

dbx commands in the file .dbxinit are executed immediately before the symbol table is read, if that file exists in the current directory, or in the user's home directory if .dbxinit does not exist in the current directory.

OPTIONS

-f fcount
    Alter the initial estimate of the number functions in the program being debugged. The initial setting is 500.

-i  Force dbx to act as though the standard input were a terminal or terminal emulator.

-I dir
    Add dir to the list of directories in which to search for a source file. dbx normally searches the current directory, and the directory where objfile is located. The directory search path can be reset with the use command.

-k  Kernel debugging.

-kbd
    Debug a program that sets the keyboard into up-down translation mode. This flag is necessary if a program uses up-down decoding.

-P fd
    Create a pipeline to a dbxtool(1) process. fd is the file descriptor through which to pipe output to the front-end process. This option is passed automatically to dbx by dbxtool.

-r  Execute objfile immediately. Parameters follow the object file name (redirection is handled properly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for termination and waits for a response. dbx reads from the terminal (/dev/tty) when -r is specified and standard input is a file or pipe.

-s startup
    Read initialization commands from the file named startup.

-sr tstartup
    Read initialization commands from the temporary file named startup, and then remove that file.

USAGE

Refer to dbx in the manual.

The most useful basic commands to know about are run, to run the program being debugged, where, to obtain a stack trace with line numbers, print, to display variables, and stop, to set breakpoints.

  Filenames
Filenames in dbx may include shell metacharacters. The shell used for pattern matching is determined by the SHELL environment variable.

  Expressions
dbx expressions are combinations of variables, constants, procedure calls, and operators. Variables are either variables in the program being debugged or special dbx variables whose names begin with $. Hexadecimal constants must be preceded by a `0x' and octal constants by a `0'. Character constants must be enclosed in single quotes. Expressions cannot involve strings, structures, or arrays, although elements of structures or arrays may be used.

  Operators

+   -   *   /   div   %
    Add, subtract, multiply, divide, integer division, and remainder, respectively.

    dbx has two division operators. `/' always yields a floating-point result and div always yields an integral result.

<<   >>    &   |   ~
    Left-shift, right-shift, bitwise AND, bitwise OR, and bitwise complement.

&   *
    Address of operator, and contents of operator.

<   >   <=   >=   ==   !=   !
    Less than, greater than, less than or equal to, greater than or equal to, equal, not equal, and negation.

&&   ||
    Logical AND, and logical OR

sizeof (cast)
    Size of variable or type and type cast.

.   ->
    Field reference, and pointed-to-field reference (however, dot works for both in dbx).

Precedence and associativity of operators are the same as for C; parentheses can be used for grouping.

If there is no corefile, only expressions containing constants are available. Procedure calls require an active child process.

  Scope Rules

dbx uses the current file and function to resolve scope conflicts. Their values are updated as files and functions are entered and exited during execution. You can also change them explicitly by using the file and func commands. When the current function is changed, the current file is updated along with it, but not vice versa.

  Execution and Tracing Commands

^C  Interrupt. Stop the program being debugged and enter dbx.

run [ args ] [ < infile ] [ >| >> outfile ]
Start executing objfile, reading in any new information from it. With no args, use the argument list from the previous run command.

        args
            Pass args as command-line arguments to the program.
        <|>|>>
            Redirect input or output, or append output to a file.

rerun [ args ] [ < infile ] [ >| >> outfile ]
Like the run command, except that when args are omitted, none are passed to the program.

cont [ at sourceline ] [ sig signal ]
Continue execution from where it stopped.

        at sourceline
            Start from sourceline
        sig signal
            Continue as if signal had occurred. signal may be a number or a name as with catch.

trace [ in function ] [ if condition ]
trace sourceline [ if condition ]
trace function [ if condition ]
trace expression at sourceline [ if condition ]
trace variable [ in function ] [ if condition ]
Display tracing information. If no argument is specified, each source line is displayed before execution. Tracing is turned off when the function or procedure is exited.

        in function
            Display tracing information only while executing the function or procedure function.
        if condition
            Display tracing information only if condition is true.
        sourceline
            Display the line immediately prior to executing it. Source line-numbers from another file are written as filename:n.
        function
            Display the routine and source line called from, parameters passed in, and return value.
        expression at sourceline
            Display the value of expression whenever sourceline is reached.
        variable
            Display the name and value whenever variable changes.

stop at sourceline [ if condition ]
stop in function [ if condition ]
stop variable [ if condition ]
stop if condition
Stop execution when the sourceline is reached, function is called, variable is changed, or condition becomes true.

when in function { command ; [ command ; ] ... }
when at sourceline { command ; [ command ; ] ... }
when condition { command ; [ command ; ] ... }
Execute the dbx command(s) when function is called, sourceline is reached, or condition is true.

status [ > filename ]
Display active trace, stop and when commands, and associated command numbers.

delete all
delete cmd-no [ , cmd-no ] ...
Remove all traces, stops and whens, or those corresponding to each dbx cmd-no (as displayed by status).

clear [ sourceline]
Clear all breakpoints at the current stopping point, or at sourceline.

catch [ signal [ , signal ] ... ]
Display all signals currently being caught, or catch signal before it is sent to the program being debugged. A signal can be specified either by name (with the SIG prefix omitted, as with kill(1)) or number. Initially all signals are caught except SIGHUP, SIGEMT, SIGFPE, SIGKILL, SIGALRM, SIGTSTP, SIGCONT, SIGCHLD, and SIGWINCH.

ignore [ signal [ , signal ] ... ]
Display all signals currently being ignored, or stop catching signal, which may be specified by name or number as with catch.

step [n]
    Execute the next n source lines. If omitted, n is taken to be 1. Steps into functions.

next [n]
    Execute the next n source lines. If omitted, n is taken to be 1. next steps past functions.

  Naming, Printing and Displaying Data

Variables from another function or procedure with the same name as one in the current block must be qualified as follows:

    [` sourcefile `] function` variable

For Pascal variables there may be more than one function or procedure name, each separated by a backquote.

print expression [ , expression ] ...
Print the value of each expression, which may involve function calls. Program execution halts when a breakpoint is reached, and dbx resumes.

display [ expression [ , expression ] ... ]
Print a list of the expressions currently being displayed, or display the value of each expression whenever execution stops.

undisplay [ expression [ , expression ] ... ]
Stop displaying the value of each expression whenever execution stops. If expression is a constant, it refers to a display-number as shown by the display command with no arguments.

whatis identifier
whatis type
    Print the declaration of the given identifier or type. types are useful to print all the members of a structure, union, or enumerated type.

which identifier
    Print the fully-qualified name of the given identifier.

whereis identifier
    Print the fully qualified name of all symbols matching identifier.

assign variable = expression
set variable = expression
Assign the value of expression to variable. There is no type conversion for operands of differing type.

set81 fpreg=word1 word2 word3
    Treat the concatenation of word1 word2 word3 as a 96-bit, IEEE floating-point value and assign it to the MC68881 floating-point register fpreg. (Supported only on Sun-3).

call function(parameters)
    Execute the named function. Arguments are passed according to the rules for the source-language of function.

where[ n]
    List all, or the top n, active functions on the stack.

dump [ function ]
Display the names and values of local variables and parameters in the current or specified function.

up [n]
down [n]
Move up (towards ``main'') or down the call stack, one or n levels.

  File Access Commands

edit [ filename | function ]
Edit the current source file, or the given filename or the file that contains function.

file [ filename ]
Print the name of the current source file, or change the current source file to filename.

func [ function| program | objfile ]
Print the name of the current function, or change to the given function, program, or objfile. Also changes the current scope.

list [ startline [ , endline ] ]
list function
List the next ten lines from current source file, list from startline through endline, or and list from five lines above, to five lines below the first line of function.

use [ directory-list ]
Print or set the list of directories in which to search for source files.

cd [ directory ]
Change the current working directory for dbx to directory (or to the value of the HOME environment variable).

pwd Print the current working directory for dbx.

/reg-exp[/]
?reg-exp [?]
Search the current file for the regular expression reg-exp, from the next (previous) line to the end (top). The matching line becomes the new current line.

  Miscellaneous Commands

sh command-line
    Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used.

alias new-command-name character-sequence
Respond to new-command-name as though it were character-sequence. Special characters occurring in character-sequence must be enclosed in quotation marks. Alias substitution as with the C shell (csh(1)) also occurs.

help [ command ]
Display a synopsis of dbx commands, or print a short message explaining command.

make
    Invoke make(1) with the name of the program as its argument. Any arguments set using dbxenv makeargs are also passed as arguments.

setenv name string
Set environment variable name to string.

source filename
Read and execute dbx commands from filename. Useful when the filename has been created by redirecting an earlier status command.

quit
    Exit dbx.

dbxenv
dbxenv case sensitive | insensitive
dbxenv fpaasm on | off
dbxenv fpabase a[0-7] | off
dbxenv makeargs string
dbxenv stringlen num
dbxenv speed seconds
Display dbx attributes or set the named attribute:

        case
            Controls whether upper- and lower-case characters are treated as different values. The default is sensitive.
        fpaasm
            Controls FPA instruction disassembly. The default is on. (Supported only on Sun-3).
        fpabase
            Sets the base register for FPA instruction disassembly. The default is off. (Supported only on Sun-3 systems).
        makeargs
            Sets arguments to pass to make. The default is CC=cc -g.
        speed
            Set the interval between execution during tracing. The default is 0.5 seconds.
        stringlen
            Controls the maximum number of characters printed for a ``char *'' variable in a C program. The default is 512.

debug [ -k ] [ objfile [ corefile | pid ] ]
With no arguments, print the name of the current program. With arguments, stop debugging the current program and begin debugging objfile having either corefile or the current process ID pid. The -k option indicates kernel debugging.

kill
    Stop debugging of the current program, but be ready to debug another.

detach
    Detach the current program (process) from dbx. dbx will be unable to access or modify its state.

modules
modules select [ all| objfile... ]
modules append objfile [ objfile... ]
The modules command displays or sets the current modules selection list. If the modules selection list is set, the debugger reads debugging information only for object files in this list. Debugging information for object files not in the modules selection list is ignored.

    modules with no arguments displays the set of object files for which source level debugging information is currently available, including the path names of any associated source files. If the debugger cannot access a source file for which it has debugging information, it displays the source file name with a trailing `?' (question mark) character. Source file path names reflect the current search path as set by the use command or the -I option.

    modules select displays the current modules selection list if no objfile is given. Otherwise, modules select sets the modules selection list to the specified object files. To get complete debugging information, the debugger may need to read object files not in the modules selection list. `modules select' displays these “implied” file names with trailing `*' (asterisk) characters (see NOTES). `modules select all' discards the modules selection list.

    modules append appends the specified object files to the modules selection list.

    If the modules selection list includes an object file not in the executable being debugged, the debugger issues a warning.

proc [ pid ]
For kernel debugging. Display which process is mapped into the user area, or map pid to the user area.

  Machine-Level Commands

tracei [ address ] [ if condition ]
tracei [ variable ] [at address ] [ if condition ]
Trace execution of a specific machine-instruction address.

stopi [ variable ] [ if condition ]
stopi [at address ] [ if condition ]
Set a breakpoint at a machine instruction address.

stepi
nexti
    Single step as in step or next, but do a single machine instruction rather than a source line.

address,address / [ mode ]
address / [count ] [ mode ]
Display the contents of memory starting at the first (or current) address up to the second address, or until count items have been displayed. The initial display mode is X. The following modes are supported:

        i   the machine instruction
        d   word in decimal
        D   longword in decimal
        o   word in octal
        O   longword in octal
        x   word in hexadecimal
        X   longword in hexadecimal
        b   byte in octal
        c   byte as a character
        s   strings as characters terminated by a null
        f   single precision real number
        F   double-precision real number
        E   extended-precision real number (not supported on Sun-4)

    An address can be specified as an item from the following list, as an expression made up of other addresses and the operators `+', `-', `*', and indirection (unary `*'), or as an arbitrary expression enclosed in parentheses.

        &name
            symbolic address
        integer
            numeric address

address = [ mode ]
Display the value of the address.

  Machine Registers
The machine registers for the current machine type are represented as special dbx variables. They can be used in expressions as any other dbx variable can. The registers and their variable names are:

  Sun-2 and Sun-3 Registers

    $d[0-7]
        data registers
    $a[0-7]
        address registers
    $fp frame pointer, equivalent to register a6
    $sp stack pointer, equivalent to register a7
    $pc program counter
    $ps program status

  Sun-3-Only Registers

    $fp[0-7]
        MC68881 data registers
    $fpc
        MC68881 control register
    $fps
        MC68881 status register
    $fpi
        MC68881 instruction address register
    $fpf
        MC68881 flags register (unused, idle, busy)
    $fpa[0-31]
        double-precision interpretation of FPA registers.
    $sfpa[0-31]
        single-precision interpretation of FPA registers.

  Sun-4 Registers

    $g[0-7]
        global registers
    $o[0-7]
        ``out'' registers
    $i[0-7]
        ``in'' registers
    $l[0-7]
        ``local'' registers
    $fp frame pointer, equivalent to register i6
    $sp stack pointer, equivalent to register o6
    $y  Y register
    $psr
        processor state register
    $wim
        window invalid mask register
    $tbr
        trap base register
    $pc program counter
    $npc
        next program counter
    $f[0-31]
        FPU ``f'' registers
    $fsr
        FPU status register
    $fq FPU queue

  Sun386i Registers

    $ss stack segment register
    $eflags
        flags
    $cs code segment register
    $eip
        instruction pointer
    $eax
        general register
    $ecx
        general register
    $edx
        general register
    $ebx
        general register
    $esp
        stack pointer
    $ebp
        frame pointer
    $esi
        source index register
    $edi
        destination index register
    $ds data segment register
    $es alternate data segment register
    $fs alternate data segment register
    $gs alternate data segment register

Registers for the 80386 lower halves (16 bits) are:

    $ax general register
    $cx general register
    $dx general register
    $bx general register
    $sp stack pointer
    $bp frame pointer
    $si source index register
    $di destination index register
    $ip instruction pointer, lower 16 bits
    $flags
        flags, lower 16 bits

The first four Sun386i 16-bit registers can be split into 8-bit parts:

    $al lower (right) half of register $ax
    $ah higher (left) half of register $ax
    $cl lower (right) half of register $cx
    $ch higher (left) half of register $cx
    $dl lower (right) half of register $dx
    $dh higher (left) half of register $dx
    $bl lower (right) half of register $bx
    $bh higher (left) half of register $bx
Registers for the 80387 are:
    $fctrl
        control register
    $fstat
        status register
    $ftag
        tag register
    $fip
        instruction pointer offset
    $fcs
        code segment selector
    $fopoff
        operand pointer offset
    $fopsel
        operand pointer selector
    $st0 - $st7
        data registers

ENVIRONMENT
dbx checks the environment variable EDITOR for the name of the text editor to use with the edit command.

FILES
core
    default core file
.dbxinit
    local dbx initialization file
~/.dbxinit
    user's dbx initialization file

SEE ALSO
cc(1V), csh(1), dbxtool(1), kill(1), lex(1), make(1), yacc(1)

NOTES

Because the cc command does not generate or support 8-bit symbol names, it is inappropriate to make dbx 8-bit clean. See cc(1V) for an explanation about why cc is not 8-bit clean.

To save space, the linker eliminates debugging information redundantly defined in multiple include files. If the linker excluded some of the symbols for an object file in the modules selection list, the debugger must read debugging information from the object files where these symbols were first defined. If these “implied” modules are not in the modules selection list, `modules select' displays their names with trailing `*' (asterisk) characters.

BUGS

dbx does not correctly handle C variables that are local to compound statements. When printing these variables it often gives incorrect results.

dbx does not handle FORTRAN entry points well — it treats them as if they were independent routines.

dbx does not handle assigning to FORTRAN complex types correctly (see the assign/set command).

Unlike C, dbx does not recognize an array or function name as the address of the array or function. In dbx, an array name signifies the entire array, and a function name signifies a call to the function with no arguments. To get the address of an array, take the address of its first element. To get the address of a function, take the address of its name.

Casts do not work with FORTRAN 77 or Pascal.

Executable code incorporated into a source file using an #include preprocessor directive confuses dbx.

dbx is confused by the output of program generators such as yacc(1) and lex(1).

A step command issued at a procedure call will not work properly when debugging information is available for the function being called and that function is in a shared library.