


      DBX(1)                      (bsd 4.2)                      DBX(1)



      NAME
           dbx - debugger

      SYNTAX
           dbx [ -r ] [ -i ] [ -I dir ] [ objfile ]

      DESCRIPTION
           Dbx is a source-level debugger and executor of rc(1), rf(1),
           and rp(1) object files.  If the compiler -g option is used,
           debugging may involve symbolic names.  If -g is omitted,
           only the machine-level facilities of dbx can be used.

           If no objfile is specified, ./a.out is used.  The object
           file contains a symbol table, which includes the name of all
           source files translated by the compiler to create it.  These
           files are available for perusal while using the debugger.

           If the file .dbxinit exists in the current directory when
           dbx is started, the debugger commands in it are executed in
           order.  Dbx also checks for a .dbxinit in the user's home
           directory if there isn't one in the current directory.

           The options are:

           -r     Execute objfile immediately.  If it terminates
                  normally, dbx exits.  Otherwise, report the reason
                  for termination and offer the user the option of
                  entering the debugger or letting the program fault.
                  Dbx reads from /dev/tty when -r is specified and
                  standard input is not a terminal.

           -i     Force dbx to act as though standard input is a
                  terminal.

           -I dir Add 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.


           Unless -r is specified, dbx just prompts and waits for a
           command.

           Execution and Tracing Commands


           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.  If objfile has been
                written since the last time the symbolic information



      Page 1                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



                was read in, dbx reads in the new information.

           trace [in procedure/function] [if condition]
           trace source-line-number [if condition]
           trace procedure/function [in procedure/function] [if condition]
           trace expression at source-line-number [if condition]
           trace variable [in procedure/function] [if condition]
                Trace during execution.  A number is associated with
                each trace.  This number may be used to turn the
                tracing off (see the delete command).

                The first argument describes what is to be traced.  If
                it is a source-line-number, then the line is printed
                immediately before being executed.  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, e.g.
                "mumble.c":17.






































      Page 2                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



                If the argument is a procedure or function name then
                every time it is called, information is printed 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
                then the value it is returning is also printed.

                If the argument is an expression with an at clause then
                the value of the expression is printed whenever the
                identified source line is reached.

                If the argument is a variable then the name and value
                of the variable is printed whenever it changes.
                Execution is substantially slower during this form of
                tracing.

                TRACE with no arguments causes every line to print
                before execution.  This is pretty slow going.

                The clause ``in procedure/function'' restricts tracing
                information to be printed only while executing inside
                the given procedure or function.

                Condition is a boolean expression that is evaluated
                before printing the trace information.

           stop if condition
           stop at source-line-number [if condition]
           stop in procedure/function [if condition]
           stop variable [if condition]
                Stop execution when the given line is reached,
                procedure or function called, variable changed, or
                condition true.

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

           delete command-number [,command-number ...]
                Remove the trace or stop corresponding to command-
                number.  The numbers associated with traces and stops
                are printed by the status command.

           catch number
           ignore number
                Start or stop trapping signal number before it is sent
                to the program.  This is useful when a program being
                debugged handles signals such as interrupts.  Initially
                all signals are trapped except SIGCONT, SIGCHILD,
                SIGALRM and SIGKILL.

           cont Continue execution from where it stopped.  Execution
                cannot be continued if the process has ``finished'',



      Page 3                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



                that is, called the standard procedure ``exit''.  Dbx
                does not allow the process to exit, thereby letting the
                user to examine the program state.

           step Execute one program line.

           next Execute up to the next source line, even if there is a
                procedure or function call between here and there.


           Displaying and Naming Data


           print expression [, expression ...]
                Print out the values of the expressions.  Array
                expressions are always subscripted by brackets (``[
                ]'').  Variables having the same identifier as one in
                the current block may be referenced as ``block-
                name . variable''.  The field reference operator
                (``.'') can be used with pointers as well as records,
                making the C operator ``->'' unnecessary.  The
                construct expression\typename can be used to print the
                expression out in the format of the named type.

           whatis name
                Print the declaration of the given name, which may be
                qualified with block names as above.

           which identifier
                Print the full qualification of the given identifier,
                i.e.  the outer blocks that the identifier is
                associated with.

           whereis identifier
                Print the full qualification of all the symbols whose
                name matches the given identifier.  The order in which
                the symbols are printed is not meaningful.

           assign variable = expression
           set variable = expression
                Assign the value of the expression to the variable.

           set address = expression
                Assign the value of the expression to memory location
                address.

           set $rn = expression
                Assign the value of the expression to machine register
                n.  n must be a value between 1 and 16.

           set $pc = expression
                Assign the value of expression to the program counter.



      Page 4                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



           call procedure(parameters)
                Execute the object code associated with the named
                procedure or function.  Currently, calls to a procedure
                with a variable number of arguments are not possible.
                Also, string parameters are not passed properly for C.

           where
                Print out the current chain (stack traceback).

           dump [> filename]
                Print the names and values of all active variables.


           Accessing Source Files


           edit [filename]
           edit procedure/function-name
                Invoke an editor on filename. Edit the current source
                file if filename is omitted.  If a procedure or
                function name is specified, edit the file that contains
                it.  The shell environment variable EDITOR specifies
                the editor to be invoked.

           file [filename]
                Change the current source file name to filename.  If
                filename is omitted, print the current source file
                name.

           func [procedure/function]
                Change the current function.  If none is specified then
                print the name of the current function.  Changing the
                current function implicitly changes the current source
                file to the one that contains the function; it also
                changes the current scope used for name resolution.

           list [starting-line-number [, limit]]
                List the lines in the current source file.  If no lines
                are specified, the next 10 lines are listed.
                starting-line-number specifies the first line to be
                listed.  If limit is not specified, then only one line
                is listed.  If limit < starting-line-number, then limit
                specifies the number of lines to list.  If limit >
                starting-line-number, then limit specifies the line
                number of the last line to list.

           list procedure/function
                List 10 lines, starting with the first named statement
                in the procedure or function.

           use [directory-list]
                Set the list of directories to be searched when looking



      Page 5                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



                for source files.  If no directory-list is provided,
                the current directory-list is printed.


           Machine-Level Commands


           dr   Display machine registers, program counter, and process
                id number.

           tracei [address] [if cond]
           tracei [variable] [at address] [if cond]
           stopi [address] [if cond]
           stopi [at] [address] [if cond]
                Turn on tracing or set a stop using a machine
                instruction address.

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

           address ,address/ [mode]
           [address] / [count] [mode]
                Print the contents of memory starting at the first
                address and continuing up to the second address or
                until count items are printed.  If no address is
                specified, the address following the one printed most
                recently is used.  The mode specifies how memory is to
                be printed; if it is omitted the previous mode
                specified is used.  The initial mode is ``X''.  The
                following modes are supported:

                i    print the machine instruction
                d    print a short word in decimal
                D    print a long word in decimal
                o    print a short word in octal
                O    print a long word in octal
                x    print a short word in hexadecimal
                X    print a long word in hexadecimal
                b    print a byte in octal
                c    print a byte as a character
                s    print a string of characters terminated by a null
                     byte
                f    print a single precision real number
                g    print a double precision real number


           Symbolic addresses are specified by preceding the name with
           an ``&''.  Registers are denoted by ``$rN'' where N is the
           number of the register.  The program counter is denoted by
           ``$pc''.  Addresses may be expressions made up of other



      Page 6                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



           addresses and the operators ``+'', ``-'', and indirection
           (unary ``*'').  The program counter is denoted by ``$pc.''


           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 old-command-name
                Respond to new-command-name as though it were old-
                command-name.  Use this to make inconveniently long
                command names shorter.

           help Print a synopsis of dbx commands.

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

           cnv integer
                convert number to decimal, hex, and octal.  Number can
                be in any one of these formats.

           address address
                print the line number corresponding to address.

           address at line-num
                print the address corresponding to line-num.

           quit Exit dbx.

      FILES
           a.out object file

      SEE ALSO
           rc(1) in The Bull-SPS9 RISC-Optimized C Compiler Manual.
           rf(1) in The Bull-SPS9 RISC-Optimized FORTRAN Compiler
           Manual.
           rp(1) in The Bull-SPS9 RISC-Optimized Pascal Compiler
           Manual.

      BUGS
           Non-local gotos (setjmp and longjmp) can cause some
           trace/stops to be missed.

           At a C switch statement, the step command may take you to



      Page 7                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



           the bottom of the switch.  Another step will take you to the
           proper case in the switch.

           At a FORTRAN computed goto, the step command may take you to
           the bottom of the computed goto.  Another step will take you
           to the computed destination line.

           At a Pascal while or repeat statement, the step command will
           take you to the end of the loop.  Another step will take you
           to the first statement in the loop.

           If a register declaration is used to force a parameter into
           a register, dbx has two addresses for the variable.  In this
           situation, dbx will be confised about which one is which and
           may not print or set the values of the register correctly.








































      Page 8                                          (73 A2 02MT REV1)






      DBX(1)                      (bsd 4.2)                      DBX(1)



           Dbx suffers from a ``multiple include'' malady.  If you have
           a program consisting 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 about one debugger start-up is done
           for each link, having the linker (ld) re-organize the symbol
           information won't save much time, though it would reduce
           some of the disk space used.  The problem is an artifact of
           the unrestricted semantics of C #include statements. For
           example, an include file can contain static declarations
           that are separate entities for each file in which they are
           included.

           If you step to enter a function or subroutine, an accurate
           stack traceback may not be possible until another step is
           used. Use stop in function to avoid this problem.

           If Dbx leaves a trap instruction in the executable file, the
           program must be re-linked.

           stop in function sometimes requires the function name to be
           fully qualified.  For example, to stop in function fun of
           file file.c, you may need to enter: stop in file.fun.
































      Page 9                                          (73 A2 02MT REV1)



