acid man page on Plan9

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

ACID(1)								       ACID(1)

       acid, truss, trump - debugger

       acid [ -kqw ] [ -l library ] [ -m machine ] [ pid ] [ textfile ]

       acid -l truss textfile

       acid -l trump [ pid ] [ textfile ]

       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 (8.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 (one of	amd64,
		386,  etc.,  as listed in 8c(1), or sunsparc or mipsco for the
		manufacturer-defined instruction notation  for	those  proces‐
		sors)  instead	of  using  the	magic number to select the CPU

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

       At startup, acid obtains standard function definitions from the library
       file   /sys/lib/acid/port,   architecture-dependent   functions	  from
       /sys/lib/acid/$objtype,	user-specified	functions from $home/lib/acid,
       and further functions from -l files.  Definitions in any file may over‐
       ride  previously	 defined  functions.   If  the	function acidinit() is
       defined, it will be invoked after all libraries have been loaded.   See
       8c(1)  for information about creating acid functions for examining data

       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  if
       the option -q is enabled.

       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

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

       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

       fpr()  Print floating-point registers.

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

	      Expression expr with format given	 by  the  character  value  of
	      expression format.

	      Print 10 lines of source around the program address.

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

	      Print source line nearest to the program address.

	      List current source directories.

	      Add a source directory to the list.

	      Convert a string of the form sourcefile:linenumber to a  machine

	      Convert a machine address to a source file name.

	      Convert a machine address to a source line number.

	      List breakpoints set in the current process.

	      Set a breakpoint in the current process at the given 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.

       func() Step repeatedly until after a function return.

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

	      Disassemble  30  machine	instructions  beginning	 at  the given

	      Print a block of memory interpreted according  to	 a  string  of
	      format codes.

	      Like mem(), repeated for n consecutive blocks.

	      Print the values of the expressions.

	      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 a stopped process.

	      Kill the given process.

	      Make the given process current.

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

       There are a number of acid `libraries' that provide higher-level debug‐
       ging facilities.	 Two notable examples are truss and trump,  which  use
       acid to trace system calls (truss) and memory allocation (trump).  Both
       require starting acid on the program, either by attaching to a  running
       process or by executing new() on a binary (perhaps after setting proga‐
       rgs), stopping the process, and then running truss() or trump() to exe‐
       cute  the program under the scaffolding.	 The output will be a trace of
       the system calls (truss) or memory allocation and  free	calls  (trump)
       executed	 by  the program.  When finished tracing, stop the process and
       execute untruss() or untrump() followed by cont() to resume execution.

       Start to debug /bin/ls; set some breakpoints; run up to the first one:

	      % acid /bin/ls
	      /bin/ls: mips plan 9 executable
	      acid: new()
	      70094: system call  _main	    ADD	 $-0x14,R29
	      70094: breakpoint	  main+0x4  MOVW R31,0x0(R29)
	      acid: pid
	      acid: argv0 = **main:argv\s
	      acid: whatis argv0
	      integer variable format s
	      acid: *argv0
	      acid: bpset(ls)
	      acid: cont()
	      70094: breakpoint	 ls    ADD  $-0x16c8,R29

       Display elements of a linked list of structures:

	      complex Str { 'D' 0 val; 'X' 4 next; };
	      complex Str s;
	      s = *headstr;
	      while s != 0 do{
		   print(s.val, "\n");
		   s =;

       Note the use of the .  operator instead of ->.

       Display an array of bytes declared in C as char array[].


       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):

	      % acid -l truss /bin/ls
	      /bin/ls:386 plan 9 executable

	      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  ..."
		   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()



       8a(1), 8c(1), 8l(1), mk(1), db(1)
       Phil Winterbottom, ``Acid Manual''.

       At termination, kill commands are proposed for processes that are still

       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
       With the extant stepping commands, one cannot step through instructions
       outside the text segment and it is hard to debug across process forks.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
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