![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to dbx.0 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / pgrm / dbx|
Return to dbx.0 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / pgrm / dbx |
1.1 root 1: DBX(1) UNIX Reference Manual DBX(1)
2:
3: NNAAMMEE
4: ddbbxx - debugger
5:
6: SSYYNNOOPPSSIISS
7: DDbbxx [--rr] [--ii] [--kk] [--II _d_i_r] [--cc _f_i_l_e] [_o_b_j_f_i_l_e [_c_o_r_e_d_u_m_p]]
8:
9: DDEESSCCRRIIPPTTIIOONN
10: DDbbxx is a tool for source level debugging and execution of programs under
11: UNIX. The _o_b_j_f_i_l_e is an object file produced by a compiler with the ap-
12: propriate flag (usually --gg) specified to produce symbol information in
13: the object file. Currently, cc(1), f77(1), pc(1), and the DEC Western
14: Research Laboratory Modula-2 compiler, mod(l), produce the appropriate
15: source information. The machine level facilities of ddbbxx can be used on
16: any program.
17:
18: The object file contains a symbol table that includes the names of all
19: the source files translated by the compiler to create it. These files
20: are available for perusal while using the debugger.
21:
22: If a file named _c_o_r_e exists in the current directory or a _c_o_r_e_d_u_m_p file
23: is specified, ddbbxx can be used to examine the state of the program when it
24: faulted.
25:
26: If the file ._d_b_x_i_n_i_t exists in the current directory then the debugger
27: commands in it are executed. DDbbxx also checks for a ._d_b_x_i_n_i_t in the
28: user's home directory if there isn't one in the current directory.
29:
30: The command line options and their meanings are:
31:
32: --rr Execute _o_b_j_f_i_l_e immediately. If it terminates successfully ddbbxx
33: exits. Otherwise the reason for termination will be reported
34: and the user offered the option of entering the debugger or
35: letting the program fault. DDbbxx will read from /_d_e_v/_t_t_y when --rr
36: is specified and standard input is not a terminal.
37:
38: --ii Force ddbbxx to act as though standard input is a terminal.
39:
40: --kk Map memory addresses, useful for kernel debugging.
41:
42: --II _d_i_r Add _d_i_r to the list of directories that are searched when look-
43: ing for a source file. Normally ddbbxx looks for source files in
44: the current directory and in the directory where _o_b_j_f_i_l_e is lo-
45: cated. The directory search path can also be set with the uussee
46: command.
47:
48: --cc _f_i_l_e Execute the ddbbxx commands in the _f_i_l_e before reading from stan-
49: dard input.
50:
51: Unless --rr is specified, ddbbxx just prompts and waits for a command.
52:
53: EExxeeccuuttiioonn aanndd TTrraacciinngg CCoommmmaannddss
54:
55: rruunn [_a_r_g_s] [<< _f_i_l_e_n_a_m_e] [>> _f_i_l_e_n_a_m_e]
56: rreerruunn [_a_r_g_s] [<< _f_i_l_e_n_a_m_e] [>> _f_i_l_e_n_a_m_e]
57: Start executing _o_b_j_f_i_l_e, passing _a_r_g_s as command line argu-
58: ments; << or >> can be used to redirect input or output in the
59: usual manner. When rreerruunn is used without any arguments the
60: previous argument list is passed to the program; otherwise it
61: is identical to rruunn. If _o_b_j_f_i_l_e has been written since the
62: last time the symbolic information was read in, ddbbxx will read
63: in the new information.
64: ttrraaccee [iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [iiff _c_o_n_d_i_t_i_o_n]
65: ttrraaccee _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n]
66: ttrraaccee _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n [iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [iiff _c_o_n_d_i_t_i_o_n]
67: ttrraaccee _e_x_p_r_e_s_s_i_o_n aatt _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n]
68: ttrraaccee _v_a_r_i_a_b_l_e [iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [iiff _c_o_n_d_i_t_i_o_n]
69: Have tracing information printed when the program is executed.
70: A number is associated with the command that is used to turn
71: the tracing off (see the ddeelleettee command).
72:
73: The first argument describes what is to be traced. If it is a
74: _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r, then the line is printed immediately prior
75: to being executed. Source line numbers in a file other than
76: the current one must be preceded by the name of the file in
77: quotes and a colon, e.g. "mumble.p":17.
78:
79: If the argument is a procedure or function name then every time
80: it is called, information is printed telling what routine
81: called it, from what source line it was called, and what param-
82: eters were passed to it. In addition, its return is noted, and
83: if it's a function then the value it is returning is also
84: printed.
85:
86: If the argument is an _e_x_p_r_e_s_s_i_o_n with an aatt clause then the
87: value of the expression is printed whenever the identified
88: source line is reached.
89:
90: If the argument is a variable then the name and value of the
91: variable is printed whenever it changes. Execution is substan-
92: tially slower during this form of tracing.
93:
94: If no argument is specified then all source lines are printed
95: before they are executed. Execution is substantially slower
96: during this form of tracing.
97:
98: The clause iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n restricts tracing information
99: to be printed only while executing inside the given procedure
100: or function.
101:
102: _C_o_n_d_i_t_i_o_n is a boolean expression and is evaluated prior to
103: printing the tracing information; if it is false then the in-
104: formation is not printed.
105: ssttoopp iiff _c_o_n_d_i_t_i_o_n
106: ssttoopp aatt _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n]
107: ssttoopp iinn _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n]
108: ssttoopp _v_a_r_i_a_b_l_e [iiff _c_o_n_d_i_t_i_o_n]
109: Stop execution when the given line is reached, procedure or
110: function called, variable changed, or condition true.
111: ssttaattuuss [>> _f_i_l_e_n_a_m_e]
112: Print out the currently active ttrraaccee and ssttoopp commands.
113: ddeelleettee _c_o_m_m_a_n_d-_n_u_m_b_e_r ...
114: The traces or stops corresponding to the given numbers are
115: removed. The numbers associated with traces and stops are
116: printed by the ssttaattuuss command.
117: ccaattcchh _n_u_m_b_e_r
118: ccaattcchh _s_i_g_n_a_l-_n_a_m_e
119: iiggnnoorree _n_u_m_b_e_r
120: iiggnnoorree _s_i_g_n_a_l-_n_a_m_e
121: Start or stop trapping a signal before it is sent to the
122: program. This is useful when a program being debugged handles
123: signals such as interrupts. A signal may be specified by
124: number or by a name (e.g., SIGINT). Signal names are case
125: insensitive and the ``SIG'' prefix is optional. By default all
126: signals are trapped except SIGCONT, SIGCHILD, SIGALRM and
127: SIGKILL.
128: ccoonntt _i_n_t_e_g_e_r
129: ccoonntt _s_i_g_n_a_l-_n_a_m_e
130: Continue execution from where it stopped. If a signal is
131: specified, the process continues as though it received the
132: signal. Otherwise, the process is continued as though it had
133: not been stopped.
134: Execution cannot be continued if the process has ``finished'',
135: that is, called the standard procedure ``exit''. DDbbxx does not
136: allow the process to exit, thereby letting the user to examine
137: the program state.
138: sstteepp Execute one source line.
139: nneexxtt Execute up to the next source line. The difference between
140: this and sstteepp is that if the line contains a call to a pro-
141: cedure or function the sstteepp command will stop at the beginning
142: of that block, while the nneexxtt command will not.
143: rreettuurrnn [_p_r_o_c_e_d_u_r_e]
144: Continue until a return to _p_r_o_c_e_d_u_r_e is executed, or until the
145: current procedure returns if none is specified.
146: ccaallll _p_r_o_c_e_d_u_r_e (_p_a_r_a_m_e_t_e_r_s)
147: Execute the object code associated with the named procedure or
148: function.
149:
150:
151: PPrriinnttiinngg VVaarriiaabblleess aanndd EExxpprreessssiioonnss
152: Names are resolved first using the static scope of the current function,
153: then using the dynamic scope if the name is not defined in the static
154: scope. If static and dynamic searches do not yield a result, an
155: arbitrary symbol is chosen and the message ``[using Ar qualified name]''
156: is printed. The name resolution procedure may be overridden by qualify-
157: ing an identifier with a block name, e.g., ``module.variable'' For C,
158: source files are treated as modules named by the file name without
159: ``.c''.
160:
161: Expressions are specified with an approximately common subset of C and
162: Pascal (or equivalently Modula-2) syntax. Indirection can be denoted us-
163: ing either a prefix ``*'' or a postfix ``^'' and array expressions are
164: subscripted by brackets (``[]''). The field reference operator (``.'')
165: can be used with pointers as well as records, making the C operator
166: ``->'' unnecessary (although it is supported).
167:
168: Types of expressions are checked; the type of an expression may be
169: overridden by using ``_t_y_p_e-_n_a_m_e (_e_x_p_r_e_s_s_i_o_n)''. When there is no
170: corresponding named type the special constructs ``&_t_y_p_e-_n_a_m_e'' and
171: ``$$_t_a_g-_n_a_m_e'' can be used to represent a pointer to a named type or C
172: structure tag.
173:
174: aassssiiggnn _v_a_r_i_a_b_l_e==_e_x_p_r_e_s_s_i_o_n
175: Assign the value of the expression to the variable.
176: dduummpp [_p_r_o_c_e_d_u_r_e] [>> _f_i_l_e_n_a_m_e]
177: Print the names and values of variables in the given procedure,
178: or the current one if none is specified. If the procedure
179: given is ``.'', then the all active variables are dumped.
180: pprriinntt _e_x_p_r_e_s_s_i_o_n [,, _e_x_p_r_e_s_s_i_o_n ...]
181: Print out the values of the expressions.
182: wwhhaattiiss _n_a_m_e
183: Print the declaration of the given name, which may be qualified
184: with block names as above.
185: wwhhiicchh _i_d_e_n_t_i_f_i_e_r
186: Print the full qualification of the given identifer, i.e. the
187: outer blocks that the identifier is associated with.
188: uupp [_c_o_u_n_t]
189: ddoowwnn [_c_o_u_n_t]
190: Move the current function, which is used for resolving names,
191: up or down the stack _c_o_u_n_t levels. The default _c_o_u_n_t is 1.
192: wwhheerree Print out a list of the active procedures and function.
193: wwhheerreeiiss _i_d_e_n_t_i_f_i_e_r
194: Print the full qualification of all the symbols whose name
195: matches the given identifier. The order in which the symbols
196: are printed is not meaningful.
197:
198:
199: AAcccceessssiinngg SSoouurrccee FFiilleess
200:
201: /_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n[/]
202: ?_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n[?]
203: Search forward or backward in the current source file
204: for the given pattern.
205: eeddiitt [_f_i_l_e_n_a_m_e]
206: eeddiitt _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n-_n_a_m_e
207: Invoke an editor on _f_i_l_e_n_a_m_e or the current source
208: file if none is specified. If a _p_r_o_c_e_d_u_r_e or
209: _f_u_n_c_t_i_o_n name is specified, the editor is invoked on
210: the file that contains it. Which editor is invoked
211: by default depends on the installation. The default
212: can be overridden by setting the environment variable
213: EDITOR to the name of the desired editor.
214: ffiillee [_f_i_l_e_n_a_m_e] Change the current source file name to _f_i_l_e_n_a_m_e. If
215: none is specified then the current source file name
216: is printed.
217: ffuunncc [_p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n]
218: Change the current function. If none is specified
219: then print the current function. Changing the
220: current function implicitly changes the current
221: source file to the one that contains the function; it
222: also changes the current scope used for name
223: resolution.
224: lliisstt [_s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [,,_s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r]
225: lliisstt _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n
226: List the lines in the current source file from the
227: first line number to the second inclusive. If no
228: lines are specified, the next 10 lines are listed.
229: If the name of a procedure or function is given lines
230: _n-_k to _n+_k are listed where _n is the first statement
231: in the procedure or function and _k is small.
232: uussee _d_i_r_e_c_t_o_r_y-_l_i_s_t
233: Set the list of directories to be searched when
234: looking for source files.
235:
236:
237: CCoommmmaanndd AAlliiaasseess aanndd VVaarriiaabblleess
238:
239: aalliiaass _n_a_m_e _n_a_m_e
240: aalliiaass _n_a_m_e _s_t_r_i_n_g
241: aalliiaass _n_a_m_e (_p_a_r_a_m_e_t_e_r_s) ``_s_t_r_i_n_g''
242: When commands are processed, dbx first checks to see if the
243: word is an alias for either a command or a string. If it is an
244: alias, then dbx treats the input as though the corresponding
245: string (with values substituted for any parameters) had been
246: entered. For example, to define an alias ``rr'' for the
247: command ``rerun'', one can say
248:
249: alias rr rerun
250:
251: To define an alias called ``b'' that sets a stop at a
252: particular line one can say
253:
254: alias b(x) ``stop at x''
255:
256: Subsequently, the command ``b(12)'' will expand to ``stop at
257: 12''.
258:
259: sseett _n_a_m_e[_e_x_p_r_e_s_s_i_o_n]
260: The sseett command defines values for debugger variables. The
261: names of these variables cannot conflict with names in the pro-
262: gram being debugged, and are expanded to the corresponding ex-
263: pression within other commands. The following variables have a
264: special meaning:
265:
266: $frame
267: Setting this variable to an address causes dbx to use the
268: stack frame pointed to by the address for doing stack
269: traces and accessing local variables. This facility is
270: of particular use for kernel debugging.
271: $hexchars
272: $hexints
273: $hexoffsets
274: $hexstrings
275: When set, dbx prints out out characters, integers,
276: offsets from registers, or character pointers respective-
277: ly in hexadecimal.
278: $listwindow
279: The value of this variable specifies the number of lines
280: to list around a function or when the lliisstt command is
281: given without any parameters. Its default value is 10.
282: $mapaddrs
283: Setting (unsetting) this variable causes dbx to start
284: (stop) mapping addresses. As with ``$frame'', this is
285: useful for kernel debugging.
286: $unsafecall
287: $unsafeassign
288: When ``$unsafecall'' is set, strict type checking is
289: turned off for arguments to subroutine or function calls
290: ( _e ._g. in the ccaallll statement). When ``$unsafeassign''
291: is set, strict type checking between the two sides of an
292: aassssiiggnn statement is turned off. These variables should
293: be used only with great care, because they severely limit
294: dbx's usefulness for detecting errors.
295:
296: uunnaalliiaass _n_a_m_e
297: Remove the alias with the given name.
298: uunnsseett _n_a_m_e
299: Delete the debugger variable associated with _n_a_m_e.
300:
301:
302: MMaacchhiinnee LLeevveell CCoommmmaannddss
303:
304: ttrraacceeii [_a_d_d_r_e_s_s] [_c_o_n_d]
305: ttrraacceeii [_v_a_r_i_a_b_l_e] [aatt_a_d_d_r_e_s_s] [iiff_c_o_n_d]
306: ssttooppii [_a_d_d_r_e_s_s] [iiff_c_o_n_d]
307: ssttooppii [aatt] [_a_d_d_r_e_s_s] [iiff_c_o_n_d]
308: Turn on tracing or set a stop using a machine instruction
309: address.
310: sstteeppii
311: nneexxttii Single step as in sstteepp or nneexxtt, but do a single instruction
312: rather than source line.
313: _a_d_d_r_e_s_s,_a_d_d_r_e_s_s/[_m_o_d_e]
314: _a_d_d_r_e_s_s/[_c_o_u_n_t][_m_o_d_e]
315: Print the contents of memory starting at the first _a_d_d_r_e_s_s and
316: continuing up to the second _a_d_d_r_e_s_s or until _c_o_u_n_t items are
317: printed. If the address is ``.'', the address following the
318: one printed most recently is used. The _m_o_d_e specifies how
319: memory is to be printed; if it is omitted the previous mode
320: specified is used. The initial mode is ``X''. The following
321: modes are supported:
322:
323: ii print the machine instruction
324: dd print a short word in decimal
325: DD print a long word in decimal
326: oo print a short word in octal
327: OO print a long word in octal
328: xx print a short word in hexadecimal
329: XX print a long word in hexadecimal
330: bb print a byte in octal
331: cc print a byte as a character
332: ss print a string of characters terminated by a
333: null byte
334: ff print a single precision real number
335: gg print a double precision real number
336:
337:
338: Symbolic addresses are specified by preceding the name with an
339: ``&''. Registers are denoted by ``$rN'' where N is the number
340: of the register. Addresses may be expressions made up of other
341: addresses and the operators ``+'', ``-'', and indirection
342: (unary ``*'').
343:
344:
345: MMiisscceellllaanneeoouuss CCoommmmaannddss
346:
347: ggrriippee Invoke a mail program to send a message to the person in charge
348: of ddbbxx.
349:
350: hheellpp Print out a synopsis of ddbbxx commands.
351:
352: qquuiitt Exit ddbbxx.
353:
354: sshh _c_o_m_m_a_n_d-_l_i_n_e
355: Pass the command line to the shell for execution. The SHELL
356: environment variable determines which shell is used.
357:
358: ssoouurrccee _f_i_l_e_n_a_m_e
359: Read ddbbxx commands from the given _f_i_l_e_n_a_m_e.
360:
361: EENNVVIIRROONNMMEENNTT
362: DDbbxx utilizes the following environment variables:
363: EDITOR
364: HOME
365: PATH
366: SHELL
367:
368: FFIILLEESS
369: _a._o_u_t object file
370: ._d_b_x_i_n_i_t initial commands
371:
372:
373: SSEEEE AALLSSOO
374: cc(1), mod(l), f77(1), pc(1)
375:
376: HHIISSTTOORRYY
377: DDbbxx appeared in 4.2 BSD.
378:
379: BBUUGGSS
380: DDbbxx suffers from the same ``multiple include'' malady as did ssddbb. If you
381: have a program consisting of a number of object files and each is built
382: from source files that include header files, the symbolic information for
383: the header files is replicated in each object file. Since about one de-
384: bugger start-up is done for each link, having the linker ld(1) re-
385: organize the symbol information would not save much time, though it would
386: reduce some of the disk space used.
387:
388: This problem is an artifact of the unrestricted semantics of #include's
389: in C; for example an include file can contain static declarations that
390: are separate entities for each file in which they are included. However,
391: even with Modula-2 there is a substantial amount of duplication of symbol
392: information necessary for inter-module type checking.
393:
394: Some problems remain with the support for individual languages. Fortran
395: problems include: inability to assign to logical, logical*2, complex and
396: double complex variables; inability to represent parameter constants
397: which are not type integer or real; peculiar representation for the
398: values of dummy procedures (the value shown for a dummy procedure is ac-
399: tually the first few bytes of the procedure text; to find the location of
400: the procedure, use ``&'' to take the address of the variable).
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.