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 at-
       taches 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;  op-
       tion -q suppresses them.

       Variable	 types (integer, float,	list, string) and formats are inferred
       from assignments.  Truth	values false/true are attributed to  zero/non-
       zero  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 ex-
	      pression 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 re-
	      turns to the prompt.

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

       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 bi-
       nary (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 un-
       trump() 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