dbx man page on 4.4BSD

Man page or keyword search:  
man Server   1065 pages
apropos Keyword Search (all sections)
Output format
4.4BSD logo
[printable version]

DBX(1)			  BSD General Commands Manual			DBX(1)

     dbx — debugger

     Dbx [-r] [-i] [-k] [-I dir] [-c file] [objfile [coredump]]

     Dbx is a tool for source level debugging and execution of programs under
     UNIX.  The objfile is an object file produced by a compiler with the
     appropriate flag (usually -g) specified to produce symbol information in
     the object file.  Currently, cc(1), f77(1), pc(1), and the DEC Western
     Research Laboratory Modula-2 compiler, mod(l), produce the appropriate
     source information.  The machine level facilities of dbx can be used on
     any program.

     The object file contains a symbol table that 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 coredump file
     is specified, dbx can be used to examine the state of the program when it

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

     The command line options and their meanings are:

     -r	     Execute objfile immediately.  If it terminates successfully dbx
	     exits.  Otherwise the reason for termination will be reported and
	     the user offered the option of entering the debugger or letting
	     the program fault.	 Dbx will read from /dev/tty when -r is speci‐
	     fied and standard input is not a terminal.

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

     -k	     Map memory addresses, useful for kernel debugging.

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

     -c file
	     Execute the dbx commands in the file before reading from standard

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

   Execution and Tracing Commands
     run [args] [< filename] [> filename]
     rerun [args] [< filename] [> filename]
	     Start executing objfile, passing args as command line arguments;
	     < or > can be used to redirect input or output in the usual man‐
	     ner.  When rerun is used without any arguments the previous argu‐
	     ment list is passed to the program; otherwise it is identical to
	     run.  If objfile has been written since the last time the sym‐
	     bolic information was read in, dbx will read in the new informa‐

     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]
	     Have tracing information printed when the program is executed.  A
	     number is associated with the command that is 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 prior to
	     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.p":17.

	     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's 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 substan‐
	     tially slower during this form of tracing.

	     If no argument is specified then all source lines are printed
	     before they are executed.	Execution is substantially slower dur‐
	     ing this form of tracing.

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

	     Condition is a boolean expression and is evaluated prior to
	     printing the tracing information; if it is false then the infor‐
	     mation is not printed.

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

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

     delete command-number ...
	     The traces or stops corresponding to the given numbers are
	     removed.  The numbers associated with traces and stops are
	     printed by the status command.

     catch number
     catch signal-name
     ignore number
     ignore signal-name
	     Start or stop trapping a signal before it is sent to the program.
	     This is useful when a program being debugged handles signals such
	     as interrupts.  A signal may be specified by number or by a name
	     (e.g., SIGINT).  Signal names are case insensitive and the “SIG”
	     prefix is optional.  By default all signals are trapped except

     cont integer
     cont signal-name
	     Continue execution from where it stopped.	If a signal is speci‐
	     fied, the process continues as though it received the signal.
	     Otherwise, the process is continued as though it had not been

	     Execution cannot be continued if the process has ``finished'',
	     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 source line.

     next    Execute up to the next source line.  The difference between this
	     and step is that if the line contains a call to a procedure or
	     function the step command will stop at the beginning of that
	     block, while the next command will not.

     return [procedure]
	     Continue until a return to procedure is executed, or until the
	     current procedure returns if none is specified.

     call procedure(parameters)
	     Execute the object code associated with the named procedure or

   Printing Variables and Expressions
     Names are resolved first using the static scope of the current function,
     then using the dynamic scope if the name is not defined in the static
     scope.  If static and dynamic searches do not yield a result, an arbi‐
     trary symbol is chosen and the message “[using qualified name]” is
     printed.  The name resolution procedure may be overridden by qualifying
     an identifier with a block name, e.g., “module.variable” For C, source
     files are treated as modules named by the file name without ``.c''.

     Expressions are specified with an approximately common subset of C and
     Pascal (or equivalently Modula-2) syntax.	Indirection can be denoted
     using either a prefix ``*'' or a postfix ``^'' and array expressions are
     subscripted by brackets (“[]”) The field reference operator (``.'') can
     be used with pointers as well as records, making the C operator ``->''
     unnecessary (although it is supported).

     Types of expressions are checked; the type of an expression may be over‐
     ridden by using “type-name(expression)”.  When there is no corresponding
     named type the special constructs “&type-name” and “$$tag-name” can be
     used to represent a pointer to a named type or C structure tag.

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

     dump [procedure] [> filename]
	     Print the names and values of variables in the given procedure,
	     or the current one if none is specified.  If the procedure given
	     is ``.'', then the all active variables are dumped.

     print expression [, expression ...]
	     Print out the values of the expressions.

     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 identifer, i.e.	the
	     outer blocks that the identifier is associated with.

     up [count]
     down [count]
	     Move the current function, which is used for resolving names, up
	     or down the stack count levels.  The default count is 1.

     where   Print out a list of the active procedures and function.

     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.

   Accessing Source Files
     / regular expression[/]
     ? regular expression[]?
	     Search forward or backward in the current source file for the
	     given pattern.

     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 name to filename.  If none is
	     specified then the current source file name is printed.

     func [procedure/function]
	     Change the current function.  If none is specified then print 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 resolu‐

     list [source-line-number [, source-line-number]]
     list procedure/function
	     List the lines in the current source file from the first line
	     number to the second inclusive.  If no lines are specified, the
	     next 10 lines are listed.	If the name of a procedure or function
	     is given lines n-k to n+k are listed where n is the first state‐
	     ment in the procedure or function and k is small.

     use directory-list
	     Set the list of directories to be searched when looking for
	     source files.

   Command Aliases and Variables
     alias name name
     alias name string
     alias name (parameters) “string”
	     When commands are processed, dbx first checks to see if the word
	     is an alias for either a command or a string.  If it is an alias,
	     then dbx treats the input as though the corresponding string
	     (with values substituted for any parameters) had been entered.
	     For example, to define an alias ``rr'' for the command ``rerun'',
	     one can say

		   alias rr rerun

	     To define an alias called ``b'' that sets a stop at a particular
	     line one can say

		   alias b(x) ``stop at x''

	     Subsequently, the command ``b(12)'' will expand to ``stop at

     set name [= expression]
	     The set command defines values for debugger variables.  The names
	     of these variables cannot conflict with names in the program
	     being debugged, and are expanded to the corresponding expression
	     within other commands.  The following variables have a special

		   Setting this variable to an address causes dbx to use the
		   stack frame pointed to by the address for doing stack
		   traces and accessing local variables.  This facility is of
		   particular use for kernel debugging.

		   When set, dbx prints out out characters, integers, offsets
		   from registers, or character pointers respectively in hexa‐

		   The value of this variable specifies the number of lines to
		   list around a function or when the list command is given
		   without any parameters.  Its default value is 10.

		   Setting (unsetting) this variable causes dbx to start
		   (stop) mapping addresses.  As with ``$frame'', this is use‐
		   ful for kernel debugging.

		   When ``$unsafecall'' is set, strict type checking is turned
		   off for arguments to subroutine or function calls ( e .g.
		   in the call statement).  When ``$unsafeassign'' is set,
		   strict type checking between the two sides of an assign
		   statement is turned off.  These variables should be used
		   only with great care, because they severely limit dbx's
		   usefulness for detecting errors.

     unalias name
	     Remove the alias with the given name.

     unset name
	     Delete the debugger variable associated with name.

   Machine Level Commands
     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

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

     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 the address is ``.'', 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 fol‐
		 lowing 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.
     Addresses may be expressions made up of other addresses and the operators
     ``+'', ``-'', and indirection (unary ``*'').

   Miscellaneous Commands
     gripe   Invoke a mail program to send a message to the person in charge
	     of dbx.

     help    Print out a synopsis of dbx commands.

     quit    Exit dbx.

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

     source filename
	     Read dbx commands from the given filename.

     Dbx examines the following environment variables:

     a.out     Object file.
     .dbxinit  Initial commands.

     cc(1), mod(l), f77(1), pc(1)

     The dbx command appeared in 4.2BSD.

     Dbx suffers from the same ``multiple include'' malady as did sdb.	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(1) re-orga‐
     nize the symbol information would not save much time, though it would
     reduce some of the disk space used.

     This 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.  However,
     even with Modula-2 there is a substantial amount of duplication of symbol
     information necessary for inter-module type checking.

     Some problems remain with the support for individual languages.  Fortran
     problems include: inability to assign to logical, logical*2, complex and
     double complex variables; inability to represent parameter constants
     which are not type integer or real; peculiar representation for the val‐
     ues of dummy procedures (the value shown for a dummy procedure is actu‐
     ally the first few bytes of the procedure text; to find the location of
     the procedure, use ``&'' to take the address of the variable).

4.2 Berkeley Distribution	August 9, 1991	     4.2 Berkeley Distribution

List of man pages available for 4.4BSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net