Script Element Documentation

Script -- Click element; script a Click router configuration

Script(INSTRUCTIONS...)

Ports: none
Package: standard (core)

The Script element implements a simple scripting language useful for controlling Click configurations. Scripts can set variables, call handlers, wait for prodding from other elements, and stop the router.

Each configuration argument is an instruction (except for optional keywords; see below). Script generally processes these instructions sequentially.

In all cases, text arguments are subject to substitutions; see below.

'set VAR TEXT'

Sets the script variable $VAR to TEXT.

'init VAR TEXT'

Initializes the script variable $VAR to TEXT. This assignment happens exactly once, when the Script element is initialized; later the instruction has no effect.

'print [>FILE | >>FILE] [TEXT | HANDLER]'

Prints text, or the result of calling a read handler, followed by a newline. At user level, the text is written to the standard output, except that if the argument begins with > or >>, then the text is written or appended to the specified FILE. In the kernel, the text is written to the system log. If print's argument starts with a letter, '@', or '_', then it is treated as a read handler. Otherwise, it is treated as quoted text; Script prints the unquoted version. For example, assuming the 'c.count' read handler returns "0": print c.count => 0 print "c.count" => c.count print '"c.count"' => "c.count" set x c.count print $x => c.count print $($x) => 0

'read HANDLER [ARG...]'

Call a read handler and print the handler name and result to standard error. (In the kernel, the result is printed to the system log.) For example, the configuration 'Idle -> c::Counter -> Idle; Script(read c.count)' would print print this to standard error: c.count: 0 Contrast the 'print' instruction.

'write HANDLER [ARG...]'

Call a write handler. The handler's return status is available in following instructions as the '$?' variable.

'readq HANDLER [ARG...]', 'writeq HANDLER [ARG...]'

Same as read and write, but removes one layer of quoting from the ARGs before calling the handler.

'pause [COUNT]'

Block until the Script element's 'step' handler is called COUNT times. COUNT defaults to 1.

'wait TIME'

Wait for TIME seconds, or until a step, whichever comes first; then go to the next instruction. TIME has microsecond precision.

'label LABEL'

Defines a label named LABEL.

'goto LABEL [CONDITION]'

Transfers control to the named label. Script elements detect loops; if an element's script appears to be looping (it executes 1000 goto instructions without blocking), the script is disabled. If CONDITION is supplied, then the branch executes only when CONDITION is true. As a special case, 'goto exit [CONDITION]' or 'goto end [CONDITION]' ends execution of the script, much like an 'exit' or 'end' instruction.

'loop'

Transfers control to the first instruction.

'return [VALUE]'

End execution of this script, returning VALUE. This instruction is most useful for passive scripts; VALUE will be returned as the value of the run handler.

'exit', 'end'

End execution of this script. For signal scripts, the 'exit' instruction does not reinstall the script, whereas the 'end' instruction does.

Scripts come in several types, including active scripts, which start running as soon as the configuration is loaded; passive scripts, which run only when prodded; signal scripts, which run in response to a signal; and driver scripts, which are active scripts that also control when the driver stops. The optional TYPE keyword argument is used to select a script type. The types are:

ACTIVE

An active script starts running as soon as the router is initialized. This is the default.

PASSIVE

A passive script runs in response to a handler, namely the run handler. Passive scripts can help build complex handlers from existing simple ones; for example, here's a passive script whose s.run read handler returns the sum of two Counter handlers. ... c1 :: Counter ... c2 :: Counter ... s :: Script(TYPE PASSIVE, return $(add $(c1.count) $(c2.count))) Within the script, the run handler's arguments, if any, are available via the $args variable. The first, second, and so forth space-separated portions of $args are available via the $1, $2, ... variables.

DRIVER

A driver script manages the Click driver's stop events. See DriverManager for more information.

SIGNAL SIGNO...

User-level only: A signal script runs in response to the signal(s) specified by the SIGNO argument(s). Each SIGNO can be an integer or a signal name, such as INT or HUP. Soon after the driver receives a named signal, this script will run. The signal handler is automatically blocked until the script runs. The signal script will be reinstalled atomically as long as the script completes without blocking. If it blocks, however, the signal script will not be installed from the blocking point until the script completes. If multiple Script elements select the same signal, all the scripts will run.

Text in most Script instructions undergoes variable substitution. References to script variables, such as '$x', are replaced by the variable text. Additionally, the form '$(HANDLER [ARG...])' can be used to interpolate a read handler's value. Variable and handler references can be nested inside a '$(...)' block. For example, the following script will print 0, 1, 2, 3, and 4 on separate lines, then exit. Note the use of Script's arithmetic handlers.

   s :: Script(set x 0,
               label begin_loop,
               print $x,
               set x $(s.add $x 1),
               goto begin_loop $(s.lt $x 5),
               stop);

This can be further shortened since local handler references do not require the element name. Thus, "$(s.add ...)" can be written "$(add ...)", as below.

   Script(set x 0,
          label begin_loop,
          print $x,
          set x $(add $x 1),
          goto begin_loop $(lt $x 5),
          stop);

step (write-only)

Advance the instruction pointer past the current blocking instruction (pause or wait). A numeric argument will step past that many blocking instructions.

goto (write-only)

Move the instruction pointer to the specified label.

run (read/write)

Run the script. If the script ends with a 'return' instruction, then the handler returns with that value.

add (read with parameters)

Useful for arithmetic. Adds a space-separated list of integers; for example, 'add 10 5 2' returns "17". (At user level, the arithmetic and comparison operators can parse floating-point numbers as well as integers.)

sub (read with parameters)

Subtracts a space-separated list of numbers; for example, 'sub 10 5 2' returns "3".

mul, div, idiv (read with parameters)

Multiplies or divides a space-separated list of numbers and returns the result. At user level, the 'idiv' handler truncates its result to an integer and returns that, whereas the 'div' handler returns a floating-point number; in the kernel, 'idiv' and 'div' both perform integer division.

eq, ne, lt, gt, le, ge (read with parameters)

Compares two parameters and return the result. For example, 'eq 10 0xA' returns "true", but 'le 9 8' returns "false". If either parameter cannot be interpreted as a number, performs a string comparison. For example, 'eq 10x 10x' return "true".

not (read with parameters)

Useful for true/false operations. Parses its parameter as a Boolean and returns its negation.

sprintf (read with parameters)

Parses its parameters as a space-separated list of arguments. The first argument is a format string; the remaining arguments are formatted accordingly. For example, 'sprintf "%05x" 127' returns "0007F".

DriverManager

Generated by 'click-elem2man' from '../elements/standard/script.hh' on 18/Jul/2007.