Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DB(1)			    General Commands Manual			 DB(1)

NAME
       db, stack - debugger

SYNOPSIS
       db [ option ...	] [ pid	| corefile ] [ textfile	]

       stack [ pid | corefile |	name ] [ textfile ]

DESCRIPTION
       Db  is  a general purpose debugging program.  It	may be used to examine
       files and to provide a controlled environment for the execution of pro-
       grams.

       A textfile is a file containing the text	and initialized	data of	an ex-
       ecutable	program.  A pid	or corefile specifies the memory  image	 of  a
       process.	 A pid gives the id of an executing process to be accessed via
       A corefile specifies the	name of	a core dump (see  on  your  system  of
       choice) containing the memory image of a	terminated process.  This man-
       ual refers to the memory	image specified	by pid or corefile as  a  mem-
       file.

       A map associated	with each textfile or memfile supports accesses	to in-
       structions and data in the file;	see `Addresses'.

       An argument consisting entirely of digits is assumed to	be  a  process
       id;  otherwise,	it  is	the  name  of  a textfile or corefile.	When a
       textfile	is given, the textfile map is associated with it.  If  only  a
       memfile	is  given,  the	textfile map is	derived	from the corresponding
       textfile, if it can be determined (this varies from system to  system).
       When  a memfile is given, the memfile map is associated with it;	other-
       wise the	map is undefined and accesses to it are	not permitted.

       Stack takes the same arguments as db.  It prints	a stack	trace (see the
       $c  command  below) and then exits.  If the first argument is a process
       name, then stack	prints the stack trace of every	running	 process  with
       the given name that is owned by the current user.

       Commands	 to  db	 are read from the standard input and responses	are to
       the standard output.  The options are

       -q     Quiet mode: suppress informational prints	at startup.

       -w     Open textfile and	memfile	for writing as well as reading.

       -Ipath Directory	in which to look for relative path names in $< and $<<
	      commands.

       -mmachine
	      Assume  instructions  are	for the	given CPU type (possible names
	      include 386 and powerpc; adding the suffix -co as	in 386-co  and
	      powerpc-co  selects disassembly in the manufacturer's syntax, if
	      available, rather	than the default Plan 9	syntax).

       Most db commands	have the following form:

	      [address]	[, count] [command]

       If address is present then the current position,	called `dot',  is  set
       to  address.   Initially	 dot  is set to	0.  Most commands are repeated
       count times with	dot advancing between repetitions.  The	default	 count
       is  1.	Address	 and  count are	expressions.  Multiple commands	on one
       line must be separated by

   Expressions
       Expressions are evaluated as long ints.

       .      The value	of dot.

       +      The value	of dot incremented by the current increment.

       ^      The value	of dot decremented by the current increment.

       "      The last address typed.

       integer
	      A	number,	in decimal radix by default.   The  prefixes  and  and
	      (zero  oh) force interpretation in octal radix; the prefixes and
	      force interpretation in decimal radix; the  prefixes  and	 force
	      interpretation  in  hexadecimal  radix.	Thus and all represent
	      sixteen.

       integer.fraction
	      A	single-precision floating point	number.

       'c'    The 16-bit value of a character.	may be used to escape a

       <name  The value	of name, which is a register name.  The	register names
	      are those	printed	by the $r command.

       symbol A	 symbol	 is  a sequence	of upper or lower case letters,	under-
	      scores or	digits,	not starting with a digit.  may	be used	to es-
	      cape other characters.  The location of the symbol is calculated
	      from the symbol table in textfile.

       routine.name
	      The address of the variable name in  the	specified  C  routine.
	      Both routine and name are	symbols.  If name is omitted the value
	      is the address of	the most recently activated stack frame	corre-
	      sponding to routine; if routine is omitted, the active procedure
	      is assumed.

       file:integer
	      The address of  the  instruction	corresponding  to  the	source
	      statement	 at  the  indicated  line  number of the file.	If the
	      source line contains no executable statement, the	address	of the
	      instruction  associated  with the	nearest	executable source line
	      is returned.  Files begin	at line	1.  If multiple	files  of  the
	      same name	are loaded, an expression of this form resolves	to the
	      first file encountered in	the symbol table.

       (exp)  The value	of the expression exp.

       Monadic operators

	      *exp   The contents of the location addressed by exp in memfile.

	      @exp   The  contents  of	the  location  addressed  by  exp   in
		     textfile.

	      -exp   Integer negation.

	      ~exp   Bitwise complement.

	      %exp   When  used	 as an address,	exp is an offset into the seg-
		     ment named	ublock;	see `Addresses'.

       Dyadic operators	are left-associative and are less binding than monadic
       operators.

	      e1+e2  Integer addition.

	      e1-e2  Integer subtraction.

	      e1*e2  Integer multiplication.

	      e1%e2  Integer division.

	      e1&e2  Bitwise conjunction.

	      e1|e2  Bitwise disjunction.

	      e1#e2  E1	rounded	up to the next multiple	of e2.

   Commands
       Most commands have the following	syntax:

       ?f   Locations starting at address in textfile are printed according to
	    the	format f.

       /f   Locations starting at address in memfile are printed according  to
	    the	format f.

       =f   The	value of address itself	is printed according to	the format f.

       A  format  consists  of	one or more characters that specify a style of
       printing.  Each format character	may be preceded	by a  decimal  integer
       that is a repeat	count for the format character.	 If no format is given
       then the	last format is used.

       Most format letters fetch some data, print it,  and  advance  (a	 local
       copy of)	dot by the number of bytes fetched.  The total number of bytes
       in a format becomes the currentincrement.

	      o	     Print two-byte integer in octal.
	      O	     Print four-byte integer in	octal.
	      q	     Print two-byte integer in signed octal.
	      Q	     Print four-byte integer in	signed octal.
	      d	     Print two-byte integer in decimal.
	      D	     Print four-byte integer in	decimal.
	      V	     Print eight-byte integer in decimal.
	      Z	     Print eight-byte integer in unsigned decimal.
	      x	     Print two-byte integer in hexadecimal.
	      X	     Print four-byte integer in	hexadecimal.
	      Y	     Print eight-byte integer in hexadecimal.
	      u	     Print two-byte integer in unsigned	decimal.
	      U	     Print four-byte integer in	unsigned decimal.
	      f	     Print as a	single-precision floating point	number.
	      F	     Print double-precision floating point.
	      b	     Print the addressed byte in hexadecimal.
	      c	     Print the addressed byte as an ASCII character.
	      C	     Print the addressed byte as a character.  Printable ASCII
		     characters	 are  represented normally; others are printed
		     in	the form \xnn.
	      s	     Print the addressed characters, as	a UTF string, until  a
		     zero  byte	 is reached.  Advance dot by the length	of the
		     string, including the zero	terminator.
	      S	     Print a string using the escape convention	(see C above).
	      r	     Print as UTF the addressed	two-byte integer (rune).
	      R	     Print as UTF the addressed	two-byte integers as runes un-
		     til a zero	rune is	reached.  Advance dot by the length of
		     the string, including the zero terminator.
	      i	     Print as machine instructions.  Dot is incremented	by the
		     size of the instruction.
	      I	     As	 i above, but print the	machine	instructions in	an al-
		     ternate form if possible.
	      M	     Print the addressed machine instruction in	a  machine-de-
		     pendent hexadecimal form.
	      a	     Print  the	 value	of dot in symbolic form.  Dot is unaf-
		     fected.
	      A	     Print the value of	dot  in	 hexadecimal.	Dot  is	 unaf-
		     fected.
	      z	     Print  the	 function  name,  source file, and line	number
		     corresponding to dot (textfile only). Dot is unaffected.
	      p	     Print the addressed value in symbolic form.  Dot  is  ad-
		     vanced by the size	of a machine address.
	      t	     When preceded by an integer, tabs to the next appropriate
		     tab stop.	For example, 8t	moves to the next 8-space  tab
		     stop.  Dot	is unaffected.
	      n	     Print a newline.  Dot is unaffected.
	      "..."  Print the enclosed	string.	 Dot is	unaffected.
	      ^	     Dot  is decremented by the	current	increment.  Nothing is
		     printed.
	      +	     Dot is incremented	by 1.  Nothing is printed.
	      -	     Dot is decremented	by 1.  Nothing is printed.

       Other commands include:

       newline
	      Update dot by the	current	increment.  Repeat the	previous  com-
	      mand with	a count	of 1.

       [?/]l value mask
	      Words  starting  at  dot	are masked with	mask and compared with
	      value until a match is found.  If	l is used, the match is	for  a
	      two-byte	integer;  L  matches four bytes.  If no	match is found
	      then dot is unchanged; otherwise dot is set to the matched loca-
	      tion.  If	mask is	omitted	then ~0	is used.

       [?/]w value ...
	      Write  the  two-byte  value into the addressed location.	If the
	      command is W, write four bytes.

       [?/]m s b e f [?]
	      New values for (b, e, f) in the segment named  s	are  recorded.
	      Valid  segment  names  are  text,	data, or ublock.  If less than
	      three address expressions	are given,  the	 remaining  parameters
	      are  left	 unchanged.   If the list is terminated	by or then the
	      file (textfile or	memfile	respectively) is used  for  subsequent
	      requests.	 For example, causes to	refer to textfile.

       >name  Dot is assigned to the variable or register named.

       !      The rest of the line is passed to	for execution.

       $modifier
	      Miscellaneous commands.  The available modifiers are:

	      <f     Read  commands  from the file f.  If this command is exe-
		     cuted in a	file, further commands in  the	file  are  not
		     seen.   If	f is omitted, the current input	stream is ter-
		     minated.  If a count is given, and	is zero,  the  command
		     is	ignored.
	      <<f    Similar  to < except it can be used in a file of commands
		     without causing the  file	to  be	closed.	  There	 is  a
		     (small)  limit to the number of <<	files that can be open
		     at	once.
	      >f     Append output to the file f, which	is created if it  does
		     not  exist.   If  f is omitted, output is returned	to the
		     terminal.
	      ?	     Print process id, the condition which caused stopping  or
		     termination,  the registers and the instruction addressed
		     by	pc.  This is the default if modifier is	omitted.
	      r	     Print the general registers and the instruction addressed
		     by	pc.  Dot is set	to pc.
	      R	     Like $r, but include miscellaneous	processor control reg-
		     isters and	floating point registers.
	      f	     Print floating-point register values as  single-precision
		     floating point numbers.
	      F	     Print  floating-point register values as double-precision
		     floating point numbers.
	      b	     Print all breakpoints and	their  associated  counts  and
		     commands.	`B' produces the same results.
	      c	     Stack  backtrace.	 If address is given, it specifies the
		     address of	a pair of 32-bit values	containing the sp  and
		     pc	 of  an	 active	 process.  This	allows selecting among
		     various contexts of a multi-threaded process.   If	 C  is
		     used,  the	names and (long) values	of all parameters, au-
		     tomatic and static	variables are printed for each	active
		     function.	If count is given, only	the first count	frames
		     are printed.
	      a	     Attach to the running process whose pid is	 contained  in
		     address.
	      e	     The  names	 and  values  of  all  external	 variables are
		     printed.
	      w	     Set the page width	for output to address (default 80).
	      q	     Exit from db.
	      m	     Print the address maps.
	      k	     Simulate kernel memory management.
	      Mmachine
		     Set the machine type used for disassembling instructions.

       :modifier
	      Manage a subprocess.  Available modifiers	are:

	      h	     Halt an asynchronously running process  to	 allow	break-
		     pointing.	 Unnecessary  for  processes created under db,
		     e.g. by :r.
	      bc     Set breakpoint at address.	 The  breakpoint  is  executed
		     count-1  times before causing a stop.  Also, if a command
		     c is given	it is executed at each breakpoint  and	if  it
		     sets dot to zero the breakpoint causes a stop.
	      d	     Delete breakpoint at address.
	      r	     Run  textfile  as	a subprocess.  If address is given the
		     program is	entered	at that	point; otherwise the  standard
		     entry  point  is  used.   Count specifies how many	break-
		     points are	to be ignored before stopping.	 Arguments  to
		     the  subprocess  may  be supplied on the same line	as the
		     command.  An argument starting with <  or	>  causes  the
		     standard  input  or output	to be established for the com-
		     mand.
	      cs     The subprocess is continued.  If s	is omitted or nonzero,
		     the  subprocess  is sent the note that caused it to stop.
		     If	0 is specified,	no note	is sent.  (If the stop was due
		     to	a breakpoint or	single-step, the corresponding note is
		     elided before continuing.)	 Breakpoint  skipping  is  the
		     same as for r.
	      ss     As	for c except that the subprocess is single stepped for
		     count machine instructions.  If a note is pending,	it  is
		     received  before  the  first instruction is executed.  If
		     there is no current subprocess then textfile is run as  a
		     subprocess	 as  for r.  In	this case no note can be sent;
		     the remainder of the line is treated as arguments to  the
		     subprocess.
	      Ss     Identical	to  s  except the subprocess is	single stepped
		     for count lines of	C source.  In optimized	code, the cor-
		     respondence between C source and the machine instructions
		     is	approximate at best.
	      x	     The current subprocess, if	any, is	released by db and al-
		     lowed to continue executing normally.
	      k	     The current subprocess, if	any, is	terminated.
	      nc     Display the pending notes for the process.	 If c is spec-
		     ified, first delete c'th pending note.

   Addresses
       The location in a file or memory	image associated with  an  address  is
       calculated  from	a map associated with the file.	 Each map contains one
       or more quadruples (t, f, b, e, o), defining a segment  named  t	 (usu-
       ally,  text,  data, or core) in file f mapping addresses	in the range b
       through e to the	part of	the file beginning at offset o.	  If  segments
       overlap,	 later	segments obscure earlier ones.	An address a is	trans-
       lated to	a file address by finding the last segment  in	the  list  for
       which baxa<e; the location in the file is then address+f-b.

       Usually,	 the text and initialized data of a program are	mapped by seg-
       ments called text, data,	and bss.  Since	a program file does  not  con-
       tain  stack  data, this data is not mapped.  The	text segment is	mapped
       similarly in a normal (i.e., non-kernel)	memfile.  However, one or more
       segments	 called	 data  provide	access to process memory.  This	region
       contains	the program's static data, the bss, the	heap and the stack.

       Sometimes it is useful to define	a map with a  single  segment  mapping
       the  region  from  0 to 0xFFFFFFFF; a map of this type allows an	entire
       file to be examined without address translation.

       The $m command dumps the	currently active maps.	The ?m and /m commands
       modify the segment parameters in	the textfile and memfile maps, respec-
       tively.

EXAMPLES
       To set a	breakpoint at the beginning of write() in extant process 27:

	      %	db 27
	      :h
	      write:b
	      :c

       To set a	breakpoint at the entry	of function parse when the local vari-
       able argc in main is equal to 1:

	      parse:b *main.argc-1=X

       This  prints  the value of argc-1 which as a side effect	sets dot; when
       argc is one the breakpoint will fire.  Beware that local	variables  may
       be stored in registers; see the BUGS section.

SEE ALSO
SOURCE
       /src/cmd/db

DIAGNOSTICS
       Exit  status  is	0, unless the last command failed or returned non-zero
       status.

BUGS
       Examining a local variable with routine.name returns  the  contents  of
       the memory allocated for	the variable, but with optimization, variables
       often reside in registers.  Also, on some architectures,	the first  ar-
       gument is always	passed in a register.

       Variables and parameters	that have been optimized away do not appear in
       the symbol table, returning the error bad local variable	when  accessed
       by db.

       Breakpoints should not be set on	instructions scheduled in delay	slots.
       When a program stops on such a breakpoint, it is	usually	impossible  to
       continue	its execution.

									 DB(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | SOURCE | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=db&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help