Keywords: doc-html

Next: Expressions Up: Statements and Expressions Previous: Statements and Expressions Contents Index

# Statements

Bro functions and event handlers are written in an imperative style, and the statements available for doing so are similar to those provided in C. As in C, statements are terminated with a semi-colon. There are no restrictions on how many lines a statement can span. Whitespace can appear between any of the syntatic components in a statement, and its presence always serves as a separator (that is, a single syntactic component cannot in general contain embedded whitespace, unless it is escaped in some form, such as appearing inside a string literal).

Bro provides the following types of statements:

  [expression] Syntax:

  > `expr ;`

  As in C, an expression by itself can also be used as a statement. For example, assignments, calling functions, and scheduling timers are all expressions; they also are often used as statements.

  [`print`] Syntax:

  > `print [ `file` ] expr-list ;`

  The expressions are converted to a list of strings, which are then printed as a comma-separated list. If the first expression is of type `file`, then the other expressions are printed to the corresponding file; otherwise they're written to stdout.

  For control over how the strings are formatted, see `fmt` function.

  [`log`] Syntax:

  > `log expr-list ;`

  The expressions are converted to a list of strings, which are then logged as a comma-separated list. ``Logging'' means recording the values to `bro_log_file`. In addition, if Bro is reading live network traffic (as opposed to from a trace file), then the messages are also reported via syslog(3) at level `LOG_NOTICE`. If the message does not already include a timestamp, one is added.

  See the `log` module for a discussion of controlling logging behavior from your policy script. In particular, an important feature of the `log` statement is that prior to logging the giving string(s), Bro first invokes `log_hook` to determine whether to suppress the logging.

  [`event`] Syntax:

  > `event expr ( expr-list ) ;`

  Evaluates expr to obtain an event handler and queues an event for it with the value corresponding to the optional comma-separated list of values given by expr-list.

  Note: `event` statements look syntactically just like function calls, other than the keyword ```event`''. However, function calls are expressions, while queueing an event is not, since it does not return a value.

  [`if`] Syntax:

  > `if ( expr ) stmt`
  > `if ( expr ) stmt else stmt`

  Evaluates expr, which must yield a `bool` value. If true, executes stmt. For the second form, if false, executes stmt.

  [`for`] Syntax:

  > `for ( var in expr ) stmt`

  Iterates over the indices of expr, which must evaluate to either a `set` or a `table`. For each iteration, var is set to one of the indices and stmt is executed. var needn't have been previously declared (in which case its type is implicitly inferred from that of the indices of expr), and must not be a global variable.

  If expr is a `set`, then the indices correspond to the members of the set. If expr is a `table`, then they correspond to the indices of the table.

  Deficiency: You can only use `for` statements to iterate over sets and tables with a single, non-compound index type. You can't iterate over multi-dimensional or compound indices.

  Deficiency: Bro lacks ways of controlling the order in which it iterates over the indices.

  [`next`] Syntax:

  > `next ;`

  Only valid within a `for` statement. When executed, causes the loop to proceed to the next iteration value (i.e., the next index value).

  [`break`] Syntax:

  > `break ;`

  Only valid within a `for` statement. When executed, causes the loop to immediately exit.

  [`return`] Syntax:

  > `return [ `expr` ] ;`

  Immediately exits the current function or event handler. For a function, returns the value expr (which is omitted if the function does not return a value, or for event handlers).

  [`add`] Syntax:

  > `add expr [ `expr` ] ;`

  Adds the element specified by expr to the `set` given by expr. For example,

          global active_hosts: set[addr, port];
          ...
          add active_hosts[1.44.33.7, 80/tcp];

  addes an element corresponding to the pair `1.44.33.7` and `80/tcp` to the set `active_hosts`.

  [`delete`] Syntax:

  > `delete expr [ `expr` ] ;`

  Deletes the corresponding value, where expr corresponds to a set or table, and expr an element/index of the set/table. If the element is not in the set/table, does nothing.

  [compound] Compound statements are formed from a list of (zero or more) statements enclosed in `{}`'s:

  > `{ statement }`

  [null] A lone:

  > `;`

  denotes an empty, do-nothing statement.

  [`local`, `const`] Syntax:

  > `local var [ `: type` ] [ `= initialization` ] [ `attributes` ] ;`
  > `const var [ `: type` ] [ `= initialization` ] [ `attributes` ] ;`

  Declares a local variable with the given type, initialization, and attributes, all of which are optional. The syntax of these fields is the same as for global variable declarations. The second form likewise declares a local variable, but one which is constant: trying to assign a new value to it results in an error. Deficiency: Currently, this `const` restriction isn't detected/enforce.

  Unlike with C, the scope of a local variable is from the point of declaration to the end of the encompassing function or event handler.

Next: Expressions Up: Statements and Expressions Previous: Statements and Expressions Contents Index