adb(1) adb(1)NAME adb - debugs executable programs SYNOPSIS adb [-k] [-w] [object-file [core-file]] ARGUMENTS core-file Specifies the name of a core image file that was produced when a core dump occurred while the object file specified by object-file was executing. The default value of core-file is core. -k Causes adb to skip execution of a system call to gather relocation addresses. This option is useful when you are running adb on a stand-alone program, such as the kernel, (/unix), that does not have relocated addresses. object-file Specifies the name of an executable program, preferably containing a symbol table. If the symbol table is not available, the symbolic features of adb cannot be used, although you can still use adb to examine the file. The default value of object-file is a.out. -w Causes adb to open the object and core files for writing as well as reading. If the object file does not exist, adb creates it. You should use this option if you want to use adb to modify the object or core files. If you do not specify this option, adb opens the files for reading only. DESCRIPTION adb is a general-purpose debugger. You can use adb to examine core files and to debug object files in a controlled environment. In general, requests to adb are of the form [address] [,count] [command] [;] where address and count are expressions. If address is present, the current address, which is represented by a period (.) and is called ``dot,'' is set to address. Initially, dot is set to 0. For most commands, count specifies how many times the command is to be executed. The default value of count is 1. January 1992 1
adb(1) adb(1)The interpretation of an address depends on the context in which it is used. If a subprocess is being debugged, addresses are interpreted in the usual way in the address space of the subprocess. If the operating system is being debugged either post-mortem or by use of the special file /dev/kmem to examine interactively or to modify memory, the maps are set to map the kernel virtual addresses. For further details of address mapping, see ``Addresses'' later in the ``Description'' section. To quit adb, use the $q or the $Q command; see ``Commands'' later in the ``Description'' section. You can also press CONTROL-D. The adb command ignores SIGQUIT, and SIGINT causes adb to return to the next adb command. Expressions You can form an expression from the following elements: The last address typed. 'cccc' The ASCII value of up to four characters. You can use a backslash ( \ ) to escape a single quote ('). (exp) The value of the expression exp. + The value of dot, incremented by the current increment. . The value of dot. <name The value of name, which is either a variable name or a register name. The adb command maintains a number of variables (see ``Variables'' later in the ``Description '' section) named by single letters or digits. If name is a register name, the value of the register is obtained from the system header in core-file. The register names are those printed by the $r command. ^ The value of dot, decremented by the current increment. _ symbol In C, the actual name of an external symbol begins with an underscore. You may have to use the actual name to distinguish it from internal or hidden variables of a program. integer A number. The prefix 0 (zero) forces interpretation in 2 January 1992
adb(1) adb(1)octal radix; the prefixes 0d and 0D force interpretation in decimal radix; the prefixes 0x and 0X force interpretation in hexadecimal radix. Thus 020=0d16=0x10=16. If a prefix is not present, adb uses the default radix (see ``Commands'' later in the ``Description'' section for information on the $d command). The default radix is initially hexadecimal. The hexadecimal digits are 0123456789abcdefABCDEF. Note that a hexadecimal number whose most significant digit would otherwise be an alphabetical character must have a 0x (or 0X) prefix (or a leading 0, if the default radix is hexadecimal). integer.fraction A 32-bit floating-point number. symbol Sequence of uppercase or lowercase letters, underscores, or digits, not starting with a digit. You can use a backslash ( \ ) to escape other characters. The value of symbol is taken from the symbol table in the object file. An initial underscore ( _ ) or tilde (~) is prefixed to symbol, if needed. Monadic Operators You can use these monadic operators with an expression: #exp Logical negation. *exp The contents of the location addressed by exp in core-file. -exp Integer negation. @exp The contents of the location addressed by exp in object-file. ~exp Bitwise complement. Dyadic Operators You can use these dyadic operators with two expressions. Dyadic operators are left-associative and are less binding than monadic operators. e1+e2 Integer addition. e1-e2 Integer subtraction. e1*e2 Integer multiplication. January 1992 3
adb(1) adb(1)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 question mark (?) and slash (/) commands may be followed by an asterisk (*). See ``Addresses'' later in the ``Description'' section for further details. The following verbs are available: newline Repeats the previous command with a count value of 1 where newline is the ASCII character 0a. By default, pressing the RETURN key produces a newline character. ! Calls a shell to read the rest of the line following !. > name Assigns dot to the variable or register named. This command is often used in the form constant>name. This form of the command can be used to enter 96-bit IEEE extended-precision numbers into the floating-point data registers fp0-fp7. For example, the following command puts the value 1.0 info fp0: 0x3FFF00008000000000000000 > fp0 When this form of the command is used, only the first 32 bits of the constant are stored in dot. See MC68881 Floating Point Coprocessor User's Manual (available from Motorola Literature Distribution Center, part number MC68881UM/AD), section 2.4, ``Extended Real,'' p. 211, for a description of IEEE extended-precision format. [?/]l value mask Masks words starting at dot with mask and compares them with value until a match is found. If L is used, the match is for 4 bytes at a time instead of 2. If no match is found, dot is unchanged; otherwise, dot is set to the matched location. If mask is omitted, -1 is used. 4 January 1992
adb(1) adb(1)[?/]m b1 e1 f1[?/] Records new values for b1, e1, f1. If fewer than three expressions are given, the remaining map parameters are left unchanged. If more than three expressions are given, the values of (b2, e2, f2), (b3, e3, f3) and so on, are changed. If the question mark (?) or slash (/) is followed by an asterisk (*), the first segment (b1, e1, f1) of the mapping is skipped, and the second and subsequent segments are changed instead. (There are as many (bn, en, fn) triples as you have sections in your program.) If the list is terminated by ? or /, object-file or core-file, respectively, is used for subsequent requests. For example, /m? causes / to refer to the object file. [?/]w value ... Writes the 2-byte value value into the addressed location. If the command is W, adb writes 4 bytes. Odd addresses are not allowed when you are writing to the subprocess address space. You can place a format request after the /, =, and ? commands to specify a style of printing: /format Prints locations starting at address in core-file according to format, and dot is incremented as for the question mark. =format Prints the value of address itself in the styles indicated by format. (For i format, a question mark is printed for the parts of the instruction that reference subsequent words.) ?format Prints the locations starting at address in object-file according to format. Dot is incremented by the sum of the increments for each format letter. A format consists of one or more characters. Each format character may be preceded by a decimal integer that is a repeat count for the format character. As the format is stepped through, dot is incremented by the amount given for each format letter. If no format is given, the last format is used. These format letters are available: "..." 0 Prints the enclosed string. + Increments dot by 1. Nothing is printed. January 1992 5
adb(1) adb(1)- Decrements dot by 1. Nothing is printed. ^ Decrements dot by the current increment. Nothing is printed. a 0 Prints the value of dot in symbolic form. Symbols are checked to ensure that they have an appropriate type, where / is a global data symbol, ? is a global text symbol, and = is a global absolute symbol. b 1 Prints the addressed byte in octal. C 1 Prints the addressed character according to the standard escape convention, where control characters are printed as ^X and the delete character is printed as ^?. c 1 Prints the addressed character. D 4 Prints as a long decimal number. d 2 Prints as a decimal number. F 8 Prints as a double floating-point number. f 4 Prints the 32-bit value as a floating-point number. i n Disassembles the addressed instruction. n 0 Prints a new line. O 4 Prints 4 bytes as an octal number. o 2 Prints 2 bytes in hexadecimal. All octal numbers output by adb are preceded by 0. p 4 Prints the addressed value in symbolic form, using the same rules for symbol lookup as a. 6 January 1992
adb(1) adb(1)Q 4 Prints as a long signed octal number. q 2 Prints as a signed octal number. r 0 Prints a space. S n Prints a string using the ^X escape convention (see C earlier in this list); n is the length of the string, including its 0 terminator. s n Prints the addressed characters until a 0 character is reached. t 0 Tabs to the next appropriate tab stop when preceded by an integer. For example, 8t causes a move to the next 8-space tab stop. U 4 Prints as a long unsigned decimal number. u 2 Prints as an unsigned decimal number. Y 4 Prints 4 bytes in data format (see ctime(3)). X 4 Prints 4 bytes as a hexadecimal number. x 2 Prints 2 bytes as a hexadecimal number. $modifier These are miscellaneous commands. These modifiers are available: <file Reads commands from file. If this command is executed in a file, further commands in the file are not seen. If file is omitted, the current input stream is terminated. If the value of count is 0, the command is ignored. The value of the count is placed in variable 9 before the first command in file is executed. <<file January 1992 7
adb(1) adb(1)Reads commands from file. This command is similar to < except it can be used in a file of commands without causing the file to be closed. Variable 9 is saved during the execution of this command and restored when the command completes. There is a (small) finite limit to the number of << files that can be open at once. >file Appends output to file, which is created if it does not exist. If file is omitted, output is returned to the terminal. ? Prints process ID, the signal that caused stoppage or termination, as well as the registers in the same way as the $r command. This option is the default if modifier is omitted. b Prints all breakpoints and their associated counts and commands. c Performs a C stack backtrace. If address is given, it is taken as the address of the current frame (instead of a7). If C is used, the names and (16-bit) values of all automatic and static variables are printed for each active function. If count is given, only the first count frames are printed. d Sets the default radix to address and reports the new value. Note that address is interpreted in the (old) current radix. Thus 10$d never changes the default radix. To make the default radix decimal, use 0t10$d. d Resets integer input as described in ``Expressions'' earlier in the ``Description'' section. e Prints the names and values of external variables. f Prints the floating-point data registers fp0-fp7 in IEEE extended precision (see >name, earlier in the ``Commands'' section for a definition), and exponential notation, along with the floating- point control registers fpcr, fpsr, and fpiar. m Prints the address map. o Regards all integers subsequently input as octal. Q Exits from adb. 8 January 1992
adb(1) adb(1)q Exits from adb. r Prints the general registers and the instruction addressed by pc. Dot is set to pc. s Sets the limit for symbol matches to address. The default is 255. v Prints all nonzero variables in hexadecimal. w Sets the page width for output to address. The default is 80. :modifier The colon (:) command and a modifier are used to manage a subprocess. These modifiers are available: bc Sets 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 0, the breakpoint causes a stop. cs Continues the subprocess with signal scs (see signal(3)). If address is given, the subprocess is continued at this address. If no signal is specified, the signal that caused the subprocess to stop is sent. Breakpoint skipping is the same as for the :r command. d Deletes breakpoint at address. k Terminates the current subprocess, if any. r Runs object-file as a subprocess. If address is given explicitly, the program is entered at this point; otherwise, the program is entered at its standard entry point. The value of count specifies how many breakpoints are to be ignored before stopping. Arguments to the subprocess can 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. All signals are turned on upon entry to the subprocess. ss Continues the subprocess as described for c, earlier in this list, except that the subprocess is single-stepped the number of times specified by count. If there is no current subprocess, the object file is run as a subprocess in the same way as for the :r command. In this case, no signal January 1992 9
adb(1) adb(1)can be sent; the remainder of the line is treated as arguments to the subprocess. Variables The adb command provides a number of variables. Named variables are set initially by adb but are not used subsequently. These numbered variables are reserved for communication: 0 The last value printed. 1 The last offset part of an instruction source. 2 The previous value of variable 1. 9 The count on the last $< or $<< command. On entry, the following variables are set from the system header in core-file. If core-file does not appear to be a core file, these values are set from object-file: b The base address of the data segment. d The data segment size. e The entry point. m The magic number (0407, 0410 , 0413). s The stack segment size. t The text segment size. Addresses The address in a file associated with a written address is determined by a mapping associated with that file. Each mapping is represented by n triples (b1,e1,f1), (b2,e2,f2), ... (bn,en,fn), corresponding to the number of sections in your object file. The file address corresponding to a written address is calculated as follows: b1<address<e1 => file-address=address+f1-b1 otherwise, b2<address<e2 => file-address=address+f2-b2 and so on. 10 January 1992
adb(1) adb(1)Otherwise, the requested address is not legal. In some cases (such as for programs with separated instruction and data space), the two segments for a file can overlap. If a question mark (?) or slash (/) is followed by an asterisk (*), the first triple is not used. The initial setting of both mappings is suitable for normal a.out and core files. If either file is not of the kind expected, for that file b1 is set to 0, e1 is set to the maximum file size, and f1 is set to 0; in this way the whole file can be examined with no address translation. So that adb can be used on large files, all appropriate values are kept as signed 32-bit integers. EXAMPLES This command starts adb on the executable file called obj1: adb obj1 When adb responds with a ready message, you can type this request: main,10?ia The request causes 16 (10 hexadecimal) instructions to be printed in assembly language, starting from main. STATUS MESSAGES AND VALUES The adb command echoes adb when there is no current command or format. The adb command produces comments about, for example, inaccessible files, syntax errors, and abnormal termination of commands. The exit status of adb is 0 unless the last command failed or returned a nonzero status. LIMITATIONS Use of the number sign (#) for the unary logical negation operator is peculiar. There doesn't seem to be any way to clear all breakpoints. In certain cases, disassembled code cannot be used directly as input to as(1). This is because adb gives more useful information than as accepts. For example, explicit register names are given in the disassembly of movm and fmovm instructions. January 1992 11
adb(1) adb(1)FILES /bin/adb Executable file a.out Default object file core Default core file SEE ALSO sdb(1) a.out(4), core(4) in A/UX Programmer's Reference 12 January 1992