db man page on Plan9

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

DB(1)									 DB(1)

       db - debugger

       db [ option ...	] [ textfile ] [ pid ]

       Db  is  a general purpose debugging program.  It may be used to examine
       files and to provide a controlled environment for the execution of Plan
       9 programs.

       A  textfile  is	a  file containing the text and initialized data of an
       executable program.  A memfile is the  memory  image  of	 an  executing
       process.	  It  is  usually  accessed  via  the  process id (pid) of the
       process in /proc/pid/mem.  A memfile contains the text, data, and saved
       registers  and  process	state.	A map associated with each textfile or
       memfile supports accesses to instructions and data  in  the  file;  see

       An  argument  consisting	 entirely of digits is assumed to be a process
       id; otherwise, it is the name of a textfile.  When a textfile is given,
       the  textfile  map  is associated with it.  If only a pid is given, the
       textfile map is associated with /proc/pid/text.	When a pid  is	given,
       the memfile map is associated with /proc/pid/mem; otherwise it is unde‐
       fined and accesses to the memfile are not permitted.

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

       -k     Use  the kernel stack of process pid to debug the executing ker‐
	      nel process.  If textfile is not specified, file /$cputype/9type
	      is used, where type is the second word in $terminal.

       -w     Create  textfile	and memfile if they don't exist; open them for
	      writing as well as reading.

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

	      Assume  instructions  are	 for  the given CPU type (any standard
	      architecture name, such as amd64 or 386, plus  mipsco  and  sun‐
	      sparc,  which  cause  disassembly	 to the manufacturer's syntax)
	      instead of using the magic number to select the CPU type.

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

	      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

	      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
	      escape  other  characters.  The location of the symbol is calcu‐
	      lated from the symbol table in textfile.

	      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.

	      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

	      -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

	      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.

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

	      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
		     until  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
		     alternate form if possible: sunsparc and mipsco reproduce
		     the manufacturers' syntax.
	      M	     Print  the	 addressed  machine  instruction in a machine-
		     dependent hexadecimal form.
	      a	     Print the value of dot in symbolic form.	Dot  is	 unaf‐
	      A	     Print  the	 value	of  dot	 in hexadecimal.  Dot is unaf‐
	      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
		     advanced 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
	      +	     Dot is incremented by 1.  Nothing is printed.
	      -	     Dot is decremented by 1.  Nothing is printed.

       Other commands include:

	      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 rc(1) for execution.

	      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
	      ?	     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,
		     automatic	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
	      e	     The names	and  values  of	 all  external	variables  are
	      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.
		     Set the machine type used for disassembling instructions.

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

       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, b, e, f), defining a segment named t (usually,
       text, data, or ublock) mapping addresses in the range b	through	 e  to
       the part of the file beginning at offset f.  The memory model of a Plan
       9 process assumes that segments are disjoint.  There can be  more  than
       one  segment  of	 a  given type (e.g., a process may have more than one
       text segment) but segments may not overlap.  An address a is translated
       to a file address by finding a segment for which b≤a<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 and data.  Since a program file does not contain bss,
       stack or ublock data, these data are not mapped by  the	data  segment.
       The  text  segment  is  mapped similarly in a normal (i.e., non-kernel)
       memfile.	 However, the segment called data maps memory from the	begin‐
       ning  of	 the  program's	 data  space  to the base of the ublock.  This
       region contains the program's static data, the bss, the	heap  and  the
       stack.	A segment called ublock maps the page containing its registers
       and process state.

       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 the entire
       file to be examined without address translation.

       Registers are saved at a machine-dependent offset in the ublock.	 It is
       usually	not necessary to know this offset; the $r, $R, $f, and $F com‐
       mands calculate it and display the register contents.

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

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

	      % db 27

       To examine the Plan 9 kernel stack for process 27:

	      % db -k 27

       Similar, but using a kernel named test:

	      % db -k test 27

       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.

       Debug process 127 on remote machine kremvax:

	      % import kremvax /proc
	      % db 127


       acid(1), nm(1), proc(3)


       Exit  status  is	 null, unless the last command failed or returned non-
       null status.

       Examining a local variable with routine.name returns  the  contents  of
       the  memory  allocated  for  the	 variable, but with optimization (sup‐
       pressed by the -N compiler flag) variables often reside	in  registers.
       Also,  on  some architectures, the first argument is always passed in a

       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.

       Because of alignment incompatibilities, Motorola 68000 series  machines
       can not be debugged remotely from a processor of a different type.

       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.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

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