![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to dbx.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / man / man1|
Return to dbx.1 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / man / man1 |
1.1 root 1: .\" Copyright (c) 1983 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)dbx.1 6.2 (Berkeley) 1/12/86
6: .\"
7: .TH DBX 1 "January 12, 1986"
8: .UC 5
9: .ds dB dbx
10: .ds DB Dbx
11: .SH NAME
12: dbx \- debugger
13: .SH SYNOPSIS
14: .B dbx
15: [
16: .B \-r
17: ] [
18: .B \-i
19: ] [
20: .B \-k
21: ] [
22: .B \-I
23: .I dir
24: ] [
25: .B \-c
26: .I file
27: ] [
28: .I objfile
29: [
30: .I coredump
31: ]]
32: .SH DESCRIPTION
33: \fI\*(DB\fP is a tool for source level debugging and execution of
34: programs under UNIX.
35: The \fIobjfile\fP is an object file produced by a compiler
36: with the appropriate flag (usually ``\-g'')
37: specified to produce symbol information in the object file.
38: Currently, \fIcc\fP(1), \fIf77\fP(1), \fIpc\fP(1), and the DEC Western
39: Research Laboratory Modula-2 compiler, \fImod\fP(l),
40: produce the appropriate source information.
41: The machine level facilities of \fI\*(dB\fP
42: can be used on any program.
43: .PP
44: The object file contains a symbol table that includes the name of the
45: all the source files translated by the compiler to create it.
46: These files are available for perusal while using the debugger.
47: .PP
48: If a file named ``core'' exists in the current directory
49: or a \fIcoredump\fP file is specified, \fI\*(dB\fP can be used
50: to examine the state of the program when it faulted.
51: .PP
52: If the file ``.\*(dBinit'' exists in the current directory then the
53: debugger commands in it are executed.
54: \fI\*(DB\fP also checks for a ``.\*(dBinit'' in the user's home directory
55: if there isn't one in the current directory.
56: .PP
57: The command line options and their meanings are:
58: .nr In 8
59: .in +\n(Inn
60: .ta \n(Inn
61: .sp 1
62: .ti -\n(Inn
63: \&\fB\-r\fP \c
64: Execute \fIobjfile\fP immediately.
65: If it terminates successfully \fI\*(dB\fP exits.
66: Otherwise the reason for termination will be reported
67: and the user offered the option of entering the debugger
68: or letting the program fault.
69: \fI\*(DB\fP will read from ``/dev/tty'' when \fB\-r\fP is specified
70: and standard input is not a terminal.
71: .sp 1
72: .ti -\n(Inn
73: \&\fB\-i\fP \c
74: Force \fI\*(dB\fP to act as though standard input is a terminal.
75: .sp 1
76: .ti -\n(Inn
77: \&\fB\-k\fP \c
78: Map memory addresses, useful for kernel debugging.
79: .sp 1
80: .ti -\n(Inn
81: \&\fB\-I\fP \fIdir\fP \c
82: Add \fIdir\fP to the list of directories
83: that are searched when looking for a source file.
84: Normally \fI\*(dB\fP looks for source files in the current directory
85: and in the directory where \fIobjfile\fP is located.
86: The directory search path can also be set with the \fBuse\fP command.
87: .sp 1
88: .ti -\n(Inn
89: \&\fB\-c\fP \fIfile\fP \c
90: Execute the \fI\*(dB\fP commands in the \fIfile\fP before
91: reading from standard input.
92: .in -\n(Inn
93: .sp 1
94: .PP
95: Unless \fB\-r\fP is specified, \fI\*(dB\fP just prompts and waits for a command.
96: .sp 1
97: .ne 8
98: .B Execution and Tracing Commands
99: .sp 1
100: .TP
101: \fBrun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP]
102: .ns
103: .TP
104: \fBrerun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP]
105: Start executing \fIobjfile\fP, passing \fIargs\fP as command line arguments;
106: \fB<\fP or \fB>\fP can be used to redirect input or output in the usual manner.
107: When \fBrerun\fP is used without any arguments the previous
108: argument list is passed to the program;
109: otherwise it is identical to \fBrun\fP.
110: If \fIobjfile\fP has been written since the last time the symbolic information
111: was read in, \fI\*(dB\fP will read in the new information.
112: .TP
113: \fBtrace\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP]
114: .ns
115: .TP
116: \fBtrace\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]
117: .ns
118: .TP
119: \fBtrace\fP \fIprocedure/function\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP]
120: .ns
121: .TP
122: \fBtrace\fP \fIexpression\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]
123: .ns
124: .TP
125: \fBtrace\fP \fIvariable\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP]
126: Have tracing information printed when the program is executed.
127: A number is associated with the command that is used
128: to turn the tracing off (see the \fBdelete\fP command).
129: .sp 1
130: The first argument describes what is to be traced.
131: If it is a \fIsource-line-number\fP, then the line is printed
132: immediately prior to being executed.
133: Source line numbers in a file other than the current one
134: must be preceded by the name of the file in quotes and a colon, e.g.
135: "mumble.p":17.
136: .sp 1
137: If the argument is a procedure or function name then
138: every time it is called, information is printed telling
139: what routine called it, from what source line it was called,
140: and what parameters were passed to it.
141: In addition, its return is noted, and if it's a function
142: then the value it is returning is also printed.
143: .sp 1
144: If the argument is an \fIexpression\fP with an \fBat\fP clause
145: then the value of the expression is printed whenever the
146: identified source line is reached.
147: .sp 1
148: If the argument is a variable then the name and value of the variable
149: is printed whenever it changes.
150: Execution is substantially slower during this form of tracing.
151: .sp 1
152: If no argument is specified then all source lines are printed
153: before they are executed.
154: Execution is substantially slower during this form of tracing.
155: .sp 1
156: The clause ``\fBin\fP \fIprocedure/function\fP'' restricts tracing information
157: to be printed only while executing inside the given procedure
158: or function.
159: .sp 1
160: \fICondition\fP is a boolean expression and is
161: evaluated prior to printing the tracing information;
162: if it is false then the information is not printed.
163: .br
164: .ne 10
165: .IP "\fBstop\fP \fBif\fP \fIcondition\fP"
166: .ns
167: .IP "\fBstop\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]"
168: .ns
169: .IP "\fBstop\fP \fBin\fP \fIprocedure/function\fP [\fBif\fP \fIcondition\fP]"
170: .ns
171: .IP "\fBstop\fP \fIvariable\fP [\fBif\fP \fIcondition\fP]"
172: Stop execution when the given line is reached, procedure or function
173: called, variable changed, or condition true.
174: .IP "\fBstatus\fP [\fB>\fP \fIfilename\fP]"
175: Print out the currently active \fBtrace\fP and \fBstop\fP commands.
176: .IP "\fBdelete\fP \fIcommand-number\fP ..."
177: The traces or stops corresponding to the given numbers are removed.
178: The numbers associated with traces and stops are printed by
179: the \fBstatus\fP command.
180: .IP "\fBcatch\fP \fInumber\fP"
181: .ns
182: .IP "\fBcatch\fP \fIsignal-name\fP"
183: .ns
184: .IP "\fBignore\fP \fInumber\fP"
185: .ns
186: .IP "\fBignore\fP \fIsignal-name\fP"
187: Start or stop trapping a signal before it is sent
188: to the program.
189: This is useful when a program being debugged
190: handles signals such as interrupts.
191: A signal may be specified by number or by a name
192: (e.g., SIGINT).
193: Signal names are case insensitive and the ``SIG'' prefix is optional.
194: By default all signals are trapped except SIGCONT, SIGCHILD,
195: SIGALRM and SIGKILL.
196: .IP "\fBcont\fP \fIinteger\fP"
197: .ns
198: .IP "\fBcont\fP \fIsignal-name\fP"
199: Continue execution from where it stopped.
200: If a signal is specified, the process continues as though
201: it received the signal.
202: Otherwise, the process is continued as though it had not been stopped.
203: .PP
204: Execution cannot be continued if the process has ``finished'',
205: that is, called the standard procedure ``exit''.
206: \fI\*(DB\fP does not allow the process to exit, thereby
207: letting the user to examine the program state.
208: .IP \fBstep\fP
209: Execute one source line.
210: .IP \fBnext\fP
211: Execute up to the next source line.
212: The difference between this and \fBstep\fP is that
213: if the line contains a call to a procedure or function
214: the \fBstep\fP command will stop at the beginning of that
215: block, while the \fBnext\fP command will not.
216: .IP "\fBreturn\fP [\fIprocedure\fP]"
217: Continue until a return to \fIprocedure\fP is executed, or
218: until the current procedure returns if none is specified.
219: .IP "\fBcall\fP \fIprocedure(parameters)\fP"
220: Execute the object code associated with the named procedure or function.
221: .sp 1
222: .br
223: .ne 8v
224: .PP
225: .B Printing Variables and Expressions
226: .sp 1
227: .PP
228: Names are resolved first using the static scope of the current function,
229: then using the dynamic scope if the name is not defined
230: in the static scope.
231: If static and dynamic searches do not yield a result,
232: an arbitrary symbol is chosen and
233: the message ``[using\ \fIqualified\ name\fP]'' is printed.
234: The name resolution procedure may be overridden by qualifying an identifier
235: with a block name, e.g., ``\fImodule\fP.\fIvariable\fP''.
236: For C, source files are treated as modules named
237: by the file name without ``.c''.
238: .PP
239: Expressions are specified with an approximately
240: common subset of C and Pascal (or equivalently Modula-2) syntax.
241: Indirection can be denoted using either a prefix ``*'' or
242: a postfix ``^'' and
243: array expressions are subscripted by brackets (``[ ]'').
244: The field reference operator (``.'') can be used with pointers
245: as well as records, making the C operator ``->'' unnecessary
246: (although it is supported).
247: .PP
248: Types of expressions are checked;
249: the type of an expression may be overridden
250: by using ``\fItype-name\fP(\fIexpression\fP)''.
251: When there is no corresponding named type
252: the special constructs ``&\fItype-name\fP'' and ``$$\fItag-name\fP''
253: can be used to represent a pointer to a named type or C structure tag.
254: .sp 1
255: .IP "\fBassign\fP \fIvariable\fP \fB=\fP \fIexpression\fP"
256: Assign the value of the expression to the variable.
257: .IP "\fBdump\fP [\fIprocedure\fR] [\fB>\fP \fIfilename\fP]"
258: Print the names and values of variables in the given procedure,
259: or the current one if none is specified.
260: If the procedure given is ``.'', then the all active variables
261: are dumped.
262: .IP "\fBprint\fP \fIexpression\fP [\fB,\fP \fIexpression\fP ...]"
263: Print out the values of the expressions.
264: .IP "\fBwhatis\fP \fIname\fP"
265: Print the declaration of the given name, which may be qualified
266: with block names as above.
267: .IP "\fBwhich\fP \fIidentifier\fP"
268: Print the full qualification of the given identifer, i.e.
269: the outer blocks that the identifier is associated with.
270: .IP "\fBup\fP [\fIcount\fP]"
271: .ns
272: .IP "\fBdown\fP [\fIcount\fP]"
273: Move the current function, which is used for resolving names,
274: up or down the stack \fIcount\fP levels.
275: The default \fIcount\fP is 1.
276: .IP \fBwhere\fP
277: Print out a list of the active procedures and function.
278: .IP "\fBwhereis\fP \fIidentifier\fP"
279: Print the full qualification of all the symbols whose
280: name matches the given identifier.
281: The order in which the symbols are printed is not meaningful.
282: .sp 1
283: .br
284: .ne 8v
285: .PP
286: .B Accessing Source Files
287: .sp 1
288: .IP "/\fIregular\ expression\fP[/]"
289: .ns
290: .IP "?\fIregular\ expression\fP[?]"
291: Search forward or backward in the current source file
292: for the given pattern.
293: .IP "\fBedit\fP [\fIfilename\fP]"
294: .ns
295: .IP "\fBedit\fP \fIprocedure/function-name\fP"
296: Invoke an editor on \fIfilename\fP or the current source file if none
297: is specified.
298: If a \fIprocedure\fP or \fIfunction\fP name is specified,
299: the editor is invoked on the file that contains it.
300: Which editor is invoked by default depends on the installation.
301: The default can be overridden by setting the environment variable
302: EDITOR to the name of the desired editor.
303: .IP "\fBfile\fP [\fIfilename\fP]"
304: Change the current source file name to \fIfilename\fP.
305: If none is specified then the current source file name is printed.
306: .IP "\fBfunc\fP [\fIprocedure/function\fP]"
307: Change the current function.
308: If none is specified then print the current function.
309: Changing the current function implicitly changes the current source file
310: to the one that contains the function; it also changes the current scope
311: used for name resolution.
312: .IP "\fBlist\fP [\fIsource-line-number\fP [\fB,\fP \fIsource-line-number\fP]]"
313: .ns
314: .IP "\fBlist\fP \fIprocedure/function\fP"
315: List the lines in the current source file from the first line number to
316: the second inclusive.
317: If no lines are specified, the next 10 lines are listed.
318: If the name of a procedure or function is given
319: lines \fIn-k\fP to \fIn+k\fP are listed where \fIn\fP is the first statement
320: in the procedure or function and \fIk\fP is small.
321: .IP "\fBuse\fP \fIdirectory-list\fP"
322: Set the list of directories to be searched
323: when looking for source files.
324: .sp 1
325: .br
326: .ne 8v
327: .PP
328: .B Command Aliases and Variables
329: .sp 1
330: .TP
331: \fBalias\fP \fIname\fP \fIname\fP
332: .ns
333: .TP
334: \fBalias\fP \fIname\fP ``\fIstring\fP''
335: .ns
336: .TP
337: \fBalias\fP \fIname\fP (\fIparameters\fP) ``\fIstring\fP''
338: When commands are processed,
339: \*(dB first checks to see if the word
340: is an alias for either a command or a string.
341: If it is an alias, then \*(dB treats the input as though
342: the corresponding string (with values substituted for any parameters)
343: had been entered.
344: For example,
345: to define an alias ``rr'' for the command ``rerun'',
346: one can say
347: .sp 1
348: .in +8n
349: alias rr rerun
350: .in -8n
351: .sp 1
352: To define an alias called ``b'' that sets a stop at a particular line
353: one can say
354: .sp 1
355: .in +8n
356: alias b(x) ``stop at x''
357: .in -8n
358: .sp 1
359: Subsequently, the command ``b(12)'' will expand to ``stop at 12''.
360: .need 5
361: .TP
362: \fBset\fP \fIname\fP [= \fIexpression\fP]
363: The \fBset\fP command defines values for debugger variables.
364: The names of these variables cannot conflict with names in the program
365: being debugged, and are expanded to the corresponding expression
366: within other commands.
367: The following variables have a special meaning:
368: .sp 1
369: .in +8n
370: .ti -5n
371: $frame
372: .br
373: Setting this variable to an address causes \*(dB to use the stack frame
374: pointed to by the address for
375: doing stack traces and accessing local variables.
376: This facility is of particular use for kernel debugging.
377: .sp 1
378: .ti -5n
379: $hexchars
380: .ti -5n
381: $hexints
382: .ti -5n
383: $hexoffsets
384: .ti -5n
385: $hexstrings
386: .br
387: When set, \*(dB prints out
388: out characters, integers, offsets from registers, or character pointers
389: respectively in hexadecimal.
390: .sp 1
391: .ti -5n
392: $listwindow
393: .br
394: The value of this variable specifies the number
395: of lines to list around a function or when the \fBlist\fP command
396: is given without any parameters.
397: Its default value is 10.
398: .sp 1
399: .ti -5n
400: $mapaddrs
401: .br
402: Setting (unsetting) this variable causes \*(dB to start (stop)
403: mapping addresses.
404: As with ``$frame'', this is useful for kernel debugging.
405: .sp 1
406: .ti -5n
407: $unsafecall
408: .ti -5n
409: $unsafeassign
410: .br
411: When ``$unsafecall'' is set,
412: strict type checking is turned off for arguments to
413: subroutine or function calls (\fIe.g.\fP in the \fBcall\fP statement).
414: When ``$unsafeassign'' is set,
415: strict type checking between the two sides
416: of an \fBassign\fP statement is turned off.
417: These variables should be used only with great care,
418: because they severely limit \*(dB's usefulness
419: for detecting errors.
420: .in -8n
421: .TP
422: \fBunalias\fP \fIname\fP
423: Remove the alias with the given name.
424: .TP
425: \fBunset\fP \fIname\fP
426: Delete the debugger variable associated with \fIname\fP.
427: .sp 1
428: .br
429: .ne 8v
430: .PP
431: .B Machine Level Commands
432: .sp 1
433: .TP
434: \fBtracei\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP]
435: .ns
436: .TP
437: \fBtracei\fP [\fIvariable\fP] [\fBat\fP \fIaddress\fP] [\fBif\fP \fIcond\fP]
438: .ns
439: .TP
440: \fBstopi\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP]
441: .ns
442: .TP
443: \fBstopi\fP [\fBat\fP] [\fIaddress\fP] [\fBif\fP \fIcond\fP]
444: Turn on tracing or set a stop using a machine instruction address.
445: .TP
446: \fBstepi\fP
447: .ns
448: .TP
449: \fBnexti\fP
450: Single step as in \fBstep\fP or \fBnext\fP, but do a single instruction
451: rather than source line.
452: .TP
453: \fIaddress\fP \fB,\fP\fIaddress\fP\fB/\fP [\fImode\fP]
454: .ns
455: .TP
456: \fIaddress\fP \fB/\fP [\fIcount\fP] [\fImode\fP]
457: Print the contents of memory starting at the first \fIaddress\fP
458: and continuing up to the second \fIaddress\fP or until \fIcount\fP items are printed.
459: If the address is ``.'', the address following the one
460: printed most recently is used.
461: The \fImode\fP specifies how memory is to be printed;
462: if it is omitted the previous mode specified is used.
463: The initial mode is ``X''.
464: The following modes are supported:
465: .nr In 5
466: .in +\n(Inn
467: .ta \n(Inn
468: .sp 1
469: .ti -\n(Inn
470: \&\fBi\fP \c
471: print the machine instruction
472: .ti -\n(Inn
473: \&\fBd\fP \c
474: print a short word in decimal
475: .ti -\n(Inn
476: \&\fBD\fP \c
477: print a long word in decimal
478: .ti -\n(Inn
479: \&\fBo\fP \c
480: print a short word in octal
481: .ti -\n(Inn
482: \&\fBO\fP \c
483: print a long word in octal
484: .ti -\n(Inn
485: \&\fBx\fP \c
486: print a short word in hexadecimal
487: .ti -\n(Inn
488: \&\fBX\fP \c
489: print a long word in hexadecimal
490: .ti -\n(Inn
491: \&\fBb\fP \c
492: print a byte in octal
493: .ti -\n(Inn
494: \&\fBc\fP \c
495: print a byte as a character
496: .ti -\n(Inn
497: \&\fBs\fP \c
498: print a string of characters terminated by a null byte
499: .ti -\n(Inn
500: \&\fBf\fP \c
501: print a single precision real number
502: .ti -\n(Inn
503: \&\fBg\fP \c
504: print a double precision real number
505: .in -\n(Inn
506: .sp 1
507: .PP
508: Symbolic addresses are specified by preceding the name with an ``&''.
509: Registers are denoted by ``$rN'' where N is the number of the register.
510: Addresses may be expressions made up of other addresses and
511: the operators ``+'', ``-'', and indirection (unary ``*'').
512: .sp 1
513: .br
514: .ne 8v
515: .PP
516: .B Miscellaneous Commands
517: .sp 1
518: .IP \fBgripe\fP
519: Invoke a mail program to send a message to the person in charge of \fI\*(dB\fP.
520: .IP \fBhelp\fP
521: Print out a synopsis of \fI\*(dB\fP commands.
522: .IP "\fBquit\fP"
523: Exit \fI\*(dB\fP.
524: .IP "\fBsh\fP \fIcommand-line\fP"
525: Pass the command line to the shell for execution.
526: The SHELL environment variable determines which shell is used.
527: .TP
528: \fBsource\fP \fIfilename\fP
529: Read \fI\*(dB\fP commands from the given \fIfilename\fP.
530: .SH FILES
531: .nr In 20
532: .in +\n(Inn
533: .ta \n(Inn
534: .sp 1
535: .ti -\n(Inn
536: \&a.out \c
537: object file
538: .ti -\n(Inn
539: \&\&.\*(dBinit \c
540: initial commands
541: .SH SEE ALSO
542: cc(1), f77(1), pc(1), mod(l)
543: .SH COMMENTS
544: \fI\*(DB\fP suffers from the same ``multiple include'' malady as did \fIsdb\fP.
545: If you have a program consisting of a number of object files
546: and each is built from source files that include header files,
547: the symbolic information for the header files is replicated in
548: each object file.
549: Since about one debugger start-up is done for each link,
550: having the linker (ld) re-organize the symbol information
551: would not save much time, though it would reduce some of the
552: disk space used.
553: .PP
554: This problem is an artifact of the unrestricted semantics
555: of #include's in C; for example an include file can contain
556: static declarations that are separate entities for each file
557: in which they are included.
558: However, even with Modula-2 there is a substantial amount of duplication
559: of symbol information necessary for inter-module type checking.
560: .PP
561: Some problems remain with the support for individual languages.
562: Fortran problems include:
563: inability to assign to logical, logical*2, complex
564: and double complex variables;
565: inability to represent parameter constants
566: which are not type integer or real;
567: peculiar representation for the values of dummy procedures
568: (the value shown for a dummy procedure is actually
569: the first few bytes of the procedure text;
570: to find the location of the procedure,
571: 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.