1$Id: sdb.1.pea,v 1.18 2020-12-12 23:40:49 phil Exp $
2=pea
3=sect NAME
4sdb \- SNOBOL4 debugger
5=sect SYNOPSIS
6B<sdb> [ I<options> .\|.\|. ] I<program.sno>
7
8=sect DESCRIPTION
9B<sdb> is a debugger for B<snobol4>(1) programs, in the mold (clawning
10fone) of B<gdb>(1), The GNU debugger.  B<sdb>(1) uses B<readline>(3)
11for command line editing/history when available.
12
13=subsect Commands
14=item B<break> I<LABEL_OR_STATEMENT_NUMBER>
15Set a breakpoint.
16=item B<bt>
17=break
18Display call stack I<back trace>.
19=item B<commands> I<BREAKPOINT_NUMBER>
20Add sdb commands to execute (ie; print &amp; continue) to a breakpoint.
21=item B<condition> I<BREAKPOINT_NUMBER> [ I<EXPR> ]
22If I<EXPR> is supplied, it is used as a predicate to make the
23breakpoint conditional, if no I<EXPR> is supplied, any previous condition
24is removed.
25=item B<continue> [ I<COUNT> ]
26Continue from breakpoint.  The optional count specifies how many times
27to continue past this breakpoint (sets B<ignore> count).
28=item B<delete> [ I<BREAKPOINT_NUMBER> ]
29Delete a single breakpoint, or all breakpoints.
30=item B<disable> [ I<BREAKPOINT_NUMBER> ]
31Temporarily disable a breakpoint, or all breakpoints.
32=item B<enable> [ I<BREAKPOINT_NUMBER> ]
33Re-enable a breakpoint, or all breakpoints.
34=item B<finish>
35Resume debugging after current function returns.
36Will display function return type and value, if any.
37=item B<help>
38Display help.
39=item B<ignore> I<BREAKPOINT_NUMBER> [ I<COUNT> ]
40Set (or clear) breakpoint ignore count.
41=item B<info>
42Display list of breakpoints and their status.
43=item B<list> [ I<LABEL_OR_STATEMENT_NUMBER> ]
44Display source code.
45=item B<next> [ I<COUNT> ]
46Single step execution, skipping over function calls.
47=item B<print> I<EXPRESSION>
48Evaluate expression and print result.  Can be used to call functions,
49or set variables.
50=item B<quit>
51Exit debugger.
52=item B<run>
53=break
54Restart program (works by saving breakpoints and restarting snobol4).
55New in version 2.1, some restrictions may apply.
56=item B<save> I<FILENAME>
57Save breakpoints to file.
58=item B<source> I<FILENAME>
59Read sdb commands from file.
60=item B<step> [ I<COUNT> ]
61Single step.
62=item B<watch> I<VARIABLE>
63Set watchpoint on a variable (break when value changes).
64=item B<what> I<EXPRESSION>
65Display the datatype of expression.
66=item B<where>
67An alias for B<bt>.
68
69A blank line repeats the previous command.
70
71Non-ambiguous abbreviations of commands can be used (ie; B<s>, B<n>).
72
73The GNU Readline library (when available) will be used for B<sdb>(1)
74input for command editing and history.
75
76The keyboard interrupt character (eg; Control-C) will stop a running
77program and return control to the B<sdb>(1) command prompt.
78
79If your program calls the B<SDB()> function, it will act as a
80breakpoint.  You can check whether B<sdb>(1) is loaded with the
81B<FUNCTION()> predicate, ie;
82
83=code
84        FUNCTION('SDB') SDB()
85=ecode
86
87=sect FILES
88=item B<~/.sdbinit>
89initial command file, read on startup.
90=item B<.sdb_history>
91saved command history
92=item B</tmp/sdb_listing.>I<pid>
93temporary listing file for sdb.sno to read
94=item B</tmp/sdb_bkpts.>I<pid>
95temporary breakpoint save file for "run" command
96
97=sect SEE ALSO
98B<snobol4>(1), B<gdb>(1), B<readline>(3), B<snobol4readline>(3)
99
100=sect AUTHOR
101Philip L. Budne
102
103Inspired by Fred Weigel's DDT.SNO and B<SITBOL>'s SNODDT.
104
105=sect LIMITATIONS
106B<sdb>(1) uses a wide variety of system facilities and will interact
107poorly with any programs that use any number of features, including:
108
109=bull Altering listing settings with directive/control lines.
110=bull Altering B<&STLIMIT>, B<&ERRLIMIT>, or B<&TRACE>.
111=bull Calling B<SETEXIT()>
112
113=sect BUGS
114If you try to put a breakpoint on a label or line with no code or goto
115fields, the breakpoint will never be triggered.
116
117You cannot put a breakpoint on the B<END> label (however control
118always returns to sdb when the B<END> label is reached).
119
120Interrupt character trapping is in it's infancy, and only occurs at
121the start of a each statement executed.
122
123The interrupt character is silently ignored when at the B<sdb> command
124prompt.
125
126Leaves an unprotected listing file of the sources in the /tmp directory
127(create a protected directory?).
128
129``quit'' and ``run'' commands say program is running even if first
130line of the program has not yet been executed!
131
132Some fatal errors cannot be trapped, and sdb will be terminated.
133