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

\labsectchapter{{Global and Local Variables}}{\label{variables}}

\section{Overview}

\index{variables!overview}

Bro variables can be complicated to understand because they have
a number of possibilities and features.  They can be
\link{{global} or {local}}{var-scope} in scope;
\link{{modifiable} or {constant}}{var-mod} (unchangeable);
\link{explicitly or implicitly typed}{var-type};
\link{optionally initialized}{var-init};
defined to have additional \link{\emph{attributes}}{var-attr};
and, for global variables,
\link{\emph{redefined}}{var-redef} 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.

\subsection{Scope}
\label{var-scope}
\index{variables!scoping}
\index{scoping of variables}
\index{global variables}
\index{local variables}
\indtt{global}{variable declaration}
\indtt{local}{variable declaration}
\emph{Global} variables are available throughout your policy script (once
declared), while the scope of \emph{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:
\begin{quotation}
    \texttt{global} \emph{name} \texttt{:} \emph{type} \texttt{;}
\end{quotation}
or
\begin{quotation}
    \texttt{local} \emph{name} \texttt{:} \emph{type} \texttt{;}
\end{quotation}
which declares \emph{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 {\tt function} or {\tt event} and associating
its initial value with that of the function or event handler).  So
the following is fine:
\begin{verbatim}
    global a: count;

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

    global c: addr;
\end{verbatim}

However, you cannot mix declarations of global variables with
\link{global statements}{global-stmts}; the following is not allowed:
\begin{verbatim}
    print "hello, world";
    global a: count;
\end{verbatim}

Local variables, on the other hand, can \emph{only} be declared within a
function or event handler.  (Unlike for global statements, these declarations
\emph{can} come after statements.)  Their scope persists to the end of
the function.  For example:
\begin{verbatim}
    function b(p: port): string
        {
        if ( p < 1024/tcp )
            local port_type = "privileged";
        else
            port_type = "ephemeral";

        return port_type;
        }
\end{verbatim}

\subsection{Modifiability}
\label{var-mod}
\index{variables!modifiability}
\index{modifiability of variables}
\indtt{const}{variable declaration}
For both global and local variables, you can declare that the
variable \emph{cannot be modified} by declaring it using the {\tt const}
keyword rather than {\tt global} or {\tt local}:
\begin{verbatim}
    const response_script = "./scripts/nuke-em";
\end{verbatim}
Note that {\tt const} variables \emph{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 {\tt const} variables \emph{can} be redefined via
\link{\tt redef}{var-redef}.

\subsection{Typing}
\label{var-type}
\index{variables!typing}
\index{typing of variables}
\index{implicit typing}
\index{explicit typing}
When you define a variable, you can \emph{explicitly} type it by
specifying its type after a colon.  For example,
\begin{verbatim}
    global a: count;
\end{verbatim}
directly indicates that {\tt a}'s type is {\tt count}.

However, Bro can also \emph{implicitly} type the variable by looking
at the type of the expression you use to initialize the variable:
\begin{verbatim}
    global a = 5;
\end{verbatim}
also declares {\tt a}'s type to be {\tt count}, since that's
the type of the initialization expression (the constant {\tt 5}).
There is no difference between this declaration and:
\begin{verbatim}
    global a: count = 5;
\end{verbatim}
except that it is more concise both to write and to read.  In particular,
Bro remains \emph{strongly} typed, even though it also supports \emph{implicit}
typing; the key is that once the type is implicitly inferred, it is thereafter
strongly enforced.

\label{type-inference}
\index{type inference}
\index{inferring types}
Bro's \emph{type inference} is fairly powerful: it can generally figure
out the type whatever initialization expression you use.  For example,
it correctly infers that:
\begin{verbatim}
    global c = { [21/tcp, "ftp"], [[80/tcp, 8000/tcp, 8080/tcp], "http"], };
\end{verbatim}
specifies that {\tt c}'s type is {\tt 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.

\subsection{Initialization}
\label{var-init}
\index{variables!initialization}
\index{initialization of variables}
When defining a variable, you can optionally specify an initial
value for the variable:
\begin{verbatim}
    global a = 5;
\end{verbatim}
indicates that the initial value of {\tt a} is the value {\tt 5}
(and also implicitly types {\tt a} as type {\tt count}, per \xref{var-type}).

The syntax of an initialization is ``{\tt =} \emph{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 \xref{table-init} and \xref{set-type}.

\subsection{Attributes}
\label{var-attr}
\index{variables!attributes}
\index{attributes}
\label{attrs}
When defining a variable, you can optionally specify a set of
\emph{attributes} associated with the variable, which specify
additional properties associated with it.  Attributes have two forms:
\begin{quotation}
    \texttt{\&} \emph{attr}
\end{quotation}
for attributes that are specified simply using their name, and
\begin{quotation}
    \texttt{\&} \emph{attr} \texttt{=} \emph{expr}
\end{quotation}
for attributes that have a value associated with them.

The attributes
\texttt{\&redef}
\texttt{\&add_func}
and
\texttt{\&delete_func},
pertain to redefining variables; they are discussed in \xref{var-redef}.

The attributes
\texttt{\&default},
\texttt{\&create_expire},
\texttt{\&read_expire},
\texttt{\&write_expire}, and
\texttt{\&expire_func}
are for use with {\tt table}'s and {\tt set}'s.
See \xref{table-attr} for discussion.

The attribute
\texttt{\&optional}
specifies that a {\tt record} field is optional.  See \xref{field-attrs}
for discussion.

Finall, to specify multiple attributes, you do \emph{not} separate them
with commas (doing so would actually make Bro's grammar ambiguous), but
just list them one after another.  For example:
\begin{verbatim}
    global a: table[port] of string &redef &default="missing";
\end{verbatim}

\subsection{Refinement}
\label{var-redef}
\index{variables!redefining}
\index{variables!refinement}
\index{refinement}
\index{redefining variables}

To do.

\indattr{redef}

\indattr{add_func}

\indattr{delete_func}

