Unix/Linux Go Back    

Plan 9 - man page for db (plan9 section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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 sup-
       ports accesses to instructions 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.	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 undefined 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 kernel 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

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

	      Assume instructions are for the given CPU type (one of 3210, 386, 68020, 960, mips,
	      mipsco,  sparc,  or  sunsparc)  instead of using the magic number to select the CPU

       Most db commands have the following form:

	      [address] [, count] [command]

       If address is present then the current position, called `dot', is set  to  address.   Ini-
       tially 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  com-
       mands 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 inter-
	      pretation 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, underscores or digits, not
	      starting with a digit.  may be used to escape other characters.	The  location  of
	      the symbol is calculated from the symbol table in textfile.

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

	      The address of the instruction corresponding to the source statement at  the  indi-
	      cated  line  number  of the file.  If the source line contains no executable state-
	      ment, 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 segment named ublock; see

       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.

       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 char-
       acter.  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 incre-

	      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.
	      x      Print two-byte integer in hexadecimal.
	      X      Print four-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 termi-
	      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 termi-
	      Y      Print a four-byte integer in date format (see ctime(2)).
	      i      Print  as	machine  instructions.	 Dot  is  incremented  by the size of the
	      I      As i above, but print the machine instructions in an alternate form if  pos-
		     sible: sunsparc and mipsco reproduce the manufacturers' syntax.
	      M      Print  the  addressed machine instruction in a machine-dependent hexadecimal
	      a      Print the value of dot in symbolic form.  Dot is unaffected.
	      A      Print the value of dot in hexadecimal.  Dot is unaffected.
	      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 printed.
	      +      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 command with a count of

       [?/]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
	      location.  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 exam-
	      ple, 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 executed in a file,  fur-
		     ther  commands in the file are not seen.  If f is omitted, the current input
		     stream is terminated.  If a count is given, and  is  zero,  the  command  is
	      <<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 modi-
		     fier 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 registers and floating
		     point registers.
	      f      Print floating-point register values as single-precision floating point num-
	      F      Print floating-point register values as double-precision floating point num-
	      b      Print all breakpoints and their associated counts and  commands.	`B'  pro-
		     duces 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  vari-
		     ables  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.
		     Set the machine type used for disassembling instructions.

	      Manage a subprocess.  Available modifiers are:

	      h      Halt an asynchronously running process to allow breakpointing.   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 break-
		     point 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  breakpoints	are to be ignored before stopping.  Arguments to the sub-
		     process may be supplied on the same line as the command.  An argument start-
		     ing  with	<  or > causes the standard input or output to be established for
		     the command.
	      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 remain-
		     der 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 correspondence  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 specified, 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 segments 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 beginning 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

       Registers are saved at a machine-dependent offset in the ublock.  It is usually not neces-
       sary  to  know  this  offset; the $r, $R, $f, and $F commands 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, respectively.

       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 variable 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 (suppressed by the -N compiler flag) variables
       often reside in registers.  Also, on some architectures,  the  first  argument  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.

       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.

Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 07:23 PM.