BSD 3 development

[unix-history] / usr / man / man1 / sdb.1

diff --git a/usr/man/man1/sdb.1 b/usr/man/man1/sdb.1
index 7e4d9b4..447a94f 100644 (file)
--- a/usr/man/man1/sdb.1
+++ b/usr/man/man1/sdb.1
@@ -1,17 +1,17 @@
-.TH SDB 1 UNIX/32V
+.TH SDB 1 VAX/11

 .SH NAME
 .SH NAME

-sdb \- C symbolic debugger
+sdb \- symbolic debugger

 .SH SYNOPSIS
 .B sdb
 [ objfil [ corfil [ directory ] ] ]
 .SH DESCRIPTION
 .I Sdb
 .SH SYNOPSIS
 .B sdb
 [ objfil [ corfil [ directory ] ] ]
 .SH DESCRIPTION
 .I Sdb

-is a symbolic debugger for C programs.
+is a symbolic debugger which can be used with C and F77 programs.

 It may be used to examine their files and to provide
 a controlled environment for their execution.
 .PP
 .I Objfil
 It may be used to examine their files and to provide
 a controlled environment for their execution.
 .PP
 .I Objfil

-is an executable C program file
+is an executable program file

 which has been compiled with the -g (debug) option.
 The default for
 .I objfil
 which has been compiled with the -g (debug) option.
 The default for
 .I objfil


@@ -39,7 +39,7 @@ Otherwise, they are set to the first line in main.
 The current line and file may be changed with the source file
 examination commands.
 .PP
 The current line and file may be changed with the source file
 examination commands.
 .PP

-Names of variables are written just as they are in C.
+Names of variables are written just as they are in C or F77.

 Variables local to a procedure may be accessed using the form
 `procedure:variable'.
 If no procedure name is given, the procedure containing the
 Variables local to a procedure may be accessed using the form
 `procedure:variable'.
 If no procedure name is given, the procedure containing the


@@ -58,6 +58,8 @@ or `procedure:number'.
 In either case the number is relative to the beginning of the file.
 If no procedure or file name is given,
 the current file is used by default.
 In either case the number is relative to the beginning of the file.
 If no procedure or file name is given,
 the current file is used by default.

+If no number is given,
+the first line of the named procedure or file is used.

 .sp 1
 .PP
 The commands for examining data in the program are:
 .sp 1
 .PP
 The commands for examining data in the program are:


@@ -65,51 +67,75 @@ The commands for examining data in the program are:
 .B t
 Print a stack trace of the terminated or stopped program.
 .TP 5
 .B t
 Print a stack trace of the terminated or stopped program.
 .TP 5

-variable/\fIm\fP
-Print the value of variable according to format 
+.B T
+Print the top line of the stack trace.
+.TP 5
+variable/\fIlm\fP
+Print the value of variable according to
+length
+.I l
+and format 

 .I m.
 If 
 .I m.
 If 

+.I l
+and

 .I m
 .I m

-is omitted,
-sdb chooses a format suitable for the variable's type
-as declared in the C program.
-Legal values for
-.I m
-are
+are omitted,
+sdb chooses a length and format suitable for the variable's type
+as declared in the program.
+The length specifiers are:

 .RS
 .TP
 .RS
 .TP

-.BI c
-character
+.BI b
+one byte

 .br
 .ns
 .TP
 .BI h
 .br
 .ns
 .TP
 .BI h

-16 bit integer in decimal
+two bytes (half word)

 .br
 .ns
 .TP
 .br
 .ns
 .TP

-.BI d
-int size integer in decimal
+.BI l
+four bytes (long word)

 .br
 .ns
 .TP
 .br
 .ns
 .TP

-.BI l
-32 bit integer in decimal
+number
+string length for formats
+.B s
+and
+.B a
+.RE
+.TP 5
+\ 
+Legal values for
+.I m
+are:
+.RS
+.TP
+.BI c
+character
+.br
+.ns
+.TP
+.BI d
+decimal

 .br
 .ns
 .TP
 .BI u
 .br
 .ns
 .TP
 .BI u

-int size bit integer in decimal, unsigned
+decimal, unsigned

 .br
 .ns
 .TP
 .BI o
 .br
 .ns
 .TP
 .BI o

-int size bit integer in octal
+octal

 .br
 .ns
 .TP
 .BI x
 .br
 .ns
 .TP
 .BI x

-int size bit integer in hexadecimal
+hexadecimal

 .br
 .ns
 .TP
 .br
 .ns
 .TP


@@ -132,18 +158,62 @@ reached.
 .BI a
 Print characters starting at the variable's address until a null
 is reached.
 .BI a
 Print characters starting at the variable's address until a null
 is reached.

-.RE
-.sp 1
-.ti +5

 .br
 .br

+.ns
+.TP
+.BI p
+pointer to procedure
+.RE
+.TP 5
+\ 
+The length specifiers are only effective with the formats
+\fBd\fP, \fBu\fP, \fBo\fP and \fBx\fP.
+If
+one of these formats
+is specified and
+.I l
+is omitted,
+the length
+defaults to the word length of the host machine;
+4 for the DEC VAX/11-780.

 The last variable may be redisplayed with the command `./'.
 The last variable may be redisplayed with the command `./'.

+.sp
+The sh(1) metacharacters 
+.B *
+and
+.B ?
+may be used within procedure and variable names,
+providing a limited form of pattern matching.
+If no procedure name is given, both variables local to the current
+procedure and global (common for F77) variables are matched,
+while if a procedure name is specified then
+only variables local to that procedure and matched.
+To match only global variables (or blank common for F77),
+the form `:pattern' is used.
+The name of a common block may be specified instead of a procedure name
+for F77 programs.
+.RE

 .TP 5
 .TP 5

-variable\fB=\fP
-Print the address of variable.
+variable\fB=\fP\fIlm\fP
+.br
+.ns
+.TP 5
+linenumber\fB=\fP\fIlm\fP
+.br
+.ns
+.TP 5
+number\fB=\fP\fIlm\fP
+Print the address of the variable or line number or the value of the number
+in the specified format.
+If no format is given, then `lx' is used.
+The last variant of this command provides a convenient way to convert
+between decimal, octal and hexadecimal.

 .TP 5
 variable\fB!\fPvalue
 Set the variable to the given value.
 The value may be a number, character constant or a variable.
 .TP 5
 variable\fB!\fPvalue
 Set the variable to the given value.
 The value may be a number, character constant or a variable.

+If the variable is of type float or double,
+the value may also be a floating constant.

 .sp 1
 .PP
 The commands for examining source files are
 .sp 1
 .PP
 The commands for examining source files are


@@ -168,12 +238,12 @@ are reported.
 .TP 5
 \fB/\fPregular expression\fB/\fP
 Search forward from the current line for a line containing
 .TP 5
 \fB/\fPregular expression\fB/\fP
 Search forward from the current line for a line containing

-a string matching the regular expression as in ed (1).
+a string matching the regular expression as in ed(1).

 The trailing `/' may be elided.
 .TP 5
 \fB?\fPregular expression\fB?\fP
 Search backward from the current line for a line containing
 The trailing `/' may be elided.
 .TP 5
 \fB?\fPregular expression\fB?\fP
 Search backward from the current line for a line containing

-a string matching the regular expression as in ed (1).
+a string matching the regular expression as in ed(1).

 The trailing `?' may be elided.
 .TP 5
 .B p
 The trailing `?' may be elided.
 .TP 5
 .B p


@@ -203,32 +273,50 @@ Print the new current line.
 \fIcount\fB \(mi\fR
 Retreat the current line by \fIcount\fP lines.
 Print the new current line.
 \fIcount\fB \(mi\fR
 Retreat the current line by \fIcount\fP lines.
 Print the new current line.

-.TP 5
-.B newline
-Advance the current line by 1 line.
-Print the new current line.

 .sp 1
 .PP
 .sp 1
 .PP

-The commands for controlling the execution of the source program are
+The commands for controlling the execution of the source program are:

 .TP 5
 \fIcount\fB r \fIargs\fR
 .TP 5
 \fIcount\fB r \fIargs\fR

+.br
+.ns
+.TP 5
+\fIcount\fB R

 Run the program with the given arguments.
 Run the program with the given arguments.

+The \fBr\fP command with no arguments reuses the previous arguments
+to the program while the \fBR\fP command
+runs the program with no arguments.

 An argument beginning with `<' or `>' causes redirection for the
 standard input or output respectively.
 If \fIcount\fP is given,
 it specifies the number of breakpoints to be ignored.
 .TP 5
 An argument beginning with `<' or `>' causes redirection for the
 standard input or output respectively.
 If \fIcount\fP is given,
 it specifies the number of breakpoints to be ignored.
 .TP 5

-\fIcount\fB c\fR
+\fIlinenumber\fB c\fI count\fR
+.br
+.ns
+.TP 5
+\fIlinenumber\fB C\fI count\fR

 Continue after a breakpoint or interrupt.
 If \fIcount\fP is given,
 it specifies the number of breakpoints to be ignored.
 Continue after a breakpoint or interrupt.
 If \fIcount\fP is given,
 it specifies the number of breakpoints to be ignored.

+\fBC\fP continues with the signal which caused the program to stop and
+\fBc\fP ignores it.
+.sp 0.5
+If a linenumber is specified
+then a temporary breakpoint is placed at the line
+and execution is continued.
+The breakpoint is deleted when the command finishes.

 .TP 5
 \fIcount\fB s\fR
 .TP 5
 \fIcount\fB s\fR

+Single step.

 Run the program through \fIcount\fP lines.
 Run the program through \fIcount\fP lines.

-\fICount\fP defaults to one if it is omitted.
+If no count is given then the program is run for one line.

 .TP 5
 .TP 5

-.B n
-Run the program until it reaches the next line.
+\fIcount\fB S\fR
+Single step, but step through subroutine calls.
+.TP 5
+.B k
+Kill the debugged program.

 .TP 5
 procedure\fB(\fParg1,arg2,...\fB)\fP
 .br
 .TP 5
 procedure\fB(\fParg1,arg2,...\fB)\fP
 .br


@@ -238,43 +326,82 @@ procedure\fB(\fParg1,arg2,...\fB)/\fP\fIm\fP
 Execute the named procedure with the given arguments.
 Arguments can be integer, character or string constants
 or names of variables accessible from the current procedure.
 Execute the named procedure with the given arguments.
 Arguments can be integer, character or string constants
 or names of variables accessible from the current procedure.

-The current implementation is limited to 14 arguments and a total
-length of 448 for string constants.

 The second form causes the value returned by the procedure to be
 printed according to format \fIm\fP.
 If no format is given, it defaults to `d'.
 .TP 5
 The second form causes the value returned by the procedure to be
 printed according to format \fIm\fP.
 If no format is given, it defaults to `d'.
 .TP 5

-\fIlinenumber\fB b\fR
+\fIlinenumber\fB b\fR \fIcommands\fR

 Set a breakpoint at the given line.
 If a procedure name without a line number is given (e.g. `proc:'),
 Set a breakpoint at the given line.
 If a procedure name without a line number is given (e.g. `proc:'),

-a breakpoint is placed at the first line in the procedure.
-If no \fIlinenumber\fP is given, a list of the currently active
-breakpoints is printed.
+a breakpoint is placed at the first line in the procedure
+even if it was not compiled with the debug flag.
+If no \fIlinenumber\fP is given,
+a breakpoint is placed at the current line.
+.sp 0.5
+If no
+.I commands
+are given then execution stops just before the breakpoint
+and control is returned to sdb.
+Otherwise
+the 
+.I commands 
+are executed when the breakpoint is
+encountered and execution continues.
+Multiple commands are specified by separating them with semicolons.

 .TP 5
 \fIlinenumber\fB d\fR
 Delete a breakpoint at the given line.
 If no \fIlinenumber\fP is given then the breakpoints are deleted interactively:
 Each breakpoint location is printed and a line is read from the standard input.
 If the line begins with a `y' or `d' then the breakpoint is deleted.
 .TP 5
 \fIlinenumber\fB d\fR
 Delete a breakpoint at the given line.
 If no \fIlinenumber\fP is given then the breakpoints are deleted interactively:
 Each breakpoint location is printed and a line is read from the standard input.
 If the line begins with a `y' or `d' then the breakpoint is deleted.

+.TP 5
+.B B
+Print a list of the currently active breakpoints.
+.TP 5
+.B D
+Delete all breakpoints.
+.TP 5
+l
+Print the last executed line.
+.TP 5
+\fIlinenumber\fB a\fR
+Announce.
+If \fIlinenumber\fR is of the form `proc:number', the command
+effectively does a `linenumber b l'.
+If \fIlinenumber\fR is of the form `proc:', the command
+effectively does a `proc: b T'.

 .sp 1
 .PP
 Miscellaneous commands.
 .TP 5
 .sp 1
 .PP
 Miscellaneous commands.
 .TP 5

+\fB! \fIcommand\fR
+The command is interpreted by sh(1).
+.TP 5
+.B newline
+If the previous command printed a source line then
+advance the current line by 1 line and
+print the new current line.
+If the previous command displayed a core location then
+display the next core location.
+.TP 5
+\fB"\fI string\fR
+Print the given string.
+.TP 5

 .B q
 Exit the debugger.
 .B q
 Exit the debugger.

-.TP 5
-\fB! \fIcommand\fR
-The command is interpreted by sh (1).

 .sp 1
 .PP
 The following commands also exist and are intended only for
 debugging the debugger.
 .TP 5
 .sp 1
 .PP
 The following commands also exist and are intended only for
 debugging the debugger.
 .TP 5

-.B a
-Toggle debug output.
+.B V
+Print the version number.

 .TP 5
 .TP 5

-.B x
+.B X

 Print a list of procedures and files being debugged.
 Print a list of procedures and files being debugged.

+.TP 5
+.B Y
+Toggle debug output.

 .SH FILES
 a.out
 .br
 .SH FILES
 a.out
 .br


@@ -282,8 +409,23 @@ core
 .SH SEE\ ALSO
 adb(1)
 .SH DIAGNOSTICS
 .SH SEE\ ALSO
 adb(1)
 .SH DIAGNOSTICS

-Comments about inaccessible files, syntax errors,
-abnormal termination of commands, etc.
+Error reports are either identical to those of adb(1) or are
+self-explanatory.

 .SH BUGS
 .SH BUGS

-Undoubtedly,
-some features are actually bugs and vice versa.
+If a procedure is called when the program is
+.I not
+stopped at a breakpoint
+(such as when a core image is being debugged),
+all variables are initialized before the procedure is started.
+This makes it impossible to use a procedure which formats
+data from a core image.
+.PP
+Arrays must be of one dimension and of zero origin to be correctly
+addressed by sdb.
+.PP
+The default type for printing F77 parameters is incorrect.
+Their address is printed instead of their value.
+.PP
+Tracebacks containing F77 subprograms with multiple entry points
+may print too many arguments in the wrong order, but their values
+are correct.