1ADB(1) General Commands Manual ADB(1)
2
6 adb - debugger (2BSD)
7
9 adb [-w] [ -k ] [ -Idir ] [ objfil [ corfil ] ]
10
12 Adb is a general purpose debugging program. It may be used to examine
13 files and to provide a controlled environment for the execution of UNIX
14 programs.
15 Objfil is normally an executable program file, preferably containing a
17 symbol table; if not then the symbolic features of adb cannot be used
18 although the file can still be examined. The default for objfil is
19 a.out. Corfil is assumed to be a core image file produced after exe‐
20 cuting objfil; the default for corfil is core.
21 Requests to adb are read from the standard input and responses are to
23 the standard output. If the -w flag is present then both objfil and
24 corfil are created if necessary and opened for reading and writing so
25 that files can be modified using adb.
26 The -k option makes adb do UNIX kernel memory mapping; it should be
28 used when core is a UNIX crash dump or /dev/mem.
29 The -I option specifies a directory where files to be read with $< or
31 $<< (see below) will be sought; the default is /usr/share/adb.
32 Adb ignores QUIT; INTERRUPT causes return to the next adb command.
34 In general requests to adb are of the form
36 [address] [, count] [command] [;]
38 If address is present then dot is set to address. Initially dot is set
40 to 0. For most commands count specifies how many times the command
41 will be executed. The default count is 1. Address and count are
42 expressions.
43 The interpretation of an address depends on the context it is used in.
45 If a subprocess is being debugged then addresses are interpreted in the
46 usual way in the address space of the subprocess. For further details
47 of address mapping see ADDRESSES.
48
50 . The value of dot.
51 + The value of dot incremented by the current increment.
53 ^ The value of dot decremented by the current increment.
55 " The last address typed.
57 integer
59 An octal number if integer begins with a 0; a hexadecimal number
60 if preceded by #; otherwise a decimal number. This default
61 interpretation of integers may be changed via the $o and $d com‐
62 mands.
63 integer.fraction
65 A 32 bit floating point number.
66 ´cccc´ The ASCII value of up to 4 characters. \ may be used to escape
68 a ´.
69 < name The value of name, which is either a variable name or a register
71 name. Adb maintains a number of variables (see VARIABLES) named
72 by single letters or digits. If name is a register name then
73 the value of the register is obtained from the system header in
74 corfil. The register names are those printed by the $r command.
75 symbol A symbol is a sequence of upper or lower case letters, under‐
77 scores or digits, not starting with a digit. The backslash
78 character \ may be used to escape other characters. The value
79 of the symbol is taken from the symbol table in objfil. An ini‐
80 tial _ or ~ will be prepended to symbol if needed. If the sym‐
81 bol is a text symbol and objfil is an overlay type, the default
82 is ~symbol, which is the subroutine itself, not the entry inter‐
83 face in the base segment.
84 _ symbol
86 In C, the `true name' of an external symbol begins with _. It
87 may be necessary to utter this name to distinguish it from
88 internal or hidden variables of a program. For a subroutine in
89 an overlay, ~symbol is the actual subroutine, and _symbol is the
90 entry point in the base segment (the "thunk"). Note that to
91 explicitly specify the local name, the ~ must be preceeded by a
92 backslash, since ~ is the bitwise complement operator: \~symbol
93 must be typed.
94 routine.name
96 The address of the variable name in the specified C routine.
97 Both routine and name are symbols. If name is omitted the value
98 is the address of the most recently activated C stack frame cor‐
99 responding to routine.
100 (exp) The value of the expression exp.
102 Monadic operators
104 *exp The contents of the location addressed by exp in corfil.
106 @exp The contents of the location addressed by exp in objfil.
108 -exp Integer negation.
110 ~exp Bitwise complement.
112 Dyadic operators are left associative and are less binding than monadic
114 operators.
115 e1+e2 Integer addition.
117 e1-e2 Integer subtraction.
119 e1*e2 Integer multiplication.
121 e1%e2 Integer division.
123 e1&e2 Bitwise conjunction.
125 e1⎪e2 Bitwise disjunction.
127 e1#e2 E1 rounded up to the next multiple of e2.
129
131 Most commands consist of a verb followed by a modifier or list of modi‐
132 fiers. The following verbs are available. (The commands `?' and `/'
133 may be followed by `*'; see ADDRESSES for further details.)
134 ?f Locations starting at address in objfil are printed according to
136 the format f. dot is incremented by the sum of the increments for
137 each format letter (q.v.).
138 /f Locations starting at address in corfil are printed according to
140 the format f and dot is incremented as for `?'.
141 =f The value of address itself is printed in the styles indicated by
143 the format f. (For i format `?' is printed for the parts of the
144 instruction that reference subsequent words.)
145 A format consists of one or more characters that specify a style of
147 printing. Each format character may be preceded by a decimal integer
148 that is a repeat count for the format character. While stepping
149 through a format dot is incremented temporarily by the amount given for
150 each format letter. If no format is given then the last format is
151 used. The format letters available are as follows.
152 o 2 Print 2 bytes in octal. All octal numbers output by adb
154 are preceded by 0.
155 O 4 Print 4 bytes in octal.
156 q 2 Print in signed octal.
157 Q 4 Print long signed octal.
158 d 2 Print in decimal.
159 D 4 Print long decimal.
160 x 2 Print 2 bytes in hexadecimal.
161 X 4 Print 4 bytes in hexadecimal.
162 u 2 Print as an unsigned decimal number.
163 U 4 Print long unsigned decimal.
164 f 4 Print the 32 bit value as a floating point number.
165 F 8 Print double floating point.
166 b 1 Print the addressed byte in octal.
167 c 1 Print the addressed character.
168 C 1 Print the addressed character using the following escape
169 convention. the standard escape convention where control
170 characters are printed as ^X and the delete character is
171 printed as ^?.
172 s n Print the addressed characters until a zero character is
173 reached.
174 S n Print a string using the ^X escape convention (see C
175 above). n is the length of the string including its zero
176 terminator.
177 Y 4 Print 4 bytes in date format (see ctime(3)).
178 i n Print as machine instructions. n is the number of bytes
179 occupied by the instruction. This style of printing
180 causes variables 1 and 2 to be set to the offset parts of
181 the source and destination respectively.
182 a 0 Print the value of dot in symbolic form. Symbols are
183 checked to ensure that they have an appropriate type as
184 indicated below.
185 / local or global data symbol
187 ? local or global text symbol
188 = local or global absolute symbol
189 p 2 Print the addressed value in symbolic form using the same
191 rules for symbol lookup as a.
192 t 0 When preceded by an integer tabs to the next appropriate
193 tab stop. For example, 8t moves to the next 8-space tab
194 stop.
195 r 0 Print a space.
196 n 0 Print a newline.
197 "..." 0
198 Print the enclosed string.
199 ^ Dot is decremented by the current increment. Nothing is
200 printed.
201 + Dot is incremented by 1. Nothing is printed.
202 - Dot is decremented by 1. Nothing is printed.
203 newline
205 If the previous command temporarily incremented dot, make the
206 increment permanent. Repeat the previous command with a count
207 of 1.
208 [?/]l value mask
210 Words starting at dot are masked with mask and compared with
211 value until a match is found. If L is used then the match is
212 for 4 bytes at a time instead of 2. If no match is found then
213 dot is unchanged; otherwise dot is set to the matched location.
214 If mask is omitted then -1 is used.
215 [?/]w value ...
217 Write the 2-byte value into the addressed location. If the com‐
218 mand is W, write 4 bytes. Odd addresses are not allowed when
219 writing to the subprocess address space.
220 [?/]m b1 e1 f1[?/]
222 New values for (b1, e1, f1) are recorded. If less than three
223 expressions are given then the remaining map parameters are left
224 unchanged. If the `?' or `/' is followed by `*' then the last
225 segment (b2,e2,f2) of the mapping is changed. If the list is
226 terminated by `?' or `/' then the file (objfil or corfil respec‐
227 tively) is used for subsequent requests. (So that, for example,
228 `/m?' will cause `/' to refer to objfil.)
229 >name Dot is assigned to the variable or register named.
231 ! A shell (/bin/sh) is called to read the rest of the line follow‐
233 ing `!'.
234 $modifier
236 Miscellaneous commands. The available modifiers are:
237 <f Read commands from the file f. If this command is exe‐
239 cuted in a file, further commands in the file are not
240 seen. If f is omitted, the current input stream is ter‐
241 minated. If a count is given, and is zero, the command
242 will be ignored. The value of the count will be placed
243 in variable 9 before the first command in f is executed.
244 <<f Similar to < except it can be used in a file of commands
245 without causing the file to be closed. Variable 9 is
246 saved during the execution of this command, and restored
247 when it completes. There is a (small) finite limit to
248 the number of << files that can be open at once.
249 >f Append output to the file f, which is created if it does
250 not exist. If f is omitted, output is returned to the
251 terminal.
252 ? Print process id, the signal which caused stoppage or
253 termination, as well as the registers as $r. This is the
254 default if modifier is omitted.
255 r Print the general registers and the instruction addressed
256 by pc. Dot is set to pc.
257 f Print the floating registers in single or double length.
258 If the floating point status of ps is set to double (0200
259 bit) then double length is used anyway.
260 b Print all breakpoints and their associated counts and
261 commands.
262 a ALGOL 68 stack backtrace. If address is given then it is
263 taken to be the address of the current frame (instead of
264 r4). If count is given then only the first count frames
265 are printed.
266 c C stack backtrace. If address is given then it is taken
267 as the address of the current frame instead of the con‐
268 tents of the frame-pointer register. If C is used then
269 the names and (16 bit) values of all automatic and static
270 variables are printed for each active function. If count
271 is given then only the first count frames are printed.
272 e The names and values of external variables are printed.
273 w Set the page width for output to address (default 80).
274 s Set the limit for symbol matches to address (default
275 255).
276 o All integers input are regarded as octal.
277 d Reset integer input as described in EXPRESSIONS.
278 q Exit from adb.
279 v Print all non zero variables in octal.
280 m Print the address map.
281 :modifier
283 Manage a subprocess. Available modifiers are:
284 bc Set breakpoint at address. If objfil is overlaid and
286 address is in the overlay region, the breakpoint is set
287 in the overlay of the symbol mentioned if address was
288 given symbolically, otherwise it is set in the current
289 overlay (that in variable c). The breakpoint is executed
290 count-1 times before causing a stop. Each time the
291 breakpoint is encountered the command c is executed. If
292 this command is omitted or sets dot to zero then the
293 breakpoint causes a stop.
294 d Delete breakpoint at address.
296 r Run objfil as a subprocess. If address is given explic‐
298 itly then the program is entered at this point; otherwise
299 the program is entered at its standard entry point.
300 count specifies how many breakpoints are to be ignored
301 before stopping. Arguments to the subprocess may be sup‐
302 plied on the same line as the command. An argument
303 starting with < or > causes the standard input or output
304 to be established for the command.
305 cs The subprocess is continued with signal s, see sigvec(2).
307 If address is given then the subprocess is continued at
308 this address. If no signal is specified then the signal
309 that caused the subprocess to stop is sent. Breakpoint
310 skipping is the same as for r.
311 ss As for c except that the subprocess is single stepped
313 count times. If there is no current subprocess then obj‐
314 fil is run as a subprocess as for r. In this case no
315 signal can be sent; the remainder of the line is treated
316 as arguments to the subprocess.
317 k The current subprocess, if any, is terminated.
319
321 Adb provides a number of variables. Named variables are set initially
322 by adb but are not used subsequently (except for c). Numbered vari‐
323 ables are reserved for communication as follows.
324 0 The last value printed.
326 1 The last offset part of an instruction source.
327 2 The previous value of variable 1.
328 9 The count on the last $< or $<< command.
329 On entry the following are set from the system header in the corfil.
331 If corfil does not appear to be a core file then these values are set
332 from objfil.
333 b The base address of the data segment.
335 c The current overlay. This is set from corfil, and in turn sets
336 the overlay map. This variable and the map may be changed by
337 referring to other overlays symbolically (e.g. by examining text
338 in subroutines in other overlays), using the $r command (which
339 resets c from the core file), or explicitly (with the command
340 >c).
341 d The data segment size.
342 e The entry point.
343 m The `magic' number (0405, 0407, 0410, 0411, 0430 or 0431). The
344 object is overlaid if m is 0430 or 0431.
345 o The sum of the overlay segment sizes (if overlaid).
346 s The stack segment size.
347 t The text segment size.
348
350 The address in a file associated with a written address is determined
351 by a mapping associated with that file. Each mapping is represented by
352 two or three triples (b1, e1, f1), (bo, eo, fo) for overlaid object
353 files, and (b2, e2, f2) and the file address corresponding to a written
354 address is calculated as follows.
355 b1≤address<e1 => file address=address+f1-b1, otherwise,
357 if overlaid,
359 bo≤address<eo => file address=address+fo-bo, otherwise,
360 b2≤address<e2 => file address=address+f2-b2,
362 otherwise, the requested address is not legal. In some cases (e.g. for
364 programs with separated I and D space) the two segments for a file may
365 overlap. If a ? or / is followed by an * then only the last triple is
366 used.
367 The initial setting of both mappings is suitable for normal a.out and
369 core files. If the object file is not of the kind expected then, for
370 both files, b1 is set to 0, e1 is set to the maximum file size and f1
371 is set to 0; in this way the whole file can be examined with no address
372 translation.
373 So that adb may be used on large files all appropriate values are kept
375 as signed 32 bit integers.
376
378 a.out
379 core
380
382 cc(1), ptrace(2), a.out(5), core(5)
383 ADB - A Tutorial, S. R. Bourne
384
386 `Adb' when there is no current command or format. Comments about inac‐
387 cessible files, syntax errors, abnormal termination of commands, etc.
388 Exit status is 0, unless last command failed or returned nonzero sta‐
389 tus.
390
392 When single stepping, system calls do not count as an executed instruc‐
393 tion.
394 Local variables whose names are the same as an external variable may
395 foul up the accessing of the external.
396 Local variables cannot be accessed in routines that are in overlays.
397 Since no shell is invoked to interpret the arguments of the :r command,
398 the customary wild-card and variable expansions cannot occur.
3993rd Berkeley Distribution October 21, 1996 ADB(1)