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

\labsectchapter{{Predefined Variables and Functions}}{\label{predefineds}}
%HEVEA\cutdef[1]{section}

\fixme{ The variables and functions are presented alphabetically.  They should
instead be organized into those with related purposes, because they can
already be located alphabetically using the index. }

\section{Predefined Variables}
\index{predefined variables|(}

Bro predefines and responds to the following variables:

\begin{description}
\indpredefvar{bro_log_file}{file}
Used to record the messages logged by {\tt log} statements.

\index{stderr@\emph{stderr}}
\index{log file}
Default: \emph{stderr}, unless you \load the \xrefanalyzer{log} analyzer;
see \xrefvarnott{bro_log_file} for further discussion.

\indpredefvar{capture_filter}{string}
Specifies what packets Bro's filter should record \pxref{capture-filter}.

\indpredefvar{direct_login_prompts}{set[string]}
Strings that when seen in a login dialog indicate that
the user will be directly logged in after entering their username,
without requiring a password \pxrefvarnott{direct_login_prompts}.

\indpredefvar{discarder_maxlen}{int}
The maximum amount of data that Bro should pass to a TCP or UDP
\emph{discarder} \pxref{discarders}.

Default: 128 bytes.

\indpredefvar{done_with_network}{bool}
Set to true when Bro is done reading from the network (or from
the save files being played back, per \xref{play-back}).  The variable is set by a
handler for \xrefevent{net_done}.

Default: initially set to false.

\index{network interfaces}
\index{analysis!on-line}
\index{on-line analysis}
\indpredefvar{interfaces}{string}
A blank-separated list of network interfaces from which Bro should
read network traffic.  Bro merges packets from the interfaces according
to their timestamps.  \deficiency{ All interfaces \emph{must} have the
same link layer type. }

If empty, then Bro does not read any network traffic, unless one
or more interfaces are specified using the \xrefflag{-i} flag.

\note{ {\tt interfaces} has an \xrefattr{add_func} that allows you to add
interfaces to the list simply using a {\tt +=} initialization
\pxref{refinement}. }

Default: empty.

\indpredefvar{login_failure_msgs}{set[string]}
Strings that when seen in a \xrefanalyzer{login} dialog indicate that
a user's attempt to authenticate failed
\pxrefvarnott{login_failure_msgs}.

\indpredefvar{login_non_failure_msgs}{set[string]}
Exceptions to {\tt login_failure_msgs} \pxrefvarnott{login_non_failure_msgs}.

\indpredefvar{login_prompts}{set[string]}
Strings that when seen in a \xrefanalyzer{login} dialog indicate a
prompt for a username \pxrefvarnott{login_prompts}.

\indpredefvar{login_success_msgs}{set[string]}
Strings that when seen in a \xrefanalyzer{login} dialog indicate that
the user successfully authenticated \pxrefvarnott{login_success_msgs}.

\indpredefvar{login_timeouts}{set[string]}
Strings that when seen in a \xrefanalyzer{login} dialog indicate that
the login server timed out the user's attempt to authenticate
\pxrefvarnott{login_timeouts}.

\index{timer expiration}
\index{expiration!timer}
\indpredefvar{max_timer_expires}{count}
Sets an upper limit on \link{how many pending timers Bro will expire}{timer-invocation} per newly arriving packet.  If set to 0, then Bro expires all
pending timers whose time has come or past.  This variable trades off
timer accuracy and memory requirements (because a number of Bro's internal
timers relate to expiring state) with potentially bursty load spikes due
to a lot of timers expiring at the same time, which can trigger the
\link{watchdog}{watchdog}, if active.

\indpredefvar{restrict_filter}{string}
Restricts what packets Bro's filter should record \pxref{restrict-filter}.

\indpredefvar{skip_authentication}{set[string]}
Strings that when seen in a \xrefanalyzer{login} dialog indicate that
the analyzer should skip attempting to follow the authentication dialog
\pxrefvarnott{skip_authentication}.

\end{description}
\index{predefined variables|)}

\section{Predefined Functions}

Bro provides a number of built-in functions:

\index{predefined functions|(}

\begin{description}
\index{connection!testing for existence}
\indpredeffunc{active_connection}{(id: conn_id): bool}
Returns true if the given connection identifier (originator/responder
addresses and ports) corresponds to a currently-active connection.

\index{files!testing if open}
\indpredeffunc{active_file}{(f: file): bool}
Returns true if the given {\tt file} is open.

\indpredeffunc{add_interface}{(iold: string, inew: string): string}
Used to refine the initialization of \xrefglobal{interfaces}.  Meant
for internal use, and as an example of refinement \pxref{refinement}.

\indpredeffunc{add_tcpdump_filter}{(fold: string, fnew: string): string}
Used to refine the initializations of \xrefglobal{capture_filter} 
and \xrefglobal{restrict_filter}.  Meant for internal use, and as an
example of refinement \pxref{refinement}.

\index{logging!control of}
\indpredeffuncnolab{log_hook}{(msg: string): bool}
If you define this function, then Bro will call it with each string
it is about to log.  The function should return true if Bro should
go ahead and log the message, false otherwise.  See \xreffuncnott{log_hook}
for further discussion and an example.

\index{strings!length}
\index{length!of strings}
\index{strlen@\emph{strlen}}
\indpredeffunc{byte_len}{(s: string): count}
Returns the number of bytes in the given string.  This includes
any embedded NULs, and also a trailing NUL, if any (which is why the
function isn't called \emph{strlen}; to remind the user that Bro strings
can include NULs).

\index{strings!concatenation}
\index{concatenation of strings}
\indpredeffunc{cat}{(args: any): string}
Returns the concatenation of the string representation of its arguments,
which can be of any type.  For example, {\tt cat("foo", 3, T)} returns
{\tt "foo3T"}.

\index{strings!cleaned up}
\indpredeffunc{clean}{(s: string): string}
Returns a cleaned up version of {\tt s}, meaning that:
\index{NUL}
\index{DEL}
\index{delete character}
\begin{itemize}
\item embedded NULs become the text ``\verb+\0+''
\item embedded DELs (delete characters) become the text ``\verb+^?+''
\item ASCII ``control'' characters with code $\le 26$ become the
	text ``\verb+^+\emph{Letter}'', where \emph{Letter} is
	the corresponding (upper case) control character; for example,
	ASCII~2 becomes ``\verb+^B+''
\item ASCII ``control'' characters with codes between~26 and~32 (non-inclusive)
	become the text ``\verb+\x+\emph{hex-code}''; for example,
	ASCII~31 becomes ``\verb+\x1f+''
\item if the string does not yet have a trailing NUL, one is added.
\end{itemize}

\indpredeffunc{close}{(f: file): bool}
Flushes any buffered output for the given file and closes it.
Returns true if the file was open, false if already closed or
never opened.

\indpredeffunc{connection_record}{(id: conn_id): connection}
Returns the \xreftype{connection} record corresponding to the\indfatal{non-existing connection}\indexmsg{connection id is not a known connection}
given connection identifier.  \note{ If the connection does not exist,
then exits with a fatal run-time error. }

\deficiency{ If Bro had an exception mechanism, then we could avoid
the fatal run-time error, and likewise could get rid of
\xreffunc{active_connection}. }

\index{strstr@\emph{strstr}}
\indpredeffunc{contains_string}{(big: string, little: string): bool}
Returns true if the string {\tt little} occurs somewhere within
{\tt big}, false otherwise.

\index{time!clock}
\index{clock time}
\indpredeffunc{current_time}{(): time}
Returns the current clock time.  You will usually instead want to
use \xreffunc{network_time}.

\indpredeffunc{discarder_check_icmp}{(i: ip_hdr, ih: icmp_hdr): bool}
Not documented.
\indpredeffunc{discarder_check_ip}{(i: ip_hdr): bool}
Not documented.
\indpredeffunc{discarder_check_tcp}{(i: ip_hdr, t: tcp_hdr, d: string): bool}
Not documented.
\indpredeffunc{discarder_check_udp}{(i: ip_hdr, u: udp_hdr, d: string): bool}
Not documented.

\index{line editing}
\index{editing}
\index{backspace character}
\index{DEL}
\index{BS}
\indpredeffunc{edit}{(s: string, edit_char: string): string}
Returns a version of {\tt s} assuming that {\tt edit_char} is the ``backspace''
character (usually \verb+"\x08"+ for backspace or \verb+"\x7f"+ for DEL).
For example, {\tt edit("hello there", "e")} returns {\tt "llo t"}.

\indruntime{bad fmt editing character}
\indexmsg{not exactly one edit character}
{\tt edit_char} must be a string of exactly one character, or Bro generates
a run-time error and uses the first character in the string.

\deficiency{ To do a proper job, {\tt edit} should also know about 
delete-word and delete-line editing; and it would be very convenient
if it could do multiple types of edits all in one shot, rather than
requiring separate invocations. }

\indpredeffunc{exit}{(): int}
Exits Bro with a status of 0.

\deficiency{ This function should probably allow you to specify
the exit status. }

\note{ If you invoke this function, then the usual cleanup
functions \xrefevent{net_done} and \xrefevent{bro_done} are \emph{not} invoked.
There probably should be an additional ``{\tt shutdown}'' function
that provides for cleaner termination.
}

\index{fflush@\emph{fflush}}
\indpredeffunc{flush_all}{(): bool}
Flushes all open files to disk.

\index{formatting text}
\index{text!formatting}
\index{string!formatting}
\index{printf@\emph{printf}}
\index{sprintf@\emph{sprintf}}
\index{width!of formatted strings}
\index{precision!of formatted strings}
\index{format!width}
\index{format!precision}
\indpredeffunc{fmt}{(args: any): string}
Performs \emph{sprintf}-style formatting.  The first argument gives
the format specifier to which the remaining arguments are formatted,
left-to-right.  As with \emph{sprintf}, the format for each argument
is introduced using ``\percent'', and
formats beginning with a positive integer $m$ specify
that the given field should have a width of $m$ characters.  Fields
with fewer characters are right-padded with blanks up to this width.

\indruntime{bad fmt precision}
\indexmsg{precision specified for non-floating point format}
\indruntime{bad fmt field width}
\indexmsg{ridiculous field width or precision}
A format specifier of ``{\tt .}$n$'' (coming after $m$, if present)
instructs {\tt fmt} to use a precision of $n$ digits.  You can
only specify a precision for the {\tt e}, {\tt f} or {\tt g}
formats.
({\tt fmt} generates a run-time error if either $m$ or $n$ exceeds~127.)

\indruntime{bad fmt format specifier}
\indexmsg{bad format}
The different format specifiers are:

\begin{description}
\index{\% format@{\tt \protect \percent}  format}
\index{format!\%@{\tt \protect \percent}}
\item[\percent]
A literal percent-sign character.

\indruntime{bad fmt date argument}
\indexmsg{bad type for Date format}
\index{bad time!format conversion error@{\tt bad time}!format conversion error}
\index{strftime@\emph{strftime}}
\indformat{D} Format as a date.  Valid only for values of type {\tt time}.

The exact format is
\emph{yy}--\emph{mm}--\emph{dd}--\emph{hh}:\emph{mm}:\emph{ss}
for the local time zone, per \emph{strftime}.

\indruntime{bad fmt integer argument}
\indexmsg{bad type for integer format}
\index{little endian}
\index{big endian}
\index{endian issues}
\index{host order (vs. network order)}
\index{network order (vs. host order)}
\index{integers!network vs. host order}
\indformat{d} Format as an integer.  Valid for types {\tt bool},
{\tt count}, {\tt int}, {\tt port}, {\tt addr}, and {\tt net},
with the latter three being converted from network order to
host order prior to formatting.  {\tt bool} values of true format
as the number~1, and false as~0.

\indruntime{bad fmt floating-point argument}
\indexmsg{bad type for floating-point format}
\indformatnoitem{e}
\indformatnoitem{f}
\indformatnoitem{g}
\item[e, f, g] Format as a floating point value.
Valid for types {\tt double}, {\tt time}, and {\tt interval}.
The formatting is the same as for \emph{printf}, including
the field width $m$ and precision $n$.

\end{description}

Given no arguments, {\tt fmt} returns an empty string.

Given a non-string first argument, {\tt fmt} returns the concatenation of
all its arguments, per \xreffunc{cat}.

\indruntime{wrong number of fmt arguments}
\indexmsg{wrong number of \emph{fmt} arguments}
\indexmsg{too many arguments for format}
\indexmsg{too few arguments for format}
Finally, given the wrong number of additional arguments for the given
format specifier, {\tt fmt} generates a run-time error.

\index{authentication dialog}
\index{state!of a Telnet/Rlogin session}
\index{Telnet!session state}
\index{Rlogin!session state}
\index{login session!state}
\indpredeffunc{get_login_state}{(c: conn_id): count}
Returns the state of the given login (Telnet or Rlogin) connection,
one of:

\begin{description}
\itemindtt{LOGIN_STATE_AUTHENTICATE}{state of login connection}
The connection is in its initial authentication dialog.

\itemindtt{LOGIN_STATE_LOGGED_IN}{state of login connection}
The analyzer believes the user has successfully authenticated.

\itemindtt{LOGIN_STATE_SKIP}{state of login connection}
The analyzer has skipped any further processing of the connection.

\itemindtt{LOGIN_STATE_CONFUSED}{state of login connection}
The analyzer has concluded that it does not correctly know the
state of the connection, and/or the username associated with it
\pxref{login-confused}.

\end{description}

\indruntime{not a login connection}
\indexmsg{connection id is not a known login connection}
or a run-time error and a value of {\tt LOGIN_STATE_AUTHENTICATE}
if the connection is not a login connection.

\index{sequence numbers!connection originator}
\index{connection!sequence numbers}
\indruntime{not a TCP connection}
\indexmsg{is not a TCP connection}
\indpredeffunc{get_orig_seq}{(c: conn_id): count}
Returns the highest sequence number sent by a connection's originator,
or~0 if there's no such TCP connection.  Sequence numbers are absolute
(i.e., they reflect the values seen directly in packet headers; they are
not relative to the beginning of the connection).

\index{sequence numbers!connection responder}
\index{connection!sequence numbers}
\indruntime{not a TCP connection}
\indexmsg{is not a TCP connection}
\indpredeffunc{get_resp_seq}{(c: conn_id): count}
Returns the highest sequence number sent by a connection's responder,
or~0 if there's no such TCP connection.

\index{environment!accessing}
\indpredeffunc{getenv}{(var: string): string}
Looks up the given environment variable and returns its value,
or an empty string if it is not defined.

\index{ports!TCP vs. UDP}
\index{TCP vs. UDP ports}
\indpredeffunc{is_tcp_port}{(p: port): bool}
Returns true if the given {\tt port} value corresponds to a TCP port,
false otherwise (i.e., it belongs to a UDP port).

\index{length!of table or set}
\index{size!of table or set}
\index{number of elements!in table or set}
\index{table size}
\index{set size}
\indruntime{wrong number of length arguments}
\indruntime{bad length argument (not a table or set)}
\indexmsg{length() takes exactly one argument}
\indexmsg{length() requires a table/set argument}
\indpredeffunc{length}{(args: any): count}
Returns the number of elements in its argument, which must be of
type {\tt table} or {\tt set}.  If not exactly one argument is
specified, or if the argument is not a table or a set, then generates
a run-time message and returns~0.

\index{union type!need for}
\index{any type!replacing with union type}
\deficiency{ If Bro had a union type, then we could get rid of the
magic ``{\tt args: any}'' specification and catch parameter mismatches
at compile-time instead of run-time. }

\index{log file}
\index{name!of log file}
\indpredeffunc{log_file_name}{(tag: string): string}
Returns a name for a log file (such as \xreflog{weird} or \xreflog{red})
in a standard form.  The form depends on whether \xrefenv{BRO_ID} is set.
If so, then the format is ``\verb+<+\emph{tag}\verb+>.<$BRO_ID>+''.  Otherwise,
it is simply {\tt tag}.

\index{masking}
\index{address masking}
\index{CIDR}
\index{subnets}
\indruntime{bad address mask}
\indexmsg{bad second argument to mask_addr()}
\indpredeffunc{mask_addr}{(a: addr, top_bits_to_keep: count): addr}
Returns the address {\tt a} masked down to the number of upper bits
indicated by {\tt top_bits_to_keep}, which must be greater than~0 and
less than~33.  For example, {\tt mask_addr(1.2.3.4, 18)} returns
{\tt 1.2.0.0}, and {\tt mask_addr(1.2.255.4, 18)} returns
{\tt 1.2.192.0}.

Compare with \xreffunc{to_net}.

\index{maximum}
\indpredeffunc{max_count}{(a: count, b: count): count}
\indttnotext{count}{maximum}
Returns the larger of {\tt a} or {\tt b}.

\indpredeffunc{max_double}{(a: double, b: double): double}
\indttnotext{double}{maximum}
Returns the larger of {\tt a} or {\tt b}.

\indpredeffunc{max_interval}{(a: interval, b: interval): interval}
\indttnotext{interval}{maximum}
Returns the larger of {\tt a} or {\tt b}.

\index{polymorphic functions!need for}
\deficiency{ If Bro supported polymorphic functions, then this
function could be merged with its predecessors, gaining simplicity and
clarity. }

\index{minimum}
\indpredeffunc{min_count}{(a: count, b: count): count}
\indttnotext{count}{minimum}
Returns the smaller of {\tt a} or {\tt b}.

\indpredeffunc{min_double}{(a: double, b: double): double}
\indttnotext{double}{minimum}
Returns the smaller of {\tt a} or {\tt b}.

\indpredeffunc{min_interval}{(a: interval, b: interval): interval}
\indttnotext{interval}{minimum}
Returns the smaller of {\tt a} or {\tt b}.

\index{polymorphic functions!need for}
\deficiency{ If Bro supported polymorphic functions, then this
function could be merged with its predecessors, gaining simplicity and
clarity. }

\indruntime{mkdir failure}
\indexmsg{cannot create directory}
\index{directories!creating}
\index{creating directories}
\indpredeffunc{mkdir}{(f: string): bool}
Creates a directory with the given name, if it does not already exist.
Returns true upon success, false (with a run-time message) if
unsuccessful.

\index{time!clock}
\index{time!packet}
\index{clock time}
\index{packets!time}
\index{scripting!general}
\index{general scripting}
\indpredeffunc{network_time}{(): time}
Returns the timestamp of the most recently read packet, whether read
from a live network interface or from a save file \pxref{play-back}.
Compare against \xreffunc{current_time}.  In general, you should use
{\tt network_time} unless you're using Bro for non-networking uses
(such as general scripting;
not particularly recommended), because otherwise your script may
behave very differently on live traffic versus played-back traffic
from a save file.

\index{files!opening}
\index{opening a file}
\indpredeffunc{open}{(f: string): file}
Opens the given filename for write access.  Creates the file if it
does not already exist.  Generates a run-time error if the file
cannot be opened/created.

\index{files!appending}
\index{files!opening}
\index{appending to a file}
\index{opening a file}
\indpredeffunc{open_for_append}{(f: string): file}
Opens the given filename for append access.  Creates the file if it
does not already exist.  Generates a run-time error if the file
cannot be opened/created.

\indpredeffunc{open_log_file}{(tag: string): file}
Opens a log file associated with the given tag, using a filename
format as returned by \xreffunc{log_file_name}.

\index{record!{\tt ftp_port}}
\indpredeffunc{parse_ftp_pasv}{(s: string): ftp_port}
Parses the server's reply to an FTP {\tt PASV} command to extract the
IP address and port number indicated by the server.  The values
are returned in an \indtt{ftp_port}{record} record, which has three
fields: {\tt h}, the address ($h$ is mnemonic for \emph{host});
{\tt p}, the (TCP) port; and {\tt valid}, a boolean that is true
if the server's reply was in the required format, false if not,
or if any of the individual values (or the indicated port number)
are out of range.

\index{record!{\tt ftp_port}}
\indpredeffunc{parse_ftp_port}{(s: string): ftp_port}
Parses the argument included in a client's FTP {\tt PORT} request to
extract the IP address and port number indicated by the server.  The values
are returned in an \indtt{ftp_port}{record} record, which has three fields, as
indicated in the discussion of \xreffunc{parse_ftp_pasv}.

\index{live traffic}
\index{recorded traffic}
\index{traffic!live vs. recorded}
\index{analysis!on-line}
\index{on-line analysis}
\index{analysis!off-line}
\index{off-line analysis}
\indpredeffunc{reading_live_traffic}{(): bool}
Returns true if Bro was invoked to read live network traffic (from
one or more network interfaces, per \xref{network-interfaces}), false
if it's reading from save files being played back \pxref{play-back}.

\note{ This function returns true even after Bro has stopped reading
network traffic, for example due to receiving a termination signal
\pxref{signal-handling}. }

\begin{table}
\label{tbl:contents-dir}
\begin{center}
\begin{tabular}{|l|l|} 
\hline
{\bf Direction} & {\bf Meaning} \\
\hline
\hline
\indtt{CONTENTS_NONE}{direction} & Stop recording the connection's contents. \\
\hline
\indtt{CONTENTS_ORIG}{direction} & Record the data sent by the connection originator (often the client). \\
\hline
\indtt{CONTENTS_RESP}{direction} & Record the data sent by the connection responder (often the server). \\
\hline
\indtt{CONTENTS_BOTH}{direction} & Record the data sent in both directions. \\
\hline
\end{tabular}
\end{center}
%HEVEA \caption{ Different types of directions for \xreffunc{set_contents_file}. }
%BEGIN LATEX
\caption[Different types of directions for {\tt set_contents_file}]{ Different types of directions for \xreffunc{set_contents_file}. }
%END LATEX
\end{table}

\indpredeffunc{set_buf}{(f: file, buffered: bool)}
Specifies that writing to the given file should either be fully
buffered (if {\tt buffered} is true), or line-buffered (if false).
Does not return a value.

\indpredeffunc{set_contents_file}{(c: conn_id, direction: count, f: file): bool}
Specifies that the traffic stream of the given connection in the given
direction should be recorded to the given file.  {\tt direction} is one of
the values given in Table~\ref{tbl:contents-dir}.

\note{ {\tt CONTENTS_BOTH}
results in the two directions being intermixed in the file, in the order
the data was seen by Bro. }

\note{ The data recorded to the file reflects the byte stream, not
the contents of individual packets.  Reordering and duplicates are
removed.  If any data is missing, the recording stops at the missing
data; see \xrefevent{ack_above_hole} for how this can happen. }

\deficiency{ Bro begins recording the traffic stream starting with
new traffic it sees.  Experience has shown it would be highly handy if
Bro could record the entire connection to the file, including previously
seen traffic.  In principle, this is possible if Bro is recording the
traffic to a save file \pxref{write-file}, which a separate utility program
could then read to extract the stream. }

Returns true upon success, false upon an error.

\index{authentication dialog}
\index{state!of a Telnet/Rlogin session}
\index{Telnet!session state}
\index{Rlogin!session state}
\index{login session!state}
\indpredeffunc{set_login_state}{(c: conn_id, new_state: count): bool}
Manually sets the state of the given login (Telnet or Rlogin) connection
to {\tt new_state}, which should be one of the values described
in \xreffunc{get_login_state}.

\indruntime{not a login connection}
\indexmsg{connection id is not a known login connection}
Generates a run-time error and returns false
if the connection is not a login connection.  Otherwise, returns true.

\index{packets!recording}
\index{recording packets}
\index{save file!control over what's recorded}
\index{write file!control over what's recorded}
\index{trace file!control over what's recorded}
\indpredeffunc{set_record_packets}{(c: conn_id, do_record: bool): bool}
Controls whether Bro should or should not record the packets corresponding
to the given connection to the save file \pxref{write-file}, if any.

Returns true upon success, false upon an error.

\index{avoiding processing}
\index{processing!avoiding}
\index{shedding load}
\index{load!shedding}
\indpredeffunc{skip_further_processing}{(c: conn_id): bool}
Informs bro that it should skip any further processing of the contents
of the given connection.  In particular, Bro will refrain from reassembling
the TCP byte stream and from generating events relating to any analyzers
that have been processing the connection.  Bro will still generate
connection-oriented events such as \xrefevent{connection_finished}.

This function provides a way to shed some load in order to reduce
the computational burden placed on the monitor.

Returns true upon success, false upon an error.

\index{string!extraction}
\index{substrings}
\indpredeffunc{sub_bytes}{(s: string, start: count, n: count): string}
Returns a copy of {\tt n} bytes from the given string, starting at position
{\tt start}.  The beginning of a string corresponds to position~1.

If {\tt start} is~0 or exceeds the length of the string, returns
an empty string.

If the string does not have {\tt n} characters from {\tt start} to
its end, then returns the characters from {\tt start} to the end.

\index{sh@\emph{sh}}
\index{command shell}
\index{Bourne shell}
\index{shell escape}
\index{scripts!running}
\index{executables!running}
\index{running outside scripts or executables}
\indpredeffunc{system}{(s: string): int}
Runs the given string as a \emph{sh} command (via C's \emph{system} call).

\index{stdout@\emph{stdout}}
\index{stderr@\emph{stderr}}
\note{ The command is run in the \emph{background} with \emph{stdout}
redirected to \emph{stderr}. }

Returns the return value from the \emph{system} call.  \note{ This
corresponds to the status of backgrounding the given command, \emph{not}
to the exit status of the command itself. }  A value of~127 corresponds
to a failure to execute \emph{sh}, and~-1 to an internal system failure.

\index{isascii@\emph{isascii}}
\index{isupper@\emph{isupper}}
\index{tolower@\emph{tolower}}
\indpredeffunc{to_lower}{(s: string): string}
Returns a copy of the given string with the uppercase letters
(as indicated by \emph{isascii} and \emph{isupper})
folded to lowercase (via \emph{tolower}).

\index{masking}
\index{address masking}
\index{CIDR}
\index{subnets}
\index{prefixes!network}
\index{network prefixes}
\indpredeffunc{to_net}{(a: addr): net}
Returns the network prefix historically associated with the given
address.  That is, if {\tt a}'s leading octet is less than~128,
then returns
\verb+<+\emph{a}\verb+>+\emph{/8};
if between~128 and~191, inclusive, then
\verb+<+\emph{a}\verb+>+\emph{/16};
if between 192~and 223, then
\verb+<+\emph{a}\verb+>+\emph{/24};
and, otherwise,
\verb+<+\emph{a}\verb+>+\emph{/32}.
See the discussion of the \xreftype{net} type for more about network prefixes.

\indruntime{converting an IPv6 address to net}
\indexmsg{conversion of non-IPv4 address to net}
Generates a run-time error and returns {\tt 0.0.0.0} 
if the address is IPv6.

\note{ Such network prefixes have become obsolete with the advent of CIDR;
still, for some sites they prove useful because they correspond to existing
address allocations. }

Compare with \xreffunc{mask_addr}.

\index{isascii@\emph{isascii}}
\index{islower@\emph{islower}}
\index{toupper@\emph{toupper}}
\indpredeffunc{to_upper}{(s: string): string}
Returns a copy of the given string with the lowercase letters
(as indicated by \emph{isascii} and \emph{islower})
folded to uppercase (via \emph{toupper}).

\end{description}

\subsection{Run-time errors for non-existing connections}
\index{connection!non-existing}

\indruntime{no such connection}
\indexmsg{connection id is not a known connection}
Note that for all functions that take a {\tt conn_id} argument
except \xreffunc{active_connection}, Bro generates a run-time
error and returns false if the given connection does not exist.

\index{NULs!disallowed in certain function calls}
\label{NULs-run-time}
\index{NULs!termination}
\index{strings!termination with NULs}
\index{NULs!allowed in strings}
\subsection{Run-time errors for strings with NULs}
While Bro allows NULs embedded within strings \pxref{NULs-allowed-in-strings},
for many of the predefined functions, their presence spells trouble,
particularly when the string is being passed to a C~run-time function.
The same holds for strings that are \emph{not} NUL-terminated.  Because
Bro string constants and values returned by Bro functions that construct
strings such as {\tt fmt} and {\tt cat} are all NUL-terminated, such strings
will not ordinarily arise; but their presence could indicate an attacker
attempting to manipulate either a TCP endpoint, or the monitor itself,
into misinterpreting a string they're sending.

\index{string-with-NUL@\verb+"<string-with-NUL>"+ error value}
\indruntime{embedded NUL}
\indruntime{NULs!terminator missing}
\indexmsg{string without NUL terminator}
\indexmsg{string with embedded NUL}
In general, any of the functions above that are passed a string argument
will check for the presence of an embedded NUL or the lack of a terminating
NUL.  If either occurs, they generate a run-time message, and the
string is transformed into the value
\verb+"<string-with-NUL>"+.

There are three exceptions: \xreffunc{clean}, \xreffunc{byte_len}, and
\xreffunc{sub_bytes}.  These functions do not complain about embedded
NULs or lack of trailing NULs.

\subsection{Functions for manipulating strings}
\label{predefineds-string}
\fixme{Missing}

\subsection{Functions for manipulating time}
\label{predefineds-time}
\fixme{Missing}

\index{predefined functions|)}

%HEVEA\cutend

