next up previous contents index
Next: Predefined Variables and Functions Up: Global and Local Variables Previous: Global and Local Variables   Contents   Index

Subsections

Overview

Bro variables can be complicated to understand because they have a number of possibilities and features. They can be global or local in scope; modifiable or constant (unchangeable); explicitly or implicitly typed; optionally initialized; defined to have additional attributes; and, for global variables, redefined to have a different initialization or different attributes from their first declaration.

Rather than giving the full syntax for variable declarations, which is messy, in the following sections we discuss each of these facets of variables in turn, illustrating them with the minimal necessary syntax. However, keep in mind that the features can be combined as needed in a variable declaration.


Scope

global local Global variables are available throughout your policy script (once declared), while the scope of local variables is confined to the function or event handler in which they're declared. You indicate the variable's type using a corresponding keyword:
global name : type ;
or
local name : type ;
which declares name to have the given type and the corresponding scope.

You can intermix function/event handler definitions with declarations of global variables, and, indeed, they're in fact the same thing (that is, a function or event handler definition is equivalent to defining a global variable of type function or event and associating its initial value with that of the function or event handler). So the following is fine:

    global a: count;

    function b(p: port): string
        {
        if ( p < 1024/tcp )
            return "privileged";
        else
            return "ephemeral";
        }

    global c: addr;

However, you cannot mix declarations of global variables with global statements; the following is not allowed:

    print "hello, world";
    global a: count;

Local variables, on the other hand, can only be declared within a function or event handler. (Unlike for global statements, these declarations can come after statements.) Their scope persists to the end of the function. For example:

    function b(p: port): string
        {
        if ( p < 1024/tcp )
            local port_type = "privileged";
        else
            port_type = "ephemeral";

        return port_type;
        }


Modifiability

const For both global and local variables, you can declare that the variable cannot be modified by declaring it using the const keyword rather than global or local:
    const response_script = "./scripts/nuke-em";
Note that const variables must be initialized (otherwise, of course, there's no way for them to ever hold a useful value).

The utility of marking a variable as unmodifiable is for clarity in expressing your script--making it explicit that a particular value will never change--and also allows Bro to possibly optimize accesses to the variable (though it does little of this currently).

Note that const variables can be redefined via redef.


Typing

When you define a variable, you can explicitly type it by specifying its type after a colon. For example,
    global a: count;
directly indicates that a's type is count.

However, Bro can also implicitly type the variable by looking at the type of the expression you use to initialize the variable:

    global a = 5;
also declares a's type to be count, since that's the type of the initialization expression (the constant 5). There is no difference between this declaration and:
    global a: count = 5;
except that it is more concise both to write and to read. In particular, Bro remains strongly typed, even though it also supports implicit typing; the key is that once the type is implicitly inferred, it is thereafter strongly enforced.

Bro's type inference is fairly powerful: it can generally figure out the type whatever initialization expression you use. For example, it correctly infers that:

    global c = { [21/tcp, "ftp"], [[80/tcp, 8000/tcp, 8080/tcp], "http"], };
specifies that c's type is set[port, string]. But for still more complicated expressions, it is not always able to infer the correct type. When this occurs, you need to explicitly specify the type.


Initialization

When defining a variable, you can optionally specify an initial value for the variable:
    global a = 5;
indicates that the initial value of a is the value 5 (and also implicitly types a as type count, per § ).

The syntax of an initialization is ``= expression'', where the given expression must be assignment-compatible with the variable's type (if explicitly given). Tables and sets also have special initializer forms, which are discussed in §  and § .


Attributes

When defining a variable, you can optionally specify a set of attributes associated with the variable, which specify additional properties associated with it. Attributes have two forms:
& attr
for attributes that are specified simply using their name, and
& attr = expr
for attributes that have a value associated with them.

The attributes &redef &add_func and &delete_func, pertain to redefining variables; they are discussed in § .

The attributes &default, &create_expire, &read_expire, &write_expire, and &expire_func are for use with table's and set's. See §  for discussion.

The attribute &optional specifies that a record field is optional. See §  for discussion.

Finall, to specify multiple attributes, you do not separate them with commas (doing so would actually make Bro's grammar ambiguous), but just list them one after another. For example:

    global a: table[port] of string &redef &default="missing";


Refinement

To do.

&redef

&add_func

&delete_func


next up previous contents index
Next: Predefined Variables and Functions Up: Global and Local Variables Previous: Global and Local Variables   Contents   Index
Vern Paxson 2002-11-17