NAME

adb - debugger

SYNOPSIS

adb [-k] [-p] [-q] [-w] [ objfil [ corfil ] ]

DESCRIPTION

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

Objfil is normally an executable program file, preferably containing a symbol table; if not then the symbolic features of adb cannot be used although the file can still be examined. The default for objfil is a.out. Corfil is assumed to be a core image file produced after executing objfil; the default for corfil is core.

If either objfil or corfil is a procfs object (see proc(4)), it becomes the process being debugged. Thus "adb - w /proc/192" begins debugging the existing process with pid 192, with background mode entered automatically if this process is currently running. (See the :g command for a description of "background mode".) If objfil is a procfs object, its execed file is accessed for symbol information.

Requests to adb are read from the standard input and responses are to the standard output. If the -w flag is present then both objfil and corfil are created if necessary and opened for reading and writing so that files can be modified using adb. The -w flag is also required to modify or affect a procfs process.

Adb ignores QUIT; INTERRUPT causes return to the next adb command.

In general requests to adb are of the form

           [address]  [, count] [command] [;]

If address is present then dot is set to address. Initially dot is set to 0. For most commands count specifies how many times the command will be executed. The default count is 1. Address and count are expressions.

The interpretation of an address depends on the context it is used in. If a subprocess is being debugged then addresses are interpreted in the usual way in the address space of the subprocess. For further details of address mapping see ADDRESSES.

EXPRESSIONS

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

integer

A number. The prefixes 0o and 0O ("zero oh") force interpretation in octal radix; the prefixes 0t and 0T force interpretation in decimal radix; the prefixes 0x and 0X force interpretation in hexadecimal radix. Thus 0o20 = 0t16 = 0x10 = sixteen. If no prefix appears, then the default radix is used; see the $d command. The default radix is initially hexadecimal. The hexadecimal digits are 0123456789abcdefABCDEF with the obvious values. Note that a hexadecimal number whose most significant digit would otherwise be an alphabetic character must have a 0x (or 0X) prefix (or a leading zero if the default radix is hexadecimal).

integer.fraction

A 32 bit floating point number (in the current radix -- use 0t for decimal).

'cccc' The ASCII value of up to 4 characters.  \ may be used
       to escape a '.

< name The value of name, which is either a variable name or
       a register name.  Adb maintains a number of variables
       (see VARIABLES) named by single  letters  or  digits.
       If  name  is  a  register  name then the value of the
       register is obtained from the system header  in  cor-
       fil.   The register names are those printed by the $r
       command.

[file]symbol

A symbol is a sequence of upper or lower case letters, underscores or digits, not starting with a digit. The backslash character \ may be used to escape other characters. The value of the symbol is taken from the symbol table in objfil, or if objfil is a procfs object, then from the a.out file it execed. Symbols local to a file are distinguished from symbols of the same name in another file by prefixing the symbol name with an optional file name enclosed in a pair of square brackets, as shown.

This form is also used when printing local symbols.

[file]_symbol

The `true name' of an "internal" symbol of the library implementation (a symbol which is part of the standard libc library, but not part of the ANSI C standard) may begin with _. It may be necessary to utter this name to distinguish it from conflicting symbols of a program.

routine.name

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 C stack frame corresponding to routine. If routine is omitted the value is the address of name in the most recently activated C stack frame containing variable name.

(exp)  The value of the expression exp.

Monadic operators

*exp The contents of the location addressed by exp in the ? map.

@exp The contents of the location addressed by exp in the / map.

-exp Integer negation.

~exp Bitwise complement.

#exp Logical negation.

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.

COMMANDS

Most commands consist of a verb followed by a modifier or list of modifiers. The following verbs are available.

?f Locations starting at address in the ? map are printed according to the format f. dot is incremented by the sum of the increments for each format letter (q.v.).

/f Locations starting at address in the / map are printed according to the format f and dot is incremented as for `?'.

=f The value of address itself is printed in the styles indicated by the format f. (For i format `?' is printed for the parts of the instruction that reference subsequent words.)

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. While stepping through a format dot is incremented by the amount given for each format letter. If no format is given then the last format is used. The format letters available are as follows.

     o  2 Print 2 bytes in octal.  All octal numbers  output
          by adb are preceded by 0.
     O  4 Print 4 bytes in octal.
     q  2 Print in signed octal.
     Q  4 Print long signed octal.
     d  2 Print in decimal.
     D  4 Print long decimal.
     x  2 Print 2 bytes in hexadecimal.
     X  4 Print 4 bytes in hexadecimal.
     u  2 Print as an unsigned decimal number.
     U  4 Print long unsigned decimal.
     f  4 Print the 32 bit value as a floating point number.
     F  8 Print double floating point.
     bu 1 Print the addressed byte in unsigned decimal.
     bd 1 Print the addressed byte in signed decimal.
     bo 1 Print the addressed byte in octal.
     bx 1 Print the addressed byte in hex.
     c  1 Print the addressed character.
     C  1 Print the addressed character using  the  standard
          escape  convention  where  control  characters are
          printed as ^X and the delete character is  printed
          as ^?.
     s  n Print the addressed characters until a zero  char-
          acter is reached.
     S  n Print a string using the ^X escape convention (see
          C above).  n is the length of the string including
          its zero terminator.

     Y  4 Print 4 bytes in date format (see ctime(3)).
     i  n Print as machine instructions.  n is the number of
          bytes  occupied by the instruction.  This style of
          printing causes variables 1 and 2 to be set to the
          offset parts of the source and destination respec-
          tively.
     a  0 Print the value of dot in symbolic form.

     p  4 Print the addressed value in symbolic form.
     t  0 When preceded by  an  integer  tabs  to  the  next
          appropriate  tab  stop.   For example, 8t moves to
          the next 8-space tab stop.
     r  0 Print a space.
     n  0 Print a newline.
     "..." 0
          Print the enclosed string.
     ^    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.

newline

Repeat the previous command 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 then the match is for 4 bytes at a time instead of 2. If no match is found then dot is unchanged; otherwise dot is set to the matched location. If mask is omitted then -1 is used.

[?/]w value ...

Write the 2-byte value into the addressed location. If the command is W, write 4 bytes.

[?/]m b e f [{?,/,"filename"}]

New values for (b, e, f) are recorded for a segment of the indicated map. The first segment which overlaps the specified b and e bounds is modified. If no existing segment overlaps, a new segment is created. If no fourth argument is specified when creating a new segment, objfil or corfil will be used for that segment, according to which command (`?' or `/') is used. If the fourth argument is `?' or `/' then objfil or corfil respectively becomes the file for the specified segment. If the fourth argument is a quoted filename, the file is opened and used for subsequent requests; this allows parts of arbitrary files to be mapped into either map while adb is running.

>name

Dot is assigned to the variable or register named.

! A shell (/bin/sh) is called to read the rest of the line following `!'.

$modifier

     Miscellaneous commands.  The available modifiers are:

     <f   Read commands from the file f.  If this command is
          executed  in  a file, further commands in the file
          are not seen.  If f is omitted, the current  input
          stream is terminated.
     >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 the process state, including the process  id
          and  the condition which caused stoppage or termi-
          nation.  This is the default if modifier is  omit-
          ted.
     r    Print the general registers  and  the  instruction
          addressed by pc.  Dot is set to pc.
     a    Print all watchpoints and their associated  counts
          and commands.
     b    Print all breakpoints and their associated  counts
          and commands.
     c    C stack backtrace.  If address is given then it is
          taken  as the address of the current frame instead
          of the contents of the frame-pointer register.  If
          C  is  used  then the names and (32 bit) values of
          all automatic and static variables are printed for
          each  active  function  (this function is curently
          broken on SVR4).  If count is given then only  the
          first count frames are printed.
     d    Set the default radix to address  and  report  the
          new  value.   Note  that address is interpreted in
          the  (old)  current  radix.   Thus  "10$d"   never
          changes  the  default  radix.  To make decimal the
          default radix, use "0t10$d".
     e    The names and values  of  external  variables  are
          printed.
     w    Set the page width for output to address  (default
          is width of the terminal on stdout, or 80).
     s    Set  the  limit  for  symbol  matches  to  address
          (default 255).
     o    All integers input are regarded as octal.
     q    Exit from adb.
     v    Print all non zero variables in hex or decimal.
     m    Print the address maps.
          If a subprocess  currently  exists,  a  :  map  is
          displayed  in addition to the ? and / maps.  The :
          map shows the valid address space of  the  subpro-
          cess.   The  `offset' field (`f' column) indicates
          the offset in  whatever  object  the  process  has
          mapped  (such  as  a shared library); the filename
          field is currently not useful.  This map  can  not
          be modified using adb.
:modifier
     Manage a subprocess.  Available modifiers are:

ac Set a watchpoint at address. Each time the process stops due to hitting a breakpoint or doing a single step, the contents of the long value at address is compared with the last known value. Each change causes the count to decrement and the the command c is executed. When the count reaches zero the process remains stopped. Typically used by setting a watchpoint and giving the single step command with a large count.

bc Set breakpoint at address. The breakpoint is executed count-1 times before causing a stop. Each time the breakpoint is encountered the command c is executed. If this command is omitted or sets dot to zero then the breakpoint causes a stop.

d Delete breakpoint at address.

r Run objfil as a subprocess. If address is given explicitly then the program is entered at this point; otherwise the program is entered at its standard entry point. count specifies how many breakpoints 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 command.

cs The subprocess is continued with signal s, see signal(2) and sigaction(2). If address is given then the subprocess is continued at this address. If no signal is specified then the signal that caused the subprocess to stop is sent. Breakpoint skipping is the same as for r.

gs The subprocess is continued with signal s, as for the c command, except that adb does not wait for the process to stop. Memory may be examined and/or modified while the process is running.

ss As for c except that the subprocess is single stepped count times. If there is no current subprocess then objfil is run as a subprocess as for r. In this case no signal can be sent; the remainder of the line is treated as arguments to the subprocess. If the subprocess is running in background mode (see :g) This will stop the subprocess and switch to "foreground" mode.

k The current subprocess, if any, is terminated.

VARIABLES

Adb provides a number of variables. Named variables are set initially by adb but are not used subsequently. Numbered variables are reserved for communication as follows.

0    The last value printed.
2    The previous value of variable 1.

3 The previous value of variable 4.

4 The previous value of variable 5.

5 The program counter value the last time the current debuggee process stopped.

ADDRESSES

The data associated with a written address are determined by a map. Adb creates two maps, referred to as "?" and "/", and roughly corresponding to objfil and corfil, respectively. A third map describing a running process is effectively created by the system, and is referred to as ":". The maps can be displayed with the $m command. Each map consists of a set of segments, each segment having a triple of addresses (b, e, f) and a file. Addresses which fall within a segment's b and e bounds, have their corresponding data in that segment's file. The file address (seek offset) corresponding to a written address is calculated as follows.

If a segment exists such that b<address<e,
then file address=address+f-b,
otherwise, the requested address is not legal.

The initial setting of the mappings is suitable for normal a.out and core files. If either file is not of the kind expected then, for that file, a segment is created with b set to 0, e set to the maximum file size and f set to 0; in this way the whole file can be examined with no address translation.

FILES

a.out
core
/proc/*

SEE ALSO

cc(1), ld(1), sdb(1), proc(4), a.out(4), core(4)

DIAGNOSTICS

`Adb' when there is no current command or format. Comments about inaccessible files, syntax errors, abnormal termination of commands, etc. Exit status is 0, unless last command failed or returned nonzero status.

PORT NOTES

This is a port of adb from the UNIXPC3.51 source to SVR4.0 using the procfs facility.

These are the essential differences from the traditional adb:

An optional "-k" argument before objfil and corfil specifies that adb is to use /stand/unix by default, instead of a.out, and /dev/kmem by default, instead of core. If objfil is a relocatable kernel, then the running kernel is queried for a base address and all symbols are relocated to match the relocation done by the boot loader.

An optional "-p" argument before objfil and corfil specifies that adb is to use "adb> " as a prompt, rather than a bare newline.

An optional "-q" argument before objfil and corfil specifies that adb is to surpress verbose startup messages and warnings, making adb more suitable for use in scripts.

The procfs facility exclusively is used to control the selected process. Stopping is enabled for all signals and all faults except FLT_PAGE.

A "background" run mode has been added, activated by the ":g" command.

If either objfil or corfil is a procfs object, it becomes the process being debugged.

In addition to the `?' and `/' maps, a `:' map can be displayed by the $m command, showing the valid address space of the current process. A variable number of address space segments for each map are supported. See ADDRESSES and the description of the $m command.

ELF and COFF object files and their symbol tables are understood, as are ELF core files. Core files created by COFF programs are not recognized.

When `corfil' is an ELF core file and no process has been selected or created, the $?, $r, and $f commands will refer to the "prstatus" and "fpregs" sections in the core file, thus displaying the state of the process when it died.

Symbols are not distinguished by their section (text and data symbols are not treated differently).

Symbols can be prefixed with an optional file name, enclosed in square brackets (I.E. [file]symbol), to specify symbols local to a specific file. The file prefix is ignored for global symbols since the symbol table contains insufficient information to determine in which file a global symbol is defined.

When adb displays the symbolic notation of an address for the a format, only global symbols are considered. When adb displays memory in any format, it will print a local symbol name if it exactly matches dot. Thus, a command like "main,10?ia" will print an address relative to main for every line, with any local symbols displayed once in addition.

The $? (a.k.a. $) command no longer duplicates the action of the $r command. Type "$;$r" if you want both.

The b format specifier no longer always prints in octal; it is now followed by a letter "u" (unsigned decimal), "d" (signed decimal), "o" (octal), or "x" (hex) to specify the radix for the byte.

The terminal's width is queried for use in output formatting.

BUGS

When adb is run on an existing process, it is supposed to automatically start in "background mode". However, if the process is in an uninterruptible sleep, adb will hang trying to find out its status, and an interrupt aborts adb instead of getting to the adb prompt.