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

FreeBSD Manual Pages

  
 
  

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

NAME
       acid, acidtypes - debugger

SYNOPSIS
       acid [ -l library ] [ -wq ] [ -m	machine	] [ pid	| core ] [ textfile ]

       acidtypes [ -p prefix ] file ...

DESCRIPTION
       Acid  is	 a programmable	symbolic debugger.  It can inspect one or more
       processes that share an address space.  A program to be debugged	may be
       specified  by the process id of a running or defunct process, or	by the
       name of the program's text file (a.out by  default).   At  the  prompt,
       acid will store function	definitions or print the value of expressions.
       Options are

       -w	Allow the textfile to be modified.

       -q	Print variable renamings at startup.

       -l library
		Load from library at startup; see below.

       -m machine
		Assume instructions are	for the	given CPU type	(see  mach(3))
		instead	of using the executable	header to select the CPU type.

       -k	Debug  the  kernel state for the process, rather than the user
		state.

       At startup, acid	obtains	standard function definitions from the library
       file  /usr/local/plan9/acid/port, architecture-dependent	functions from
       /usr/local/plan9/acid/$objtype,	  user-specified    functions	  from
       $home/lib/acid,	and  further  functions	from -l	files.	Definitions in
       any file	may override previously	defined	functions.   If	 the  function
       acidinit()  is  defined,	it will	be invoked after all modules have been
       loaded.	Then the  function  acidmap()  will  be	 invoked  if  defined.
       /usr/local/plan9/acid/port   provides  a	 definition  of	 acidmap  that
       attaches	all the	shared libraries being used by the target process  and
       then runs acidtypes (q.v.)  to create acid functions for	examining data
       structures.

   Language
       Symbols of the program being debugged become  integer  variables	 whose
       values  are  addresses.	Contents of addresses are obtained by indirec-
       tion.  Local variables are qualified  by	 function  name,  for  example
       main:argv.  When	program	symbols	conflict with acid words, distinguish-
       ing $ signs are prefixed.  Such	renamings  are	reported  at  startup;
       option -q suppresses them.

       Variable	 types (integer, float,	list, string) and formats are inferred
       from  assignments.   Truth  values   false/true	 are   attributed   to
       zero/nonzero integers or	floats and to empty/nonempty lists or strings.
       Lists are sequences of expressions surrounded by	{}  and	 separated  by
       commas.

       Expressions  are	 much  as  in  C, but yield both a value and a format.
       Casts to	complex	types are allowed.  Lists admit	the  following	opera-
       tors, with subscripts counted from 0.

	      head list
	      tail list
	      append list, element
	      delete list, subscript

       Format  codes  are  the	same  as in db(1).  Formats may	be attached to
       (unary) expressions with	\, e.g.	 (32*7)\D.  There are two  indirection
       operators,  *  to  address a core image,	@ to address a text file.  The
       type and	format of the result are determined by the format of the oper-
       and, whose type must be integer.

       Statements are

	      if expr then statement [ else statement ]
	      while expr do statement
	      loop expr, expr do statement
	      defn name(args) {	statement }
	      defn name
	      name(args)
	      builtin name(args)
	      local name
	      return expr
	      whatis [	name ]

       The  statement  defn  name  clears the definition for name.  A defn may
       override	a built-in function; prefixing a function  call	 with  builtin
       ignores any overriding defn, forcing the	use of the built-in function.

       Here  is	 a  partial  list  of functions; see the manual	for a complete
       list.

       stk()  Print a stack trace for current process.

       lstk() Print a stack trace with values of local variables.

       gpr()  Print general registers.	Registers  can	also  be  accessed  by
	      name, for	example	*R0.

       spr()  Print  special  registers	 such  as  program  counter  and stack
	      pointer.

       fpr()  Print floating-point registers.

       regs() Same as spr();gpr().

       fmt(expr,format)
	      Expression expr with format given	 by  the  character  value  of
	      expression format.

       src(address)
	      Print 10 lines of	source around the program address.

       Bsrc(address)
	      Get  the	source line for	the program address into a window of a
	      running sam(1) and select	it.

       line(address)
	      Print source line	nearest	to the program address.

       source()
	      List current source directories.

       addsrcdir(string)
	      Add a source directory to	the list.

       filepc(where)
	      Convert a	string of the form sourcefile:linenumber to a  machine
	      address.

       pcfile(address)
	      Convert a	machine	address	to a source file name.

       pcline(address)
	      Convert a	machine	address	to a source line number.

       bptab()
	      List breakpoints set in the current process.

       bpset(address)
	      Set  a  breakpoint  in the current process at the	given address.
	      (Doesn't work on Unix yet.)

       bpdel(address)
	      Delete a breakpoint from the current process.

       cont() Continue execution of current process and	wait for it to stop.

       step() Execute a	single machine instruction  in	the  current  process.
	      (Doesn't work on Unix yet.)

       func() Step repeatedly until after a function return.

       stopped(pid)
	      This replaceable function	is called automatically	when the given
	      process stops.  It  normally  prints  the	 program  counter  and
	      returns to the prompt.

       asm(address)
	      Disassemble  30  machine	instructions  beginning	 at  the given
	      address.

       mem(address,string)
	      Print a block of memory interpreted according  to	 a  string  of
	      format codes.

       dump(address,n,string)
	      Like mem(), repeated for n consecutive blocks.

       print(expr,...)
	      Print the	values of the expressions.

       newproc(arguments)
	      Start a new process with arguments given as a string and halt at
	      the first	instruction.

       new()  Like newproc(), but take arguments (except argv[0]) from	string
	      variable progargs.

       win()  Like new(), but run the process in a separate window.

       start(pid)
	      Start a stopped process.

       kill(pid)
	      Kill the given process.

       setproc(pid)
	      Make the given process current.

       rc(string)
	      Escape to	the shell, rc(1), to execute the command string.

       include(string)
	      Read acid	commands from the named	file.

       includepipe(string)
	      Run the command string, reading its standard output as acid com-
	      mands.
   Shared library segments
       When a pid or core file is specified on the command line, acid will, as
       part  of	 its  startup, determine the set of shared libraries in	use by
       the process image and map those at appropriate locations.  If  acid  is
       started	without	 a  pid	or core	file and is subsequently attached to a
       process via setproc, the	shared library	maps  can  be  initialized  by
       calling dynamicmap().
   Type	information
       Unix  compilers conventionally include detailed type information	in the
       debugging symbol	section	of binaries.  The external  program  acidtypes
       extracts	 this  information  and	formats	it as acid program text.  Once
       the shared libraries have been mapped, the default acid startup invokes
       acidtypes  (via includepipe) on the set of currently mapped text	files.
       The function acidtypes()	can be	called	to  rerun  the	command	 after
       changing	the set	of mapped text files.
   Acid	Libraries
       There are a number of acid `libraries' that provide higher-level	debug-
       ging facilities.	 One notable example is	 trump,	 which	uses  acid  to
       trace  memory allocation.  Trump	requires starting acid on the program,
       either by attaching to a	running	process	or by  executing  new()	 on  a
       binary (perhaps after setting progargs),	stopping the process, and then
       running trump() to execute the program under the	scaffolding.  The out-
       put will	be a trace of the memory allocation and	free calls executed by
       the program.  When finished  tracing,  stop  the	 process  and  execute
       untrump() followed by cont() to resume execution.
EXAMPLES
       Start  to  debug	/bin/ls; set some breakpoints; run up to the first one
       (this example doesn't work on Unix yet):
	      %	acid /bin/ls
	      /bin/ls: mips plan 9 executable
	      /sys/lib/acid/port
	      /sys/lib/acid/mips
	      acid: new()
	      70094: system call  _main	    ADD	 $-0x14,R29
	      70094: breakpoint	  main+0x4  MOVW R31,0x0(R29)
	      acid: pid
	      70094
	      acid: argv0 = **main:argv\s
	      acid: whatis argv0
	      integer variable format s
	      acid: *argv0
	      /bin/ls
	      acid: bpset(ls)
	      acid: cont()
	      70094: breakpoint	 ls    ADD  $-0x16c8,R29
	      acid:
       Display elements	of a linked list of structures:
	      complex Str { 'D'	0 val; 'X' 4 next; };
	      s	= *headstr;
	      while s != 0 do{
		   complex Str s;
		   print(s.val,	"\n");
		   s = s.next;
	      }
       Note the	use of the .  operator instead of ->.
       Display an array	of bytes declared in C as char array[].
	      *(array\s)
       This example gives array	string format, then prints the	string	begin-
       ning at the address (in acid notation) *array.
       Trace the system	calls executed by ls(1)	(neither does this one):
	      %	acid -l	truss /bin/ls
	      /bin/ls:386 plan 9 executable

	      /sys/lib/acid/port
	      /sys/lib/acid/kernel
	      /sys/lib/acid/truss
	      /sys/lib/acid/386
	      acid: progargs = "-l lib/profile"
	      acid: new()
	      acid: truss()
	      open("#c/pid", 0)
		   return value: 3
	      pread(3, 0x7fffeeac, 20, -1)
		   return value: 12
		   data: "	  166 "
	      ...
	      stat("lib/profile", 0x0000f8cc, 113)
		   return value: 65
	      open("/env/timezone", 0)
		   return value: 3
	      pread(3, 0x7fffd7c4, 1680, -1)
		   return value: 1518
		   data: "EST -18000 EDT -14400
		 9943200   25664400   41392800	 57718800   73447200   89168400
	       104896800  ..."
	      close(3)
		   return value: 0
	      pwrite(1,	"--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile
	      ", 54, -1)
	      --rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29	lib/profile
		   return value: 54
	      ...
	      166: breakpoint	  _exits+0x5	 INTB $0x40
	      acid: cont()
FILES
       /usr/local/plan9/acid/$objtype
       /usr/local/plan9/acid/port
       /usr/local/plan9/acid/kernel
       /usr/local/plan9/acid/trump
       /usr/local/plan9/acid/truss
       $home/lib/acid
SOURCE
       /usr/local/plan9/src/cmd/acid
SEE ALSO
       mk(1), db(1)
       Phil Winterbottom, ``Acid Manual''.
DIAGNOSTICS
       At termination, kill commands are proposed for processes	that are still
       active.
BUGS
       There is	no way to redirect the standard	input and standard output of a
       new process.
       Source line selection near the beginning	of a file may pick an adjacent
       file.
       With the	extant stepping	commands, one cannot step through instructions
       outside the text	segment	and it is hard to debug	across process forks.
       Breakpoints  do	not  work yet.	Therefore, commands such as step, new,
       and truss do not	work either.  New in particular	will need some help to
       cope with dynamic libraries.

								       ACID(1)

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

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

home | help