Attributes

The Bro scripting language supports the following attributes.

Name	Description
&redef	Redefine a global constant or extend a type.
&priority	Specify priority for event handler or hook.
&log	Mark a record field as to be written to a log.
&optional	Allow a record field value to be missing.
&default	Specify a default value.
&add_func	Specify a function to call for each “redef +=”.
&delete_func	Same as “&add_func”, except for “redef -=”.
&expire_func	Specify a function to call when container element expires.
&read_expire	Specify a read timeout interval.
&write_expire	Specify a write timeout interval.
&create_expire	Specify a creation timeout interval.
&synchronized	Synchronize a variable across nodes.
&persistent	Make a variable persistent (written to disk).
&rotate_interval	Rotate a file after specified interval.
&rotate_size	Rotate a file after specified file size.
&encrypt	Encrypt a file when writing to disk.
&raw_output	Open file in raw mode (chars. are not escaped).
&mergeable	Prefer set union for synchronized state.
&error_handler	Used internally for reporter framework events.
&type_column	Used by input framework for “port” type.
&deprecated	Marks an identifier as deprecated.

Here is a more detailed explanation of each attribute:

&redef

Allows use of a redef to redefine initial values of global variables (i.e., variables declared either global or const). Example:

const clever = T &redef;
global cache_size = 256 &redef;

Note that a variable declared “global” can also have its value changed with assignment statements (doesn’t matter if it has the “&redef” attribute or not).

&priority

Specifies the execution priority (as a signed integer) of a hook or event handler. Higher values are executed before lower ones. The default value is 0. Example:

event bro_init() &priority=10
{
    print "high priority";
}

&log

Writes a record field to the associated log stream.

&optional

Allows a record field value to be missing (i.e., neither initialized nor ever assigned a value).

In this example, the record could be instantiated with either “myrec($a=127.0.0.1)” or “myrec($a=127.0.0.1, $b=80/tcp)”:

type myrec: record { a: addr; b: port &optional; };

The ?$ operator can be used to check if a record field has a value or not (it returns a bool value of T if the field has a value, and F if not).

&default

Specifies a default value for a record field, container element, or a function/hook/event parameter.

In this example, the record could be instantiated with either “myrec($a=5, $c=3.14)” or “myrec($a=5, $b=53/udp, $c=3.14)”:

type myrec: record { a: count; b: port &default=80/tcp; c: double; };

In this example, the table will return the string "foo" for any attempted access to a non-existing index:

global mytable: table[count] of string &default="foo";

When used with function/hook/event parameters, all of the parameters with the “&default” attribute must come after all other parameters. For example, the following function could be called either as “myfunc(5)” or as “myfunc(5, 53/udp)”:

function myfunc(a: count, b: port &default=80/tcp)
{
    print a, b;
}

&add_func

Can be applied to an identifier with &redef to specify a function to be called any time a “redef <id> += …” declaration is parsed. The function takes two arguments of the same type as the identifier, the first being the old value of the variable and the second being the new value given after the “+=” operator in the “redef” declaration. The return value of the function will be the actual new value of the variable after the “redef” declaration is parsed.

&delete_func

Same as &add_func, except for redef declarations that use the “-=” operator.

&expire_func

Called right before a container element expires. The function’s first parameter is of the same type of the container and the second parameter the same type of the container’s index. The return value is an interval indicating the amount of additional time to wait before expiring the container element at the given index (which will trigger another execution of this function).

&read_expire

Specifies a read expiration timeout for container elements. That is, the element expires after the given amount of time since the last time it has been read. Note that a write also counts as a read.

&write_expire

Specifies a write expiration timeout for container elements. That is, the element expires after the given amount of time since the last time it has been written.

&create_expire

Specifies a creation expiration timeout for container elements. That is, the element expires after the given amount of time since it has been inserted into the container, regardless of any reads or writes.

&synchronized

Synchronizes variable accesses across nodes. The value of a &synchronized variable is automatically propagated to all peers when it changes.

&persistent

Makes a variable persistent, i.e., its value is written to disk (per default at shutdown time).

&rotate_interval

Rotates a file after a specified interval.

Note: This attribute is deprecated and will be removed in a future release.

&rotate_size

Rotates a file after it has reached a given size in bytes.

Note: This attribute is deprecated and will be removed in a future release.

&encrypt

Encrypts files right before writing them to disk.

Note: This attribute is deprecated and will be removed in a future release.

&raw_output

Opens a file in raw mode, i.e., non-ASCII characters are not escaped.

&mergeable

Prefers merging sets on assignment for synchronized state. This attribute is used in conjunction with &synchronized container types: when the same container is updated at two peers with different values, the propagation of the state causes a race condition, where the last update succeeds. This can cause inconsistencies and can be avoided by unifying the two sets, rather than merely overwriting the old value.

&error_handler

Internally set on the events that are associated with the reporter framework: reporter_info, reporter_warning, and reporter_error. It prevents any handlers of those events from being able to generate reporter messages that go through any of those events (i.e., it prevents an infinite event recursion). Instead, such nested reporter messages are output to stderr.

&type_column

Used by the input framework. It can be used on columns of type port (such a column only contains the port number) and specifies the name of an additional column in the input file which specifies the protocol of the port (tcp/udp/icmp).

In the following example, the input file would contain four columns named “ip”, “srcp”, “proto”, and “msg”:

type Idx: record {
    ip: addr;
};


type Val: record {
    srcp: port &type_column = "proto";
    msg: string;
};

&deprecated

The associated identifier is marked as deprecated and will be removed in a future version of Bro. Look in the NEWS file for more instructions to migrate code that uses deprecated functionality.