next up previous contents index
Next: Missing Documentation Up: Interactive Debugger Previous: Notes and Limitations   Contents   Index


Reference

Summary of Commands
Note: all commands may be abbreviated with a unique prefix. Shortcuts below are special exceptions to this rule.





Command Shortcut Description
help   Get help with debugger commands
quit   Exit Bro
next n Step to the following statement, skipping function calls
step s Step to following statements, stepping in to function calls
continue c Resume execution of the policy script
finish   Run until the currently-executing function completes
break b Set a breakpoint
condition   Set a condition on an existing breakpoint
delete d Delete the specified breakpoints; delete all if no arguments
disable   Turn off the specified breakpoint; do not delete permanently
enable   Undo a prior `disable' command
info   Get information about the debugging environment
print p Evaluate an expression and print the result
set   Alias for `print'
backtrace bt Print a stack trace
frame   Select frame number N
up   Select the stack frame one level up from the current one
down   Select the stack frame one level down from the current one
list l Print source lines surrounding specified context
trace   Turn on or off execution tracing





Getting Help

help
Help for each command may be invoked with the help command. Calling the command with no arguments displays a one-line summary of each command.

Command-Line Options

-d switch
The -d switch enables the Bro script debugger.
-t switch
The -t enables execution tracing. There is an argument to the switch, which indicates a file that will contain the result of the trace. Trace output consists of the source code lines executed, indented for each nested function invocation.

Example. The following command invokes Bro, using tcpdump_file for the input packets and outputting the result of the trace to execution_trace.

  ./bro -t execution_trace -r tcpdump_file policy_script.bro

Example. If the argument to -t is a single dash character (``-''), then the trace output is sent to stderr.

  ./bro -t - -r tcpdump_file policy_script.bro

Example. Lastly, execution tracing may be combined with the debugger. Here we send output to stderr, so it will be intermingled with the debugger's output. Tracing may be turned off and on in the debugger using the trace command.

  ./bro -d -t - -r tcpdump_file policy_script.bro

Running the Script

quit
Exit Bro, aborting execution of the currently executing script.
restart (r)
(Currently Unimplemented) Restart the execution of the script, rewinding to the beginning of the input file(s), if appropriate. Breakpoints and other debugger state are preserved.
continue (c)
Resume execution of the script file. The script will continue running until interrupted by a breakpoint or a signal.
next (n)
Execute one statement, without entering any subroutines called in that statement.
step (s)
Execute one statement, but stop on entry to any called subroutine.
finish
Run until the currently executing function returns.

Breakpoints

break (b)
Set a breakpoint. A breakpoint suspend execution when execution reaches a particular location and returns control to the debugger. Breakpoint locations may be specified in a number of ways:

break With no argument, the current line is used.
break [FILE:]LINE The specified line in the specified file; if no policy file is specified, the current file is implied.
break FUNCTION The first line of the specified function or event handler. If more than one event handler matches the name, a choice will be presented.
break WILDCARD Similar to FUNCTION, but a POSIX-compliant regular expression (see the regex(3) man page )is supplied, which is matched against all functions and event handlers. One exception to the the POSIX syntax is that, as in the shell, the * character may be used to match zero or more of any character without a preceding period character (.).

condition $N$ expression
The numeric argument $N$ indicates which breakpoint to add a condition to, and the expression is the conditional expression. A breakpoint with a condition will only stop execution when the supplied condition is true. The condition will be evaluated in the context of the breakpoint's location when it is reached.
enable
With no arguments, enable all breakpoints previously disabled with the disable command. If numeric arguments separated by spaces are provided, the breakpoints with those numbers will be enabled.
disable
With no arguments, disable all breakpoints. Disabled breakpoints will not stop execution, but will be retained to be enabled later. If numeric arguments separated by spaces are provided, the breakpoints with those numbers will be disabled.
delete (d)
With no arguments, permanently delete all breakpoints. If numeric arguments separated by spaces are provided, the breakpoints with those numbers will be deleted.

Debugger State

info
Give information about the current script and debugging environment. A subcommand should follow the info command to indicate which information is desired. At present, the following subcommands are available:

info break List all breakpoints and their status

Inspecting Program State

print (p) / set
The print command and its alias, set, are used to evaluate any expression in the policy script language. The result of the evaluation is printed out. Results of the evaluation affect the current execution environment; expressions may include things like assignment. The expression is evaluated in the context of the currently selected stack frame. The frame, up, and down commands (below) are used to change the currently selected frame, which defaults to the innermost one.
backtrace (bt)
Print a description of all the stack frames (function invocations) of the currently executing script.
With no arguments, prints out the currently selected stack frame.
With a numeric argument $\pm N$, prints the innermost $N$ frames if the argument is positive, or the outermost $N$ frames if the argument is negative.
frame
With no arguments, prints the currently selected frame.
With a numeric argument $N$, selects frame $N$. Frame numbers are numbered inside-out from 0; the
up
Select the stack frame that called the currently selected one. If a numeric argument $N$ is supplied, go up that many frames.
down
Select the stack frame called by the currently selected one. If a numeric argument $N$ is supplied, go down that many frames.
list (l)
With no argument, print the ten lines of script source code following the previous listing. If there was no previous listing, print ten lines surrounding the next statement to be executed. If an argument is supplied, ten lines are printed around the location it describes. The argument may take one of the following forms:

[FILE:]LINE The specified line in the specified file; if no policy file is specified, the current file is implied.
FUNCTION The first line of the specified function or event handler. If more than one event handler matches the name, a choice will be presented.
$\pm N$ With a numeric argument preceded by a plus or minus sign, the line at the supplied offset from the previously selected line.


next up previous contents index
Next: Missing Documentation Up: Interactive Debugger Previous: Notes and Limitations   Contents   Index
Vern Paxson 2004-03-21