% $Header: /home/jaguar/u0/vern/bro/bro-doc/RCS/values.tex,v 1.16 2002/11/16 01:26:03 vern Exp vern $

\labsectchapter{{Values, Types, and Constants}}{\label{values-types-constants}}
%HEVEA\cutdef[1]{section}

\section{Overview}

\index{values!overview}
We begin with an overview of the types of values supported by
Bro,
giving a brief description of each type and
introducing the notions of type conversion and type inference.
We discuss each type in detail in \S~\ref{first-type}--\S~\ref{last-type} below.

\subsection{Bro Types}

There are \updateme{18} types of values in the Bro type
system:\index{types!overview}

\begin{itemize}
\index{types!{\tt bool}}
\indtype{bool}
\item {\tt bool} for Booleans;

\index{types!{\em numeric}}
\index{types!{\tt count}}
\indtype{count}
\index{types!{\tt int}}
\indtype{int}
\index{types!{\tt double}}
\indtype{double}
\index{numeric types!{\tt count}}
\index{numeric types!{\tt int}}
\index{numeric types!{\tt double}}
\item {\tt count}, {\tt int}, and {\tt double} types, collectively 
called {\em numeric\/}, for arithmetic and logical operations, and comparisons;

\index{types!{\em enumeration}}
\index{types!{\tt enum}}
\indtype{enum}
\item {\tt enum} for enumerated types similar to those in~C;

\index{types!{\tt string}}
\indtype{string}
\item {\tt string}, character strings that can be used
for comparisons and to index tables and sets;

\index{types!{\tt pattern}}
\indtype{pattern}
\item {\tt pattern}, regular expressions that can be used for pattern
matching;

\index{types!{\em temporal}}
\index{types!{\tt time}}
\indtype{time}
\index{types!{\tt interval}}
\indtype{interval}
\item {\tt time} and {\tt interval}, for absolute and relative times,
collectively termed \emph{temporal};
%### (more discussion here about the two types, plus an example)

\index{types!{\tt port}}
\indtype{port}
\item {\tt port}, a TCP or UDP port number;

\index{types!{\tt addr}}
\indtype{addr}
\item {\tt addr}, an IP address;

\index{types!{\tt net}}
\indtype{net}
\item {\tt net}, a network prefix;

\index{types!{\tt record}}
\indtype{record}
\item {\tt record}, a collection of values (of possibly different types),
each of which has a name;

\index{types!{\tt table}}
\indtype{table}
\item {\tt table}, an associative array, indexed by tuples of
scalars and yielding values of a particular type;

\index{types!{\tt set}}
\indtype{set}
\item {\tt set}, a collection of tuples-of-scalars, for which a
particular tuple's membership can be tested;

\index{types!{\tt file}}
\indtype{file}
\item {\tt file}, a disk file to \updateme{write or append} to;

\index{types!{\tt function}}
\indtype{function}
\item {\tt function}, a function that when called with a list of
values (arguments) returns a value;

\index{types!{\tt event}}
\indtype{event}
\item {\tt event}, an event handler that is invoked with a list of
values (arguments) any time an event occurs.

\end{itemize}

Every value in a Bro script has one of these types.
For most types there are ways of specifying {\em constants} representing
values of the type.  For example, {\tt 2.71828} is a constant
of type {\tt double}, and {\tt 80/tcp} is a constant of type
{\tt port}.  The discussion of types in
\S~\ref{first-type}--\S~\ref{last-type} below includes a description
of how to specify constants for the types.

\index{typing!static}
\index{static typing}
Finally, even though Bro variables have {\em static} types,
meaning that their type is fixed,
often their type is {\em inferred} from the value to which
they are initially assigned when the variable is declared.
For example,
\begin{verbatim}
    local a = "hi there";
\end{verbatim}
fixes {\tt a}'s type as {\tt string}, and
\begin{verbatim}
    local b = 6;
\end{verbatim}
sets {\tt b}'s type to {\tt count}.  See \xref{type-inference}
for further discussion.

\labsectsubsection{{Type Conversions}}{\label{type-conversion}}

\index{types!conversion|(}
Some types will be automatically converted to other types as
%### spell out which types
needed.\index{types!conversion!automatic}
For example, a {\tt count} value can always be used where a {\tt double}
value is expected.  The following:
\begin{verbatim}
    local a = 5;
    local b = a * .2;
\end{verbatim}
creates a local variable {\tt a} of type {\tt count} and
assigns the {\tt double} value {\tt 1.0} to {\tt b}, which will
also be of type {\tt double}.
Automatic conversions are limited to converting between {\em numeric} types.
The rules for how types are converted are given below.
\index{types!conversion|)}

\labsectsection{{Booleans}}{\label{first-type}}

\index{booleans|(}
The {\tt bool} type reflects a value with one of two possible
meanings: {\em true} or {\em false}.

\labsectsubsection{{Boolean Constants}}{\label{boolean-constants}}

\index{constants!boolean}
\index{{\tt T}}
\index{{\tt F}}
There are two {\tt bool} constants:
{\tt T} and {\tt F}.  They
represent the values of ``true" and ``false", respectively.

\labsectsubsection{{Logical Operators}}{\label{logical-operators}}
\index{types!{\tt bool}}

\index{operators!logical|(}
Bro supports three logical operators:
{\tt \&\&},
	  \index{& short-circuit@\verb+&&+{\tt \ } short-circuit ``and''}
	  \index{short-circuit1@short-circuit \verb+&&+ ``and'' operator}
	  \index{and operator@\verb+&&+ ``and'' operator}
	  \index{operator!and@\verb+&&+ ``and''}
{\tt ||},
	 \index{& or short-circuit@\verb+"|"|+{\tt \ } short-circuit ``or''}
	 \index{short-circuit2@short-circuit \verb+"|"|+ ``or'' operator}
	 \index{or operator@\verb+"|"|+ ``or'' operator}
	 \index{operator!or@\verb+"|"|+ ``or''}
and {\tt !}
	 \index{& z not@{\tt "!\ \ } ``not'' operator}
	 \index{not operator@{\tt "!} ``not'' operator}
	 \index{operator!not@{\tt "!} ``not''}
are Boolean ``and,'' ``or,'' and ``not,'' respectively.
{\tt \&\&} and {\tt ||} are ``short circuit'' operators, as in~C:
they evaluate their right-hand operand
only if needed.

The \verb+&&+ operator returns {\tt F} if its
first operand evaluates to {\em false}, otherwise it evaluates its second
operand and returns {\tt T} if it evaluates to {\em true}.
The {\tt ||} operator evaluates its first operand and returns {\tt T} if
the operand evaluates to {\em true}.  Otherwise it evaluates its second
operand, and returns {\tt T} if it is {\em true}, {\tt F} if {\em false}.

\label{logical-negation}
\index{logical negation}
\index{negation!logical}
The unary {\tt !}
operator returns the boolean negation of its argument.
So, {\tt !\ T} yields {\tt F}, and {\tt !\ F} yields {\tt T}.

\index{operators!logical!associativity}
\index{operators!logical!precedence}
The logical operators are left-associative.
The {\tt !}
operator has very high precedence, the same as unary {\tt +} and {\tt -};
see \S~\ref{arith-operators}~and~\S~\ref{precedence}.
The {\tt ||} operator has
precedence just below {\tt \&\&}, which in turn is just below that of
the comparison operators (see \xref{rel-operators}).
\index{operators!logical|)}
\index{booleans|)}

\section{Numeric Types}
\index{types!{\tt count}}
\index{types!{\tt int}}
\index{types!{\tt double}}

\index{types!{\em numeric}|(}
{\tt int}, {\tt count}, and {\tt double} types
should be familiar to most programmers as integer, unsigned integer, and
double-precision floating-point types.

These types are referred to collectively as {\em numeric}.  {\em Numeric}
types can be used in arithmetic operations (see \S~\ref{arith-operators}
below) as well as in comparisons (\xref{rel-operators}).

\labsectsubsection{{Numeric Constants}}{\label{numeric-constants}}

\index{constants!count}
{\tt count} constants are just strings of digits: {\tt 1234} and {\tt 0}
are examples.

\index{constants!integer}
{\tt integer} constants are strings of digits preceded
by a {\tt +} or {\tt -} sign: {\tt -42} and {\tt +5} for example.
Because digit strings without a sign are of type {\tt count}, occasionally
you need to take care when defining a variable if it really needs to
be of type {\tt int} rather than {\tt count}.  Because of type inferencing
\pxref{type-inference}, a definition like:
\begin{verbatim}
    local size_difference = 0;
\end{verbatim}
will result in {\tt size_difference} having type {\tt count} when
{\tt int} is what's instead needed (because, say, the size difference can be
negative).  This can be resolved either by using an {\tt int} constant
in the  initialization:
\begin{verbatim}
    local size_difference = +0;
\end{verbatim}
or explicitly indicating the type:
\begin{verbatim}
    local size_difference: int = 0;
\end{verbatim}

\index{constants!floating-point}
You write floating-point constants in the usual ways, a string of digits
with perhaps a decimal point and perhaps a scale-factor written in scientific
notation.  Optional {\tt +} or {\tt -} signs may be given before the digits
or before the scientific notation exponent.
Examples are {\tt -1234.}, {\tt -1234e0}, {\tt 3.14159}, and {\tt .003e-23}.
All floating-point constants are of type {\tt double}.

\labsectsubsection{{Mixing Numeric Types}}{\label{mixing-numerics}}

\index{types!numeric!intermixing}
\index{types!numeric!{\tt bool} not numeric}
You can freely intermix {\em numeric} types in expressions.  When intermixed,
values are promoted to the ``highest" type in the expression.
In general, this promotion follows a simple hierarchy: {\tt double} is
highest, {\tt int} comes next, and {\tt count} is lowest.  (Note that
{\tt bool} is not a numeric type.)

\labsectsubsection{{Arithmetic Operators}}{\label{arith-operators}}

\index{operators!arithmetic|(}
\index{addition!numeric}
\index{subtraction!numeric}
\index{multiplication!numeric}
\index{division!numeric}
\index{operators!arithmetic!operand conversion}
For doing arithmetic, Bro supports
{\tt +}\indoponekey{+}{addition operator}{+1addition},
{\tt -}\indoponekey{-}{subtraction operator}{+2subtraction},
{\tt *}\indoponekey{*}{multiplication operator}{+3multiplication},
{\tt /}\indoponekey{/}{division operator}{+4division},
and
{\tt \%}\index{%@\percent modulus operator}.
In general, binary operators evaluate their operands after converting them
to the higher type of the two and return a result of that type.
However, subtraction of two {\tt count} values yields an {\tt int} value.
Division is integral if its operands are {\tt count} and/or {\tt int}.

{\tt +}\indoponekey{+}{unary operator}{+1unary}
and {\tt -}\indoponekey{-}{unary operator}{+2unary}
can also be used as unary operators.  If applied to a {\tt count} type,
they yield an {\tt int} type.

{\tt \%} computes a {\em modulus}, defined in the same way as in
the~C language.  It can only be applied to {\tt count} or {\tt int}
types, and yields {\tt count} if both operands are {\tt count} types,
otherwise {\tt int}.

\index{operators!arithmetic!precedence}
Binary {\tt +} and {\tt -}
have the lowest precedence, {\tt *}, {\tt /}, and {\tt \%} have equal
and next highest precedence.  The unary
{\tt +} and {\tt -} operators have the same precedence as the {\tt !}
operator \pxref{logical-negation}.
See \xref{precedence}, for a table of the precedence of all Bro
operators.

\index{operators!arithmetic!associativity}
All arithmetic operators associate from left-to-right.
\index{operators!arithmetic|)}

\labsectsubsection{{Comparison Operators}}{\label{rel-operators}}

\index{operators!comparison|(}
\index{relationals!numeric}
\index{operators!comparison!operand conversion}
Bro provides the usual comparison operators:
\verb+==+\index{== equality operator@\verb+==+{\tt \ } equality operator},
\verb+!=+\index{== inequality operator@\verb+"!=+{\tt \ } inequality operator},
\verb+<+\index{== less-than operator@\verb+<+{\tt \ \ } less-than operator},
\verb+<=+\index{== less-than-or-equal operator@\verb+<=+{\tt \ } less-or-equal operator},
\verb+>+\index{== z operator@\verb+>+{\tt \ \ } greater-than operator},
and
\verb+>=+\index{== zz operator@\verb+>=+{\tt \ } greater-or-equal operator}.
They each take two operands, which
they convert to the higher of the two types (see \xref{mixing-numerics}).
They return a {\tt bool} corresponding to the comparison of the operands.
For example,
\begin{verbatim}
    3 < 3.000001
\end{verbatim}
yields true.

\index{operators!comparison!associativity}
\index{operators!comparison!precedence}
The comparison operators are all non-associative and have equal precedence,
just below that of the \link{{\tt in} operator}{in-operator} and
just above that of the \link{logical {\tt \&\&} operator}{logical-operators}.
See \xref{precedence},
for a general discussion of precedence.
\index{operators!comparison|)}
\index{types!{\em numeric}|)}

\section{Enumerations}
\index{enumerations|(}
\index{types!{\tt enum}}
\indtype{enum}
Enumerations allow you to specify a set of related values that have
no further structure, similar to {\tt enum} types in C.  For example:
\begin{verbatim}
    type color: enum { Red, White, Blue, };
\end{verbatim}
defines the values {\tt Red}, {\tt White}, and {\tt Blue}.  A variable
of type {\tt color} holds one of these values.  Note that {\tt Red} et al
\index{global scope!of enumerations}
have \emph{global scope}.  You \emph{cannot} define a variable or type
with those names.  (Also note that, as usual, the comma after {\tt Blue}
is optional.)

The only operations allowed on enumerations are comparisons for
equality.  Unlike C enuemrations, they do not have values or an
ordering associated with them.

You can extend the set of values in an enumeration using
{\tt redef enum \emph{identifier} += \{ \emph{name-list} \}}:
\begin{verbatim}
    redef enum color += { Black, Yellow };
\end{verbatim}
\index{enumerations|)}

\section{Strings}
\index{strings|(}
\index{types!{\tt string}}
The {\tt string} type holds character-string values, used to represent
and manipulate text.

\labsectsubsection{{String Constants}}{\label{string-constants}}

\index{constants!string|(}
\index{escape sequences}
\index{possible future changes!breaking string constants across multiple lines}
You create string constants by enclosing text within double ({\tt "}) quotes.
A backslash character (\verb+\+) 
introduces an {\em escape sequence\/}.  The following ANSI C escape
sequences are recognized:
\verb+\a+\index{\a alert escape@\verb+\a+{\tt \ } alert escape}
	 \index{\a bell escape@\verb+\a+{\tt \ } bell escape}
yields an alert (bell) character,
\verb+\b+\index{\b backspace escape@\verb+\b+{\tt \ } backspace escape}
yields a backspace character,
\verb+\f+\index{\f formfeed escape@\verb+\f+{\tt \ } formfeed escape}
yields a formfeed character,
\verb+\n+\index{\n newline escape@\verb+\n+{\tt \ } newline escape}
yields a newline character,
\verb+\r+\index{\r carriage return escape@\verb+\r+{\tt \ } carriage return escape}
yields a carriage return character,
\verb+\t+\index{\t tab escape@\verb+\t+{\tt \ } tab escape}
a tab character,
\verb+\+\emph{octal-digits}\index{octal escape@\verb+\+\emph{octal-digits} octal escape}
the 8-bit ASCII character with code \emph{octal-digits},
and
\verb+\x+\emph{hex-digits}\index{hexadecimal escape@\verb+\x+\emph{hex-digits} hexadecimal escape}
the 8-bit ASCII character with code \emph{hex-digits}.
Bro string constants currently \emph{cannot} be continued across
multiple lines by escaping newlines in the input.  This may change
in the future.
Any other character following a \verb+\+ is passed along literally.

\index{NULs!allowed in strings}
\label{NULs-allowed-in-strings}
\index{evasion!inserting NULs}
\unlikeC{strings are represented internally as a count and a
vector of bytes, rather than a NUL-terminated series of bytes.}  This
difference is important because NULs can easily be introduced into strings
derived from network traffic, either by the nature of the application,
inadvertently, or maliciously by an attacker attempting to subvert the
monitor.  An example of the latter is sending the following to an FTP server:
\begin{verbatim}
    USER nice\0USER root
\end{verbatim}
where ``\verb+\0+'' represents a NUL.  Depending on how it is written,
the FTP application receiving this text might well interpret it as
two separate commands, ``{\tt USER nice}'' followed by ``{\tt USER root}''.
But if the monitoring program uses NUL-terminated strings, then it
will effectively see only ``{\tt USER nice}'' and have no opportunity
to detect the subversive action.

\index{NULs!terminating string constants}
\index{string constants!NUL terminated}
Note that Bro string constants are automatically NUL-terminated.

\note{ While Bro itself allows NULs in strings, their presence
in arguments to many Bro functions results in a run-time error, as
often their presence (or, conversely, lack of a NUL terminator)
indicates some sort of problem (particularly
for arguments that will be passed to C~functions).  See
\xref{NULs-run-time} for discussion. }

\index{constants!string|)}

\subsection{String Operators}

\index{operators!string}
\index{relationals!string}
\index{ASCII!as usual character set}
\index{character set!ASCII}
Currently the only string operators provided are the comparison
operators discussed in \xref{rel-operators} and pattern-matching
as discussed in \xref{pattern-matching-ops}.  These operators
perform character by character comparisons based on the native
character set, usually ASCII.

Some functions for manipulating strings are also available.  See
\xref{predefineds-string}.
\index{strings|)}

\labsectsection{{Patterns}}{\label{patterns}}
\index{types!{\tt pattern}}
\index{searching for strings}
\index{pattern matching}

\index{patterns|(}
The {\tt pattern} type holds regular-expression patterns, which can
be used for fast text searching operations.

\labsectsubsection{{Pattern Constants}}{\label{pattern-constants}}

\index{constants!pattern|(}
\index{flex utility@\emph{flex} utility}
\index{lex utility@\emph{lex} utility}
\index{utilities!flex@\emph{flex}}
\index{utilities!lex@\emph{lex}}
You create pattern constants by enclosing text within forward slashes ({\tt /}).
The syntax is the same as for the \emph{flex} version of the \emph{lex}
utility.
%### document explicitly?
For example,
\begin{verbatim}
    /foo|bar/
\end{verbatim}
specifies a pattern that matches either the text ``foo'' or the
text ``bar'';
\begin{verbatim}
    /[a-zA-Z0-9]+/
\end{verbatim}
matches one or more letters or digits, as will
\begin{verbatim}
    /[[:alpha:][:digit:]]+/
\end{verbatim}
or
\begin{verbatim}
    /[[:alnum:]]+/
\end{verbatim}
and the pattern
\begin{verbatim}
    /^rewt.*login+/
\end{verbatim}
matches any string with the text ``rewt'' at the beginning of
a line followed somewhere later in the line by the text ``login''.

You can create disjunctions (patterns the match any of a number of
alternatives) both using the ``{\verb+|+}'' regular expression
operator directly, as in the first example above, or by using it
to join multiple patterns.  So the first example above
could instead be written:
\begin{verbatim}
    /foo/ | /bar/
\end{verbatim}
This form is convenient when constructing large disjunctions because
it's easier to see what's going on.

Note that the speed of the regular expression matching does \emph{not}
depend on the complexity or size of the patterns, so you should feel
free to make full use of the expressive power they afford.

You can assign {\tt pattern} values to variables, hold them in tables,
and so on.  So for example you could have:
\begin{verbatim}
    global address_filters: table[addr] of pattern = {
        [128.3.4.4] = /failed login/ | /access denied/,
        [128.3.5.1] = /access timeout/
    };
\end{verbatim}
and then could test, for example:
\begin{verbatim}
    if ( address_filters[c$id$orig_h] in msg )
        skip_the_activity();
\end{verbatim}

Note though that you cannot use create patterns dynamically.
this form (or any other) to create dynamic

\index{constants!pattern|)}

\labsectsubsection{{Pattern Operators}}{\label{pattern-matching-ops}}
\index{operators!pattern}

There are two types of pattern-matching operators: \emph{exact}
matching and \emph{embedded} matching.

\subsubsection{Exact Pattern Matching}
\index{pattern matching!exact}
\index{== equality operator@\verb+==+{\tt \ } equality operator}
%HEVEA \index{== exact pattern match@\verb+~+ exact pattern match operator}
%BEGIN LATEX
\index{== exact pattern match@$~\tilde{~}~~~${\tt ~} exact pattern match operator}
%END LATEX
Exact matching tests for a
string entirely matching a given
pattern.  You specify exact matching by using the
\verb+==+ equality relational with one {\tt pattern} operand and one
{\tt string} operand (order irrelevant).  For example,
\begin{verbatim}
    "foo" == /foo|bar/
\end{verbatim}
yields true, while
\begin{verbatim}
    /foo|bar/ == "foobar"
\end{verbatim}
yields false.  The \verb+!=+ operator is the negation of the \verb+==+
operator, just as when comparing strings or numerics.
\index{== inequality operator@\verb+"!=+{\tt \ } inequality operator}
%HEVEA \index{== exact match negation@\verb+"!~+ exact match negation}
%BEGIN LATEX
\index{== exact match negation@\verb+"!+$\tilde{~}~~$\kludge exact match negation}
%END LATEX

Note that for exact matching, the \verb+^+ (anchor to beginning-of-line)
and \verb+$+ (anchor to end-of-line) regular expression operators are
redundant: since the match is \emph{exact}, every pattern is implicitly
anchored to the beginning and end of the line.

\subsubsection{Embedded Pattern Matching}
\index{pattern matching!embedded}

\index{in operator@\verb+in+ operator}
Embedded matching tests whether a given pattern appears anywhere
within a given string.
You specify embedded pattern matching
using the {\tt in} operator.  It takes two operands, the first
(which must appear on the left-hand side) of type {\tt pattern},
the second of type {\tt string}.
For example,
\begin{verbatim}
    /foo|bar/ in "foobar"
\end{verbatim}
yields true, as does
\begin{verbatim}
    /oob/ in "foobar"
\end{verbatim}
but
\begin{verbatim}
    /^oob/ in "foobar"
\end{verbatim}
does not, since the text ``oob'' does not appear the beginning
of the string ``foobar''.
Note, though, that the {\tt \$} regular expression operator (anchor
to end-of-line) is not currently supported, so:
\begin{verbatim}
    /oob$/ in "foobar"
\end{verbatim}
currently yields true.  This is likely to change in the future.
\index{bugs!{\tt \$} pattern operator not supported}

\index{in2 operator@\verb+"!in+ negation of {\tt in} operator}
\index{not in operator@\verb+"!in+ negation of {\tt in} operator}
Finally, the {\tt !in} operator yields the negation of the {\tt in} operator.

\index{patterns|)}

\labsectsection{{Temporal Types}}{\label{temporal-types}}
\index{time|(}
\index{absolute time}
\index{relative time}
\index{temporal!types}
\index{types!{\tt time}}
\index{types!{\tt interval}}

Bro supports types representing \emph{absolute} and \emph{relative}
times with the {\tt time} and {\tt interval} types, respectively.
%### more discussion here about the two types, plus an example.
%### add summary

\labsectsubsection{{Temporal Constants}}{\label{temporal-constants}}

\index{constants!temporal}
\index{temporal!constants}
\index{constants!time|(}
\index{constants!interval|(}
\index{possible future changes!constants for absolute times}
There is currently no way to specify an absolute time as a constant
(though see the {\tt current_time} and {\tt network_time} functions
in \xref{predefineds-time}).  You can specify {\tt interval} constants,
however, by appending a \emph{time unit} after a numeric constant.
For example,
\begin{verbatim}
    3.5 min
\end{verbatim}
denotes 210~seconds.
The different time units are {\tt usec}, {\tt sec},
{\tt min}, {\tt hr}, and {\tt day}, representing microseconds, seconds,
minutes, hours, and days, respectively.  The whitespace between 
the numeric constant and the unit is optional, and the letter ``s''
may be added to pluralize the unit (this has no semantic effect).
So the above
example could also be written:
\index{usec@{\tt usec} (microseconds) interval unit}
\index{sec@{\tt sec} (seconds) interval unit}
\index{min@{\tt min} (minutes) interval unit}
\index{hr@{\tt hr} (hours) interval unit}
\index{day@{\tt day} interval unit}
\index{interval units!{\tt usec}}
\index{interval units!{\tt sec}}
\index{interval units!{\tt min}}
\index{interval units!{\tt hr}}
\index{interval units!{\tt day}}
\begin{verbatim}
    3.5mins
\end{verbatim}
or
\begin{verbatim}
    150 secs
\end{verbatim}
\index{constants!interval|)}
\index{constants!time|)}

\labsectsubsection{{Temporal Operators}}{\label{temporal-ops}}
\index{operators!temporal}

You can apply arithmetic and relational operators to temporal
values, as follows.

\subsubsection{Temporal Negation}
\index{temporal!negation}
\index{negation!temporal}

The unary {\tt -}\indoponekey{-}{unary operator}{+2unary}
operator can be applied to an {\tt interval} value to yield another
{\tt interval} value.  For example,
\begin{verbatim}
    - 12 hr
\end{verbatim}
represents ``twelve hours in the past.''

\subsubsection{Temporal Addition}
\index{temporal!addition}
\index{addition!temporal}

\indoponekey{+}{addition operator}{+1addition}
Adding two {\tt interval} values yields another {\tt interval} value.
For example,
\begin{verbatim}
    5 sec + 2 min
\end{verbatim}
yields 125~seconds.
Adding a {\tt time} value to an {\tt interval} yields
another {\tt time} value.

\subsubsection{Temporal Subtraction}
\index{temporal!subtraction}
\index{subtraction!temporal}

\indoponekey{-}{subtraction operator}{+2subtraction}
Subtracting a {\tt time} value from another {\tt time} value
yields an {\tt interval} value, as does subtracting an {\tt interval}
value from another {\tt interval}, while subtracting an {\tt interval}
from a {\tt time} yields a {\tt time}.

\subsubsection{Temporal Multiplication}
\index{temporal!multiplication}
\index{multiplication!temporal}

\indoponekey{*}{multiplication operator}{+3multiplication}
You can multiply an {\tt interval} value by a \emph{numeric} value
to yield another {\tt interval} value.  For example,
\begin{verbatim}
   5 min * 6.5
\end{verbatim}
yields 1,950~seconds.  {\tt time} values cannot be scaled by
multiplication or division.

\subsubsection{Temporal Division}
\index{temporal!division}
\index{division!temporal}

\indoponekey{/}{division operator}{+4division}
You can also divide an {\tt interval} value by a \emph{numeric} value
to yield another {\tt interval} value.  For example,
\begin{verbatim}
   5 min / 2
\end{verbatim}
yields 150~seconds.  Furthermore, you can divide one {\tt interval}
value by another to yield a {\tt double}. For example,
\begin{verbatim}
   5 min / 30 sec
\end{verbatim}
yields 10.

\subsubsection{Temporal Relationals}
\index{temporal!relationals}
\index{relationals!temporal}

You may compare two {\tt time} values or two {\tt interval} values
for equality, and also for ordering, where times or intervals
further in the future are considered larger than times or intervals
nearer in the future, or in the past.

\index{time|)}

\labsectsection{{Port Type}}{\label{port-type}}
\index{port type|(}
\index{ports!UDP}
\index{ports!TCP}

The {\tt port} type corresponds to a TCP or UDP port number.  TCP and
UDP ports are distinct.  Thus, a value of type {\tt port} can hold either
a TCP or a UDP port, but at any given time it is holding exactly one of
these.

\labsectsubsection{{Port Constants}}{\label{port-constants}}

\index{constants!port}
\index{ports!constants}
There are two forms of {\tt port}
constants.  The first consists of an unsigned integer followed by either
``{\tt /tcp}'' or ``{\tt /udp}.''  So, for example, ``{\tt 80/tcp}''
corresponds to TCP port~80 (the HTTP protocol used by the World Wide Web).
The second form of constant is specified using a predefined identifier,
such as ``{\tt http}'', equivalent to ``{\tt 80/tcp}.''  These predefined
identifiers are simply {\tt const} variables defined in the Bro
initialization file \pxref{bro-init-file}, such as:
\begin{verbatim}
    const http = 80/tcp;
\end{verbatim}

\labsectsubsection{{Port Operators}}{\label{port-ops}}
\index{ports!operators}
\index{operators!ports}

The only operations that can be applied to {\tt port} values are
relationals.  You may compare them for equality, and also for ordering.
For example,
\begin{verbatim}
     20/tcp < telnet
\end{verbatim}
yields true because {\tt telnet} is a predefined constant set to
{\tt 23/tcp}.  

UDP ports are considered larger than TCP ports, i.e., ``{\tt 0/udp}'' is
larger than ``{\tt 65535/tcp}''.

\index{port type|)}

\labsectsection{{Address Type}}{\label{address-type}}
\index{address type|(}

\index{relationals!address}
Another networking type provided by Bro is {\tt addr}, corresponding to an
IP~address.  The only operations that can be performed on them are
comparisons for equality or inequality (also, a built-in function provides
masking, as discussed below).

When configuring the Bro distribution, if you specify
\xrefconfig{enable-brov6}
then Bro will be built to support both IPv4 and IPv6 addresses,
and an {\tt addr} can hold either.  Otherwise, addresses are
restricted to IPv4.
\index{IPv6 support}

\labsectsubsection{{Address Constants}}{\label{address-constants}}

\index{constants!address}
\index{address type!constants}
\index{IPv4/IPv6 address constants}

Constants of type {\tt addr} have the familiar ``dotted quad'' format,
\mbox{$A_1 {\tt .} A_2 {\tt .} A_3 {\tt .} A_4$}, where the $A_i$ all lie
between 0~and~255.  If you have configured for IPv6 support as discussed
above, then you can also use the colon-separated hexadecimal form
described in \cite{RFC2373}.

\index{hostnames}
\index{constants!hostname}
\label{hostnames}
Often more useful are \emph{hostname} constants.  There is no Bro
type corresponding to Internet hostnames. Because hostnames can correspond
to multiple IP~addresses, you quickly run into ambiguities if comparing
one hostname with another.  Bro does, however, support hostnames as
constants.  Any series of two or more identifiers delimited by dots
forms a hostname constant, so, for example, ``{\tt lbl.gov}'' and
``{\tt www.microsoft.com}'' are both hostname constants (the latter,
as of this writing, corresponds to 5~distinct IP~addresses).  The value of
a hostname constant is a {\tt list} of {\tt addr} containing one
or more elements.  These lists (as with the lists associated with
certain {\tt port} constants, discussed above) cannot be used in
Bro expressions; but they play a central role in \link{initializing
Bro {\tt table}'s and {\tt set}'s}{table-init}.

\labsectsubsection{{Address Operators}}{\label{address-ops}}
\index{address type!operators}
\index{operators!address}

The only operations that can be applied to {\tt addr} values are
comparisons for equality or inequality, using \verb+==+ and \verb+!=+.
However, you can also operate on {\tt addr} values using
\xreffunc{mask_addr} to mask off lower address bits, and \xreffunc{to_net}
to convert an {\tt addr} to a {\tt net} (see below).

\index{address type|)}

\labsectsection{{Net Type}}{\label{net-type}}
\index{net type|(}

\index{address masking}
\index{CIDR}
\index{subnets}
\index{prefixes!network}
\index{network prefixes}
Related to the {\tt addr} type is {\tt net}.  {\tt net} values hold address
prefixes.  Historically, the IP address space was divided into different
\emph{classes} of addresses, based on the uppermost components of a given
address: class~A spanned the range 0.0.0.0 to 127.255.255.255; class~B from
128.0.0.0 to 191.255.255.255; class~C from 192.0.0.0 to 223.255.255.255;
class~D from 224.0.0.0 to 239.255.255.255; and class~E from 240.0.0.0 to
255.255.255.255.  Addresses were allocated to different networks out of
either class A, B, or~C, in blocks of $2^{24}$, $2^{16}$, and $2^8$
addresses, respectively.

Accordingly, {\tt net} values hold either an 8-bit class~A prefix,
a 16-bit class~B prefix, a 24-bit class~C prefix, or a 32-bit class~D
``prefix'' (an entire address).  Values for class~E prefixes are not
defined (because no such addresses are currently allocated, and so shouldn't
appear in other than clearly-bogus packets).

Today, address allocations come not from class~A, B or~C, but instead
from \emph{CIDR} blocks (CIDR = Classless Inter-Domain Routing), which
are prefixes between 1~and 32~bits long in the range 0.0.0.0 to
223.255.255.255.  \deficiency{ Bro \emph{should} deal just with CIDR
prefixes, rather than old-style network prefixes.  However, these are
more difficult to implement efficiently for table searching and the like;
hence currently Bro only supports the easier-to-implement old-style
prefixes.  Since these don't match current allocation policies, often
they don't really fit an address range you'll want to describe.  But
for sites with older allocations, they do, which gives them some basic
utility.}

\index{IPv6 and lack of CIDR prefixes}
In addition, \deficiency{ IPv6 has no notion of old-style network prefixes,
only CIDR prefixes, so the lack of support of CIDR prefixes impairs
use of Bro to analyze IPv6 traffic. }

\labsectsubsection{{Net Constants}}{\label{net-constants}}

\index{constants!net}
\index{net!constants}
You express constants of type {\tt net} in one of two forms, either:
\begin{quotation}
\mbox{$N_1 {\tt .} N_2 {\tt .}$}
\end{quotation}
or
\begin{quotation}
\mbox{$N_1 {\tt .} N_2 {\tt .} N_3 $}
\end{quotation}
where the $N_i$ all lie between 0~and~255.  The first of these corresponds
to class~B prefixes (note the trailing ``{\tt .}'' that's required to
distinguish the constant from a floating-point number), and the second to
class~C prefixes.  \deficiency{ There's currently no way to specify a
class~A prefix. }

\labsectsubsection{{Net Operators}}{\label{net-ops}}
\index{net!operators}
\index{operators!net}

\index{relationals!net}
The only operations that can be applied to {\tt net} values are
comparisons for equality or inequality, using \verb+==+ and \verb+!=+.

\index{net type|)}

\labsectsection{{Records}}{\label{records}}

\index{records|(}
\index{records!fields}
A {\tt record} is a collection of values.  Each value has a name,
referred to as one of the record's {\em fields\/},
and a type.  The values do
not need to have the same type, and there is no restriction on the
allowed types (i.e., each field can be {\em any} type).

\labsectsubsection{{Defining records}}{\label{record-decl}}
A definition of a record type has the following syntax:
\begin{quote}
    {\tt record \{} \emph{field}$^+$ {\tt \}}
\end{quote}
(that is, the keyword {\tt record} followed by one-or-more \emph{field}'s
enclosed in braces),
where a \emph{field} has the syntax:
\begin{quote}
    \emph{identifier} {\tt :} \emph{type} \emph{field-attributes}$^*$ {\tt ;}
    \emph{identifier} {\tt :} \emph{type} \emph{field-attributes}$^*$ {\tt ,}
\end{quote}
Each field has a name given by the identifier (which can be the same
as the identifier of an existing variable or a field in another record).
\index{records!fields!legal names}
\index{names!case-sensitive}
Field names must follow the same syntax as that for Bro variable names (see
\xref{variables}), namely they must begin with a letter or
an underscore (``{\tt _}'') followed by zero or more letters, underscores,
or digits.  Bro reserved words such as {\tt if} or {\tt event} cannot
be used for field names.  Field names are
case-sensitive.

Each field holds a value of the given type.
We discuss the optional \link{\emph{field-attributes}}{field-attrs} below.
Finally, you can use either a semicolon or a comma to terminate the
definition of a record field.

\label{conn-id}
For example, the following record type:
\begin{verbatim}
    type conn_id: record {
        orig_h: addr;  # Address of originating host.
        orig_p: port;  # Port used by originator.
        resp_h: addr;  # Address of responding host.
        resp_p: port;  # Port used by responder.
    };
\end{verbatim}
is used throughout Bro scripts to denote a connection identifier
by specifying the connections originating and responding addresses
and ports.  It has four fields: {\tt orig_h} and {\tt resp_h} of type
{\tt addr}, and {\tt orig_p} of {\tt resp_p} of type {\tt port}.

\labsectsubsection{{Record Constants}}{\label{record-constants}}
\index{constants!record|(}

You can initialize values of type
{\tt record} using either assignment from another, already existing
{\tt record} value; or element-by-element; or using a \link{\emph{record constructor}}{record-constructors}.

In a Bro function or event handler, we could declare a local
variable the \link{{\tt conn_id}}{conn-id} type given above:
\begin{verbatim}
    local id: conn_id;
\end{verbatim}
and then explicitly assign each of its fields:
\begin{verbatim}
    id$orig_h = 207.46.138.11;
    id$orig_p = 31337/tcp;
    id$resp_h = 207.110.0.15;
    id$resp_p = 22/tcp;
\end{verbatim}
\deficiency{ One danger with this initialization method is that if you forget
to initialize a field, and then later access it, you will \emph{crash} Bro. }

Or we could use:
\begin{verbatim}
    id = [$orig_h = 207.46.138.11, $orig_p = 31337/tcp,
          $resp_h = 207.110.0.15, $resp_p = 22/tcp];
\end{verbatim}

This second form is no different from assigning a {\tt record} value 
computed in some other fashion, such as the value of another variable,
a table element, or the value returned by a function call.  Such assignments
must specify \emph{all} of the fields in the target (i.e., in {\tt id} in
this example), unless the missing field has the \link{\xrefattr{optional} or
\xrefattr{default} attribute}{record-decl}.

\index{constants!record|)}

\labsectsubsection{{Accessing Fields Using ``{\tt \$}}''}{\label{record-dollar}}

\index{records!fields!accessing}
\indopone{\$}{record field access operator}
You access and assign record fields using the ``{\tt \$}'' (dollar-sign)
operator.  As indicated in the example above, for the record {\tt id} we can
access its {\tt orig_h} field using:
\begin{verbatim}
    id$orig_h
\end{verbatim}
which will yield the {\tt addr} value {\tt 207.46.138.11}.

\labsectsubsection{{Record Assignment}}{\label{record-assign}}
\index{records!assignment|(}
\index{assigning records|(}
You can assign one record value to another using simple assignment:
\begin{verbatim}
    local a: conn_id;
    ...
    local b: conn_id;
    ...
    b = a;
\end{verbatim}
\index{copy!shallow vs. deep}
\index{shallow copy}
\index{deep copy}
\label{shallow-copy}
Doing so produces a \emph{shallow} copy.  That is, after the assignment,
{\tt b} refers to the same record as does {\tt a}, and an assignment
to one of {\tt b}'s fields will alter the field in {\tt a}'s value
(and vice versa for an assignment to one of {\tt a}'s fields).
However, assigning again to {\tt b} itself, or assigning to {\tt a} itself,
will break the connection.

\deficiency{ Bro lacks a mechanism for specifying a \emph{deep} copy,
in which no linkage is connected between {\tt b} and {\tt a}. }  Consequently,
you must be careful when assigning records to ensure you account for
the shallow-copy semantics.

You can also assign to a record another record that has fields with
the same names and types, even if they come in a different order.
For example, if you have:
\begin{verbatim}
    local b: conn_id;
    local c: record {
        resp_h: addr, orig_h: addr;
        resp_p: port, orig_p: port;
    };
\end{verbatim}
then you can assign either {\tt b} to {\tt c} or vice versa.

You could \emph{not}, however, make the assignment (in either
direction) if you had:
\begin{verbatim}
    local b: conn_id;
    local c: record {
        resp_h: addr, orig_h: addr;
        resp_p: port, orig_p: port;
        num_alerts: count;
    };
\end{verbatim}
because the field {\tt num_alerts} would either be missing or excess.

\index{records!field attributes}
\index{field attributes}
\index{attributes!record fields}
\label{field-attrs}
However,
when declaring a record you can associate \link{attributes}{attrs}
with the fields.  The relevant ones are \xrefattr{optional},
which indicates that when assigning to the record
you can omit the field, and \xrefattr{default} {\tt = \emph{expr}},
which indicates
that if the field is missing, then a reference to it returns the value of
the expression \emph{expr}.  So if instead you had:
\begin{verbatim}
    local b: conn_id;
    local c: record {
        resp_h: addr, orig_h: addr;
        resp_p: port, orig_p: port;
        num_alerts: count &optional;
    };
\end{verbatim}
then you could execute {\tt c = b} even though {\tt num_alerts} is
missing from {\tt b}.  You still could not execute {\tt b = c}, though,
since in that direction, {\tt num_alerts} is an extra field (regardless
of whether it has been assigned to or not---the error is a type-checking
error, not a run-time error).

The same holds for:
\begin{verbatim}
    local b: conn_id;
    local c: record {
        resp_h: addr, orig_h: addr;
        resp_p: port, orig_p: port;
        num_alerts: count &default = 0;
    };
\end{verbatim}
I.e., you could execute {\tt c = b} but not {\tt b = c}.  The only
difference between this example and the previous one is that for
the previous one, access to {\tt c\$num_alerts} without having first
assigned to it results in a run-time error, while in the second,
it yields {\tt 0}.

You can test for whether a record field exists using the
\link{{\tt ?\$} operator}{field-test-op}.

Finally, all of the rules for assigning records also apply when
passing a record value as an argument in a function call or
an event handler invocation.

\index{assigning records|)}
\index{records!assignment|)}

\index{records|)}

\labsectsection{{Tables}}{\label{tables}}

\index{tables|(}
\index{array!associative}
\index{associative array}
\index{index!of a table}
\index{yield!of a table}
{\tt table}'s provide \emph{associative arrays}: mappings from one set of
values to another.  The values being mapped are termed the \emph{index}
(or \emph{indices}, if they come in groups of more than one)
and the results of the mapping the \emph{yield}.

Tables are quite powerful, and indexing them is very efficient,
boiling down to a single hash table lookup.  So you should take advantage
of them whenever appropriate.

\labsectsubsection{Declaring Tables}{\label{table-decl}}
You declare tables using the following syntax:
\begin{quote}
    {\tt table [} \emph{type}$^+$ {\tt ] of} \emph{type}
\end{quote}
\index{scalars}
where \emph{type}$^+$ is one or more types, separated by commas.

The indices can be of the following \emph{scalar} types: \emph{numeric},
\emph{temporal}, \emph{enumerations},
{\tt string}, {\tt port}, {\tt addr}, or {\tt net}.
The yield can be of any type.  So, for example:
\begin{verbatim}
    global a: table[count] of string;
\end{verbatim}
declares {\tt a} to be a table indexed by a {\tt count} value and
yielding a {\tt string} value, similar to a regular array in a
language like C.  The yield type can also be more complex:
\begin{verbatim}
    global a: table[count] of table[addr, port] of conn_id;
\end{verbatim}
declares {\tt a} to be a table indexed by {\tt count} and
yielding another table, which itself is indexed by an {\tt addr}
and a {\tt port} to yield a \link{{\tt conn_id} record}{conn-id}.

\index{array!multi-dimensional}
\index{multi-dimensional table}
This second example illustrates a \emph{multi-dimensional} table,
one indexed not by a single value but by a \emph{tuple} of values.

\labsectsubsection{Initializing Tables}{\label{table-init}}
You initialize tables by enclosing a set of initializers within braces.
Each initializer looks like:
\begin{quote}
    {\tt [} \emph{expr-list} {\tt ] =} \emph{expr}
\end{quote}
where \emph{expr-list} is a comma-separated list of expressions
corresponding to an index of the table (so, for a table indexed
by {\tt count}, for example, this would be a single expression
of type {\tt count}) and \emph{expr} is the yield value to 
assign to that index.

For example,
\begin{verbatim}
    global a: table[count] of string = {
        [11] = "eleven",
        [5] = "five",
    };
\end{verbatim}
initializes the table {\tt a} to have two elements, one indexed
by {\tt 11} and yielding the string {\tt "eleven"} and the other
indexed by {\tt 5} and yielding the string {\tt "five"}.
(Note the comma after the last list element; it is optional,
similar to how C allows final commas in declarations.)

You can also group together a set of indices together to initialize
them to the same value:
\begin{verbatim}
    type HostType: enum { DeskTop, Server, Router };
    global a: table[addr] of HostType = {
        [[155.26.27.2, 155.26.27.8, 155.26.27.44]] = Server,
    };
\end{verbatim}
is equivalent to:
\begin{verbatim}
    type HostType: enum { DeskTop, Server, Router };
    global a: table[addr] of HostType = {
        [155.26.27.2] = Server,
        [155.26.27.8] = Server,
        [155.26.27.44] = Server,
    };
\end{verbatim}
This mechanism also applies to \link{\emph{hostnames}}{hostnames},
which can be used in table initializations for any indices of
type {\tt addr}.  For example, if {\tt www.my-server.com} corresponded
to the addresses 155.26.27.2 and 155.26.27.44, then the above
could be written:
\begin{verbatim}
    global a: table[addr] of HostType = {
        [[www.my-server.com, 155.26.27.8]] = Server,
    };
\end{verbatim}
and if it corresponded to all there, then:
\begin{verbatim}
    global a: table[addr] of HostType = {
        [www.my-server.com] = Server,
    };
\end{verbatim}

You can also use multiple index groupings across different indices:
\begin{verbatim}
    global access_allowed: table[addr, port] of bool = {
        [www.my-server.com, [21/tcp, 80/tcp]] = T,
    };
\end{verbatim}
is equivalent to:
\begin{verbatim}
    global access_allowed: table[addr, port] of bool = {
        [155.26.27.2, 21/tcp] = T,
        [155.26.27.2, 80/tcp] = T,
        [155.26.27.8, 21/tcp] = T,
        [155.26.27.8, 80/tcp] = T,
        [155.26.27.44, 21/tcp] = T,
        [155.26.27.44, 80/tcp] = T,
    };
\end{verbatim}

\label{cross-product-init}
\fixme{add example of cross-product initialization of sets}

\labsectsubsection{Table Attributes}{\label{table-attr}}
When declaring a table, you can specify a number of attributes
that affect its operation:

\begin{description}

\index{default values}
\itemindattr{default}
Specifies a value to yield when an index does not appear in the table.
Syntax:
\begin{quote}
{\tt \&default = \emph{expr}}
\end{quote}
\emph{expr} can have one of two forms.  If it's type is the same as
the table's yield type, then \emph{expr} is evaluated and returned.
\index{dynamic defaults}
If it's type is a {\tt function} with arguments whose types correspond
left-to-right with the index types of the table, and which returns
a type the same as the yield type, then that function is called with
the indices that yielded the missing value to compute the default value.

For example:
\begin{verbatim}
    global a: table[count] of string &default = "nothing special";
\end{verbatim}
will return the string {\tt "nothing special"} anytime {\tt a} is
indexed with a {\tt count} value that does not appear in {\tt a}.

A more dynamic example:
\begin{verbatim}
    function nothing_special(): string
        {
        if ( panic_mode )
            return "look out!";
        else
            return "nothing special";
        }

    global a: table[count] of string &default = nothing_special;
\end{verbatim}

An example of using a function that computes using the index:
\begin{verbatim}
    function make_pretty(c: count): string
        {
        return fmt("**%d**", c);
        }

    global a: table[count] of string &default = make_pretty;
\end{verbatim}

\index{memory management}
\index{state management}
\index{management!of state}
\itemindattr{create_expire}
Specifies that elements in the table should be \emph{automatically
deleted} after a given amount of time has elapsed since they were
first entered into the table.
Syntax:
\begin{quote}
{\tt \&create_expire = \emph{expr}}
\end{quote}
where \emph{expr} is of type \xreftype{interval}.

\itemindattr{read_expire}
The same as \xrefattr{create_expire} except the element is deleted
when the given amount of time has lapsed since the last time the
element was accessed from the table.

\itemindattr{write_expire}
The same as \xrefattr{create_expire} except the element is deleted
when the given amount of time has lapsed since the last time the
element was entered or modified in the table.

\itemindattr{expire_func}
Specifies a function to call when an element is due for expression
because of \xrefattr{create_expire}, \xrefattr{read_expire}, or
\xrefattr{write_expire}.
Syntax:
\begin{quote}
{\tt \&expire_func = \emph{expr}}
\end{quote}
\emph{expr} must be a function that takes an argument with the same
type as the table's yield type and returns an \xreftype{interval} value.
The {\tt interval} indicates for how much longer the element should
remain in the table; returning {\tt 0 secs} or a negative value instructs
Bro to go ahead and delete the element.

\deficiency{ There should be a version of {\tt \&expire_func} that
is passed the index of the element as well as its yield value. }

\end{description}

You specify multiple attributes by listing one after the other,
\emph{without} commas between them:
\begin{verbatim}
    global a: table[count] of string &default="foo" &write_expire=5sec;
\end{verbatim}
Note that you can specify each type of attribute only once.  You can,
however, specify more than one of \xrefattr{create_expire},
\xrefattr{read_expire}, and \xrefattr{write_expire}.  In that case,
whenever any of the corresponding timers expires, the element will
be deleted.

\labsectsubsection{Accessing Tables}{\label{table-access}}
As usual, you access the values in tables by indexing them with 
a value (for a single index) or list of values (multiple indices)
enclosed in {\tt []}'s.
\index{sub-tables!lack of}
\deficiency{ Presently, when indexing a multi-dimensional table
you must provide \emph{all} of the relevant indices; you can't
leave one out in order to extract a sub-table. }

\label{record-index}
You can also index arrays using {\tt record}'s, providing the
record is comprised of values whose types match that of the table's
indices.  (Any record fields whose types are themselves records
are recursively unpacked to effect this matching.)  For example,
if we have:
\begin{verbatim}
    local b: table[addr, port] of conn_id;
    local c = 131.243.1.10;
    local d = 80/tcp;
\end{verbatim}
then we could index {\tt b} using {\tt b[c, d]}, but if we had:
\begin{verbatim}
    local e = [$field1 = c, $field2 = d];
\end{verbatim}
we could also index it using {\tt a[d]}

You can test whether a table holds a given index using
the \link{{\tt in} operator}{in-operator}.  For example:
\begin{verbatim}
    [131.243.1.10, 80/tcp] in b
\end{verbatim}
or
\begin{verbatim}
    e in b
\end{verbatim}
per the examples above.  In addition, if the table has only
a single index (not multi-dimensional), then you can omit
the {\tt []}'s:
\begin{verbatim}
    local active_connections: table[addr] of conn_id;
    ...
    if ( 131.243.1.10 in active_connections )
        ...
\end{verbatim}

\labsectsubsection{Table Assignment}{\label{table-assign}}
An indexed can be the target of an assignment:
\begin{verbatim}
    b[131.243.1.10, 80/tcp] = c$id;
\end{verbatim}
You can also assign to an entire table.  For example, suppose we
have the global:
\begin{verbatim}
    global active_conn_count: table[addr, port] of count;
\end{verbatim}
\index{tables!clearing entries}
then we could later clear the contents of the table using:
\begin{verbatim}
    local empty_table: table[addr, port] of count;
    active_conn_count = empty_table;
\end{verbatim}
Here the first statement declares a local variable {\tt empty_table}
with the same type as {\tt active_conn_count}.  Since we don't
initialize the table, it starts out empty.  Assigning it to
{\tt active_conn_count} then replaces the value of {\tt active_conn_count}
with an empty table.
\index{copy!shallow vs. deep}
\index{shallow copy}
\index{deep copy}
\note{ As with {\tt record}'s, assigning {\tt table} values results
in a \link{\emph{shallow} copy}{shallow-copy}. }

In addition to directly accessing an element of a table by specifying
its index, you can also loop over all of the indices in a table
using the \xrefstmt{for} statement.

\labsectsubsection{Deleting Table Elements}{\label{table-del}}
You can remove an individual element from a table using the
\xrefstmt{delete} statement:
\begin{verbatim}
    delete active_host[c$id];
\end{verbatim}
will remove the element in {\tt active_host} corresponding to
the connection identifier {\tt c\$id} (which is a
\link{{\tt conn_id} record}{conn-id}).  If the element isn't
present, nothing happens.

\index{tables|)}

\section{Sets}
\label{set-type}
\index{set type|(}
Sets are very similar to tables.  The principle difference is that they are
simply a collection of indices; they don't yield any values.
You declare tables using the following syntax:
\begin{quote}
    {\tt set [} \emph{type}$^+$ {\tt ]}
\end{quote}
where, as with {\tt table}s,
\emph{type}$^+$ is one or more scalar types (or records), separated by commas.

You initialize sets listing their elements in braces:
\begin{verbatim}
    global a = { 21/tcp, 23/tcp, 80/tcp, 443/tcp };
\end{verbatim}
which implicitly types {\tt a} as a {\tt set[port]} and then
initializes it to contain the given 4 {\tt port} values.

For multiple indices, you enclose each set of indices in brackets:
\begin{verbatim}
    global b = { [21/tcp, "ftp"], [23/tcp, "telnet"], };
\end{verbatim}
which implicitly {\tt b} as {\tt set[port, string]} and then
initializes it to contain the given two elements.  (As with tables,
the comma after the last element is optional.)

As with tables, you can group together sets of indices:
\begin{verbatim}
    global c = { [21/tcp, "ftp"], [[80/tcp, 8000/tcp, 8080/tcp], "http"], };
\end{verbatim}
initializes {\tt c} to contain 4 elements.

Also as with tables, you can use the
\xrefattr{create_expire},
\xrefattr{read_expire},
and
\xrefattr{write_expire}
attributes to control the automatic expiration of elements in a set.
\deficiency{ However, the \xrefattr{expire_func} attribute is not
currently supported. }

You can test for whether a particular member is in a set using
the \link{{\tt in} operator}{in-operator}, as with tables.  You
add elements using the \xrefstmt{add} statement:
\begin{verbatim}
    add c[443/tcp, "https"];
\end{verbatim}
and can remove them using the \xrefstmt{delete} statement:
\begin{verbatim}
    add d[21/tcp, "ftp"];
\end{verbatim}
Also, as with tables, you can assign to the entire set, which assigns
a \link{\emph{shallow} copy}{shallow-copy}.

Finally, as with tables, you can loop over all of the indices in a set
using the \xrefstmt{for} statement.

\index{set type|)}

\section{Files}
\index{file type|(}
\deficiency{ Bro currently supports only a very simple notion of files.
You can only
write to files, you can't read from them: and files are essentially
untyped---the only values you can write to them are {\tt string}'s or
values that can be converted to {\tt string}.}

You declare {\tt file} variables simply as type {\tt file}:
\begin{verbatim}
    global f: file;
\end{verbatim}

You can create values of type {\tt file} by using the \xrefindfunc{open}
function:
\begin{verbatim}
    f = open("suspicious_info.log");
\end{verbatim}
will create (or recreate, if it already exists) the file
\emph{suspicious_info.log} and open it for writing.  You can also use
\xrefindfunc{open_for_append} to append to an existing file (or create
a new one, if it doesn't exist).

You write to files using the \xrefstmt{print} statement:
\begin{verbatim}
    print f, 5 * 6;
\end{verbatim}
will print the text {\tt 30} to the file corresponding to the value of {\tt f}.

There is no restriction regarding how many files you can have open at a
given time.  In particular, even if your system has a limit imposed by
\indtt{RLIMIT_NOFILE} as set by the system call \indtt{setrlimit}{system calls}.
If, however, you want to to close a file, you can do so using \xreffunc{close},
and you can test whether a file is open using \xreffunc{active_file}.

Finally, you can control whether a file is buffered using \xreffunc{set_buf},
and can flush the buffers of all open files using \xreffunc{flush_all}.

\index{file type|)}

\section{Functions}
\label{functions}
\index{functions|(}
\index{function type|(}
You declare a Bro {\tt function} type using:
\begin{quote}
    {\tt function (} \emph{argument}$^*$ {\tt )} \optsyntax{{\tt :} \emph{type}}
\end{quote}
where \emph{argument}$^+$ is a (possibly empty)
comma-separated list of arguments, and the final
``{\tt :} \emph{type}'' declares the return type of the function.
It is optional; if missing, then the function does not return a value.

Each argument is declared using:
\begin{quote}
    \emph{param-name} {\tt :} \emph{type}
\end{quote}

So, for example:
\begin{verbatim}
    function(a: addr, p: port): string
\end{verbatim}
corresponds to a function that takes two parameters, {\tt a} of type
{\tt addr} and {\tt p} of type {\tt port}, and returns a value of
type {\tt string}.

You could furthermore declare:
\begin{verbatim}
    global generate_id: function(a: addr, p: port): string;
\end{verbatim}
to define {\tt generate_id} as a variable of this type.  Note that
the declaration does \emph{not} define the body of the function,
and, indeed, {\tt generate_id} could have different function bodies
at different times, by assigning different function values to it.

When defining a function including its body, the syntax is slightly different:
\begin{quote}
    {\tt function} \emph{func-name} {\tt (} \emph{argument}$^*$ {\tt )} \optsyntax{{\tt :} \emph{type}} {\tt \{} \emph{statement}$^*$ {\tt \}}
\end{quote}
That is, you introduce \emph{func-name}, the name of the function, between
the keywork {\tt function} and the opening parenthesis of the argument
list, and you list the statements of the function within braces at the end.

For the previous example, we could define its body using:
\begin{verbatim}
    function generate_id(a: addr, p: port): string
        {
        if ( a in local_servers )
            # Ignore port, they're always the same.
            return fmt("server %s", a);

        if ( p < 1024/tcp )
            # Privileged port, flag it.
            return fmt("%s/priv-%s", a, p);

        # Nothing special - default formatting.
        return fmt("%s/%s", a, p);
        }
\end{verbatim}
We also could have omitted the first definition; a function definition
like the one immediately above automatically defines {\tt generate_id}
as a function of type {\tt function(a: addr, p: port): string}.  Note
\index{redefining functions}
\index{functions!redefining}
though that if \emph{func-name} was indeed already declared, then the
argument list much match \emph{exactly} that of the previous definition.
This includes the names of the arguments; \unlikeC{you cannot change
the argument names between their first (forward) definition and the
full definition of the function.}

You can also define functions without using any name.  These are
referred to as \link{anonymous functions}{anonymous-expr}, and
are a type of expression.

You can only do two things with functions: \link{call them}{function-call-expr}
or assign them.  As an example of the latter, suppose we have:
\begin{verbatim}
    local id_funcs: table[conn_id] of function(p: port, a: addr): string;
\end{verbatim}
would declare a local variable indexed by a
\link{{\tt conn_id} record}{conn-id} value to yield a function of the
same type as in the previous example.  You could then execute:
\begin{verbatim}
    id_funcs[c$id] = generate_id
\end{verbatim}
or call whatever function is associated with a given {\tt conn_id}:
\begin{verbatim}
    print fmt("id is: %s", id_funcs[c$id](80/tcp, 1.2.3.4));
\end{verbatim}

\index{function type|)}
\index{functions|)}

\section{Event handlers}
\label{event-handlers}
\index{event handlers|(}
\index{event type|(}

Event handlers are nearly identical in both syntax and semantics
to functions, with the two differences being that event handlers
have no return type since they never return a value, and you cannot
call an event handler.  You declare an event handler using:
\begin{quote}
    {\tt event (} \emph{argument}$^*$ {\tt )}
\end{quote}
So, or example,
\begin{verbatim}
    local eh: event(attack_source: addr, severity: count)
\end{verbatim}
declares the local variable \texttt{eh} to have a type corresponding
to an event handler that takes two arguments, {\tt attack_source} of
type {\tt addr}, and {\tt severity} of type {\tt count}.

To declare an event handler along with its body, the syntax is:
\begin{quote}
    {\tt event} \emph{handler} {\tt (} \emph{argument}$^*$ {\tt )} {\tt \{} \emph{statement}$^*$ {\tt \}}
\end{quote}

As with functions, you can assign event handlers to variables of the
same type.  Instead of calling event handlers like functions, though,
\index{event handler!invocation}
\index{invoking event handlers}
instead they are \emph{invoked}.  This can happen in one of three ways:
\begin{description}
\index{event engine}

\item[From the event engine]
When the event engine detects an event for which you have defined a
corresponding event handler, it queues an event for that handler.  The
handler is invoked as soon as the event engine finishes processing the
current packet (and invoking any other event handlers that were queued
first).  The various event handlers known to the event engine are discussed
in Chapter~\xref{analyzers}.

\item[Via the {\tt event} statement]
The \xrefstmt{event} statement queues an event for the given event handler
for immediate processing.  For example:
\begin{verbatim}
    event password_exposed(c, user, password);
\end{verbatim}
queues an inovocation of the event handler {\tt password_exposed} with
the arguments {\tt c}, {\tt user}, and {\tt password}.  Note that
{\tt password_exposed} must have been previously declared as an event
handler with a compatible set of arguments.

Or, if we had a local variable {\tt eh} as defined above, we could execute:
\begin{verbatim}
    event eh(src, how_severe);
\end{verbatim}
if {\tt src} is of type {\tt addr} and {\tt how_severe} of type {\tt count}.

\item[Via the {\tt schedule} expression]
The \xrefexpr{schedule} expression queues an event for future invocation.
For example:
\begin{verbatim}
    schedule 5 secs { password_exposed(c, user, password) };
\end{verbatim}
would cause {\tt password_exposed} to be invoked 5 seconds in the future.

\end{description}

\index{event type|)}
\index{event handlers|)}

\section{The {\tt any} type}
\index{any type@``any'' type|(}
The {\tt any} type is a type used internally by Bro to bypass strong
typing.  For example, the \xreffunc{fmt} function takes arguments
of type {\tt any}, because its arguments can be of different types,
and of variable length.  However, the {\tt any} type is not supported
\index{casting!not provided in Bro}
\index{type casting!not provided in Bro}
for use by the user; while Bro lets you declare variables of type {\tt any},
it does not allow assignment to them.
\index{possible future changes!use of {\tt any} type for bypassing strong typing}
This may change in the future.  Note, though, that you can achieve
some of the same effect using {\tt record} values with \xrefattr{optional}
fields.

\index{any type@``any'' type|)}

\label{last-type}
%HEVEA\cutend

