NAME

dbx − debugger

SYNOPSIS

dbx [ −r ] [ −i ] [ −I dir ] [ objfile [ corefile ]]

DESCRIPTION

Dbx is a tool for source-level debugging and execution of programs.    It accepts the same commands as dbxtool (1), but provides a user interface which does not use the window system. 

Objfile is an object file produced by cc(1), f77(1) and pc(1) (or a combination of them) with the appropriate flag (−g) specified to produce symbol information in the object file.  IMPORTANT: every stage of the compilation process, including the ld phase, must include the −g option. 

If no objfile is specified, one uses the debug command to specify the program to be debugged.  The object file contains a symbol table which includes the names of all the source files translated by the compiler to create it.  These files are available for perusal while using the debugger. 

If a file named core exists in the current directory or a corefile is specified, dbx can be used to examine the state of the program when it faulted. 

Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current directory. 

OPTIONS

−rExecute 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 user response.  Dbx reads from /dev/tty when −r is specified and standard input is not a terminal. 

−iForce dbx to act as though standard input is a terminal. 

−I dirAdd dir to the list of directories that are searched when looking for a source file.  Normally dbx looks for source files in the current directory and in the directory where objfile is located.  The directory search path can also be set with the use command. 

DBX AND DBXTOOL COMMON USER INTERFACE

The following material concerning the user interface applies to both dbx and dbxtool.  Note that commands, toolenv, button, and unbutton affect only dbxtool; they are described in the dbxtool (1) manual entry.  The commands described below are divided into the following categories:

Execution and Tracing
Run the program being debugged, trace its execution, and stop at selected places.

Displaying and Naming Data
Display data and locate variables in the debugged program.

Accessing Source Files
Provide operations (such as editing) on the actual source text of the program.

Machine Level Commands
Provide access to memory locations and machine registers.

Miscellaneous
Miscellaneous commands such as help, and call a shell. 

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 for displaying variables, and stop for setting breakpoints. 

File Names

File names within 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.  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. 

Dbx recognizes these operators:

+    −    ∗    /    div    %
add, subtract, multiply, divide, integer divide and remainder

<<    >>    &    |    ~
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, greater than or equal, equal to, not equal to, and not

&&    ||
logical and, and logical or

sizeof  (cast)
sizeof variable or type, and type cast

The field reference operator (‘.’) can be used with pointers to records, as well as records, making the C operator ‘−>’ unnecessary (although it is supported). 

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

Of course, if the program being debugged is not active and there is no core file, one may only use expressions containing constants.  Procedure calls require an active child process. 

Dbx and FORTRAN

Note the following when using dbx with FORTRAN programs:

1.Array elements must be referenced with square brackets ‘[’ and ‘]’ rather than parentheses, e.g., print whatsit[3] instead of print whatsit(3). 

2.The main routine is referenced as MAIN (as distinguished from ‘main’).  All other names in the source file which have upper case letters in them will be lower case in dbx, unless the −U option of f77 is used to compile the program. 

3.When referring to the value of a logical type in an expression, use the value 0 or 1 rather than false or true, respectively. 

Dbx Scope Rules

Dbx has two external variables which it uses to resolve scope conflicts.  These are called ‘file’ and ‘func’ — see Section 3 below, Accessing Source Files.  The values of ‘file’ and ‘func’ change automatically as files and routines are entered and exited during execution of the user program.  ‘File’ and ‘func’ can also be changed by the user.  Changing ‘func’ also changes the value of ‘file’; however, changing ‘file’ does not change ‘func’.

‘Func’ is used for name resolution, as in the command: print  grab where grab may be defined in two different routines.  The search order is:

1.Search for ‘grab’ in the routine named by ‘func’,

2.If ‘grab’ doesn’t exist in the routine named by ‘func’, the file containing the routine named by ‘func’ is searched,

3.finally the next outer level — the whole program in the case of C and FORTRAN — is searched for ‘grab’. 

Clearly, if ‘grab’ is local to a different routine than the one named by ‘func’, or is a static variable in a different file than is the routine named by ‘func’, it won’t be found.  Note, however, that print  a.grab is allowed, as long as routine ‘a’ has been entered but not exited yet.  Note that the file that routine ‘a’ is in might have to be specified when the file name (minus its suffix) is the same as a routine name.  For example, if routine ‘a’ is found in module ‘a.c’, then print  a.grab would be not enough — one would have to use print  a.a.grab.  If in doubt as to how to specify a name, use the whereis command, as in whereis  grab to display the full qualifications of all instances of the specified name (grab in this case). 

‘File’ is used to:

1.resolve conflicts when setting ‘func’ — for example, when a C program has two static routines with the same name,

2.determine which file to use for commands which take only a source line number — for example, stop  at  55, and:

3.determine which file to use for commands such as the ‘edit’ command which has optional arguments or no arguments at all. 

When dbx begins execution, the value of ‘file’ is the first source file in the compiler/load list and the value of ‘func’ is the module for this same file (that is, without the suffix ‘.c’, ‘.f’ or ‘.p’).  This causes name resolution to take place on a global level, that is, names are resolved such that the most global element is found.  After execution begins, however, ‘func’ always has a value corresponding to a routine name. 

Note that changing ‘func’ doesn’t affect the place where dbx continues execution when the program is restarted. 

1. Execution and Tracing Commands

When the process being debugged is executing, it may be interrupted by typing the interrupt character.  The process is stopped and dbx becomes ready to accept commands. The process can be continued again with the cont command. 

run  [args]  [< filename]  [> filename]
Start executing objfile, passing args as command line arguments; < or > can be used to redirect input or output in the usual manner.  Otherwise, all characters in args are passed through unchanged.  If no arguments are specified, the argument list in the last previous run command (if any) is used.  If objfile has been written since the last time the symbolic information was read in, dbx reads in the new information. 

cont   [at source-line-number]  [number]
Continue execution from where it stopped, or, if the clause ‘at source-line-number’ is given, from that line number.  The number causes execution to continue as if that signal had occurred. 

Source-line-number is evaluated relative to the current ’file’ and must be within the current procedure/function.  Execution cannot be continued if the process has ’finished’, i.e., called the standard procedure ’_exit’.  Dbx captures control when the process attempts to exit, thereby letting the user examine the program state. 

trace  [in procedure/function]  [if condition]

trace source-line-number  [if condition]

trace procedure/function  [if condition]

trace expression at source-line-number  [if condition]

trace variable  [in procedure/function]  [if condition]
Display tracing information when the program is executed.  A number is associated with the command and can be used to turn the tracing off (see the delete command). 

If no argument is specified, each source line is displayed before it is  executed.  Execution is substantially slower during this form of tracing. 

The clause ‘in procedure/function’ restricts tracing information to be displayed only while executing inside the given procedure or function.  Note that the ‘procedure/function’ traced must be visible in the scope in which the trace command is issued — see the ‘func‘ command. 

Condition is a Boolean expression and is evaluated prior to displaying the tracing information; the information is displayed only if condition is true. 

The first argument describes what is to be traced.  The effects of different kinds of arguments are described below:

Source Line Number
Display the line immediately prior to executing it.  Source line numbers in a file other than the current one must be preceded by the name of the file in quotes and a colon, for example, "mumble.p":17.

Procedure or Function Name
Every time the procedure or function is called, display information telling what routine called it, from what source line it was called, and what parameters were passed to it.  In addition, its return is noted, and if it is a function, the return value is also displayed.

Expression
If the argument is an expression with an at clause, the value of the expression is displayed whenever the identified source line is reached. 

Variable
The name and value of the variable are displayed whenever the value changes. Execution is substantially slower during this form of tracing.

Tracing is turned off whenever the block in which it was turned on is exited.  For instance, if the program is stopped inside some procedure and tracing is invoked, the tracing will end when the procedure is exited.  To trace the whole program, tracing must be invoked before a run command is issued. 

stop at source-line-number  [if condition]

stop in procedure/function  [if condition]

stop variable  [if condition]

stop if condition
Stop execution when the given line is reached, procedure or function is called, variable is changed, or condition becomes true. Execution slows considerably when conditional stops are used, and is very slow when checking for a change in a variable.

when in procedure/function  { command; ...}

when at source-line-number  { command; ...}

when condition  { command; ...}
Execute the given dbx commands when the procedure or function is called, line number is reached, or condition is true. The braces and the semicolon separating the commands are required.

status  [> filename]
Display the currently active trace and stop commands. 

delete command-number [, ... command-number]

delete all
Remove the traces and/or stops corresponding to the given numbers, or all of them.  The status command displays the numbers associated with traces and stops. 

clear source-line-number
Clears ALL breakpoints at the given source line number.

catch number [, ... number]

ignore number [, ... number]
Start ("catch") or stop ("ignore") trapping the signals with the given numbers before they are sent to the program being debugged.  This is useful when a program being debugged handles signals such as interrupts.  Initially all signals are trapped except SIGHUP, SIGCONT, SIGCHILD, SIGALRM, SIGKILL, SIGSTP, and SIGWINCH. 

step [n]
Execute through the next n source lines and stop on the  (n+1)st such line.  If n is not specified, it is taken to be one.  Step into procedures and functions. 

next  [n]
Execute through the next n source lines and stop on the  (n+1)st such line.  If n is not specified, it is taken to be one.  Count procedure and function calls as single statements. 

When using conditions with the trace and stop commands, remember that variable names are resolved with respect to the current scope not the scope of the trace or stop command.  For example, if you are currently stopped in function foo and you issue the command stop in bar if x == 5, the variable x refers to x in function foo not in function bar.  The func command can be used to changed the scope before issuing a trace or stop command. 

2. Naming, Printing and Displaying Data

print expression  [, expression ...]
Print the values of the expressions. Expressions may involve function calls. If execution encounters any breakpoints, execution halts and the dbx command level is re-entered. A stack trace with the where command shows that the call originated from the dbx command level. 

Variables having the same identifier as one in the current block may be referenced as ‘block-name.variable’, where block-name is a unique identifier for a block.  For example, to access variable ‘c’ inside routine ‘a’ which is declared inside module ‘a.c’, one would have to use print  a.a.c to make the name ‘a’ unambiguous.  Use whereis to determine the fully qualified name of an identifier. 

display [expression  [, expression ...]]
Display the values of the expressions each time execution of the program being debugged stops.  In dbxtool, the expressions and their values appear in the display window.  The name qualification rules for print apply to display as well.  With no arguments, the display command prints a list of the expressions currently being displayed.

undisplay expression  [, expression ...]
Stop displaying the expressions and their values each time execution of the program being debugged stops.  The name qualification rules for print apply to undisplay as well. 

whatis identifier

whatis type
Print the declaration of the given identifier or type. The identifier may be qualified with block names as above. Types are useful to print all the members of a structure, union, or enumerated type. 

which identifier
Print the fully qualified form of the given identifier, that is, the outer blocks that the identifier is associated with.

whereis identifier
Print the fully qualified form of all the symbols whose names match the given identifier.  The order in which the symbols are displayed is not meaningful.

assign variable = expression

set variable = expression
Assign the value of the expression to the variable.  Currently no type conversion takes place if operands are of different types.

call procedure(parameters)
Execute the object code associated with the named procedure or function. If execution encounters any breakpoints, execution halts and the dbx command level is re-entered. A stack trace with the where command shows that the call originated from the dbx command level. 

If the source file that the routine is defined in was compiled with the -g flag, the number and types of parameters must match.  However, if C routines are called which are not compiled with the -g flag, dbx will not do parameter checking; the parameters are simply pushed onto the stack as given in the parameter list.  Currently, string and structure parameters are not passed properly for C and parameters greater than four bytes in length (for example, complex and double precision variables) and alternate return points are not passed properly for FORTRAN. 

where [n]
Display a list of the top n active procedures and functions on the stack.  If n is not specified, it displays all active procedures and functions. 

dump [func]
Display the names and values of all the local variables and parameters in func.  If func is not specified the current function is used. 

up [n]
Move up (towards "main") the call stack n levels.  If n is not specified, the default is one.  This command allows you to examine the local variables in functions other than the current one.  In dbxtool, the line containing the call is hilighted for one second. 

down [n]
Move down (towards the current stopping point) the call stack n levels.  If n is not specified, the default is one.  In dbxtool, the line containing the call is hilighted for one second. 

3. Accessing Source Files & Directories

edit  [filename]

edit procedure/function-name
Invoke an editor on filename or the current source file if none is specified.  If a procedure or function name is specified, the editor is invoked on the file that contains it.  Which editor is invoked by default depends on the installation.  The default can be overridden by setting the environment variable EDITOR to the name of the desired editor. 

file  [filename]
Change the current source file to filename.  Print the name of the current source file if no filename is specified. 

func  [procedure/function/program name]
Change the current function.  Print the current function if none is specified.  Changing the current function implicitly changes the current source file variable file to the one that contains the function; it also changes the current scope used for name resolution.  If the entire scope of the program is desired, the argument should be the object file name. 

list  [source-line-number  [, source-line-number]]

list procedure/function
List the lines in the current source file from the first line number through the second. If no lines are specified, the next 10 lines are listed. If the name of a procedure or function is given lines n−5 to n+5 are listed where n is the first statement in the procedure or function.  If the list command’s argument is a procedure or function, the scope for further listing is changed to that routine — use the file command to change it back. 

use [directory-list]
Set the list of directories to be searched when looking for source files. Print the current list of directories if no directory-list is given. 

cd [dirname]
Change dbx’s notion of the current directory to dirname.  With no argument, use the value of the HOME environment variable. 

pwdPrint dbx’s notion of the current directory. 

/string[/]
Search down the current file for the regular expression string.  The search begins with the line immediately after the current line and, if necessary, continues until the end of the file.  The matching line becomes the current line.  In dbxtool, the matching line is hilighted for one second. 

?string[?]
Search up the current file for the regular expression string.  The search begins with the line immediately before the current line and, if necessary, continues until the top of the file.  The matching line becomes the current line.  In dbxtool, the matching line is hilighted for one second. 

When dbx is searching for a source file, the value of ‘file’ and the ‘use’ directory search path is used.  The value of ‘file’ is appended to each directory in the ‘use’ search path until a file is found.  This file becomes the current file. 

Dbx knows the same file names that are given to the compilers.  For instance, if a file is compiled with the command % cc -c -g ../mip/scan.c then dbx knows of the file ../mip/scan.c, but it does not know of the file scan.c. 

4. Machine-Level Commands

tracei  [address]  [if cond]

tracei  [variable]  [at address]  [if cond]

stopi  [variable]  [if cond]

stopi  [at]  [address]  [if cond]
Turn on tracing or 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 address and continuing up to the second address or until count items have been displayed.  If no address is specified, the address following the one displayed most recently is used.  The mode specifies how memory is to be displayed; if it is omitted the last previously specified mode is used.  The initial mode is ‘X’.  The following modes are supported:

idisplay the machine instruction

ddisplay a word in decimal

Ddisplay a longword in decimal

odisplay a word in octal

Odisplay a longword in octal

xdisplay a word in hexadecimal

Xdisplay a longword in hexadecimal

bdisplay a byte in octal

cdisplay a byte as a character

sdisplay a string of characters terminated by a null byte

fdisplay a single precision real number

gdisplay a double precision real number

Symbolic addresses used in this context are specified by preceding a name with an ‘&’.  Registers are denoted by ‘$d0-$d7’ (data registers), ‘$a0-$a7’ (address registers), ‘$fp’ (frame pointer), ‘$sp’ (stack pointer), and ‘$pc’ (program counter).  Note that $fp is equivalent to register a6 and $sp is equivalent to register a7.  For example, to print the contents of all registers in hex, one would type “&$d0/20X” or “&$d0,&$a7/X”. To print the contents of register d0, one could also type “print $d0” (one cannot currently specify a range with print).  Addresses may be expressions made up of other addresses and the operators ‘+’, ‘−’, ‘∗’, and indirection (unary ‘∗’). 

5. 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 ala the C shell (csh(1)) also occurs.

help [command]

helpPrint a short message explaining command.  If no argument is given, display a synopsis of dbx commands. 

source
Read dbx commands from the given filename.  This is especially useful when the filename has been created by redirecting a status command from an earlier debugging session. 

quit
Exit dbx. 

dbxenv stringlen num

dbxenv
Set dbx attributes.  The only one currently supported is stringlen which controls the maximum number of characters printed for a “char ∗” variable in a C program.  The dbxenv command with no argument prints the attributes and their current values. 

debug [objfile [corefile]]
Terminate debugging of the current program (if any) and begin debugging the one found in objfile, without incurring the overhead of reinitializing dbx.  If no arguments are specified, the name of the program currently being debugged and its arguments is printed. 

kill
Terminate debugging of the current program, but leave dbx ready to debug another.  This is particularly useful to eliminate remains of a window program one was debugging without exiting the debugger or to allow the object file to be removed and remade without incurring a "text file busy" error message. 

Debugging Processes that Fork

Debugging a process that fork(2)s introduces unique problems. Dbx uses the ptrace(2) interface to fetch from and store into the debuggee. This interface requires that the debugger be the parent process of the debuggee. If the debuggee forks, the child of the fork is the grandchild of dbx and it cannot be debugged.  No breakpoints should be set in the code that is executed by the child of the fork.  If the child of the fork trips over a breakpoint, it will die. 

When the debuggee forks, it can still be debugged with a few caveats.  After the fork, there are two processes that are sharing the same text (code) space.  The kernel does not allow ptrace to write into a text space that is being used by more than one process.  This means the debuggee should not trip over any breakpoints while the child of the fork is still sharing its text space.  In most cases, the child of the fork will exec(2) a new program almost immediately. After the exec, it is safe for the debuggee to trip over breakpoints. Therefore, it is recommended that a sleep(2) of two or three seconds be placed in the debuggee immediately after the fork. This gives the child of the fork some time to exec a new program and get out of the way.

FILES

a.outdefault object file
coredefault core file
~/.dbxinitinitial commands

SEE ALSO

cc(1)C compiler
f77(1)FORTRAN compiler
pc(1)Pascal compiler

COMMENTS

Dbx suffers from a ‘multiple include’ malady.  If a program consists of a number of object files and each is built from source files that include header files, the symbolic information for the header files is replicated in each object file.  Since roughly debugger start-up is done for each link, having the linker (ld) reorganize the symbol information won’t save much time, though it does reduce the disk space used.  The problem is an artifact of the unrestricted semantics of #include’s in C; for example an include file can contain static declarations that are separate entities for each file in which they are included. 

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). 

The use command and -I option do not override the current directory if there is source by the same name in the current directory. 

Some operations behave differently in dbx than in C. 

•Dbx has two division operators — / always yields a floating point result and div always yields an integral result. 

•An array or function name does not imply the address of the array or function in dbx.  An array name implies the entire array, and a function name implies a call to the function with no arguments.  The address of an array can be obtained by taking the address of the array’s first element, and the address of function can be obtained by taking the address of the function’s name. 

Casts do not work with FORTRAN or Pascal. 

String and structure parameters are not passed properly for C and parameters greater than four bytes in length (for example, complex and double precision variables) and alternate return points are not passed properly for FORTRAN. 

Sun Release 2.0  —  Last change: 1 February 1985