This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.
Script -- Click element; script a Click router configuration
Ports: normally 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. Many
instructions come in two forms, as in
writeq. The non-
q forms perform
substitutions on the text, but do not remove any quotes from the result, while
q forms perform substitutions and then remove a layer of quoting. For
example, assuming the 'c.count' read handler returns 0:
set x $(c.count) print $x => 0 set x "$(c.count)" print $x => "0" setq x "$(c.count)" print $x => 0
setVAR TEXT', '
initVAR TEXT', '
exportVAR [TEXT]', '
init, but also makes the value of script variable VAR available via a read handler named VAR.
printn[>FILE | >>FILE] [TEXT | HANDLER]'
readHANDLER [ARGS]', '
writeHANDLER [ARGS]', '
goto exit [CONDITION]' and '
goto end [CONDITION]' end execution of the script, like '
exit' and '
end' respectively. '
goto loop [CONDITION]' transfers control to the first instruction, like '
goto error [CONDITION]' ends execution of the script with an error, like '
goto stop [CONDITION]' ends execution of the script and asks the driver to stop, like '
end' causes the script to be reinstalled as a signal handler. In packet scripts, '
end' emits the packet on output 0. An implicit '
end' is executed if execution falls off the end of a script.
exit' will not reinstall the script as a signal handler. In packet scripts, '
exit' will drop the packet.
end', and additionally ask the driver to stop. (A TYPE DRIVER Script, or DriverManager element, can intercept this request.)
runhandler. In packet scripts, VALUE is the port on which the packet should be emitted.
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:
runhandler. Passive scripts can help build complex handlers from existing simple ones; for example, here's a passive script whose
s.runread 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
$argsvariable equals the
$2, etc. equal the first, second, etc. space-separated portions of
$#equals the number of space-separated arguments.
$inputvariable equals the packet input port. The script's return value is used as the output port number.
$0variable equals the handler's name, and the
$writevariable is "true" if the handler was called as a write handler. For example, consider: s :: Script(TYPE PROXY, goto nota $(ne $0 a), returnq "you called 'a'", label nota, goto notb $(ne $0 b), returnq "you called 'b'", label notb, error bad handler); Calling the read handler "s.a" will return "you called 'a'", calling "s.b" will return "you called 'b'", and anything else will produce a "bad handler" error.
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
$(...)' 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
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);
wait). A numeric argument will step past that many blocking instructions.
return' instruction, then the handler returns with that value.
add 10 5 2' returns "
17". (At user level, the arithmetic and comparison operators can parse floating-point numbers as well as integers.)
sub 10 5 2' returns "
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.
mod 7 3' returns "
mod' expects integer operands and returns the integer modulus. At user level, '
rem' implements floating-point remainder; in the kernel, it is the same as '
eq 10 0xA' returns "
true", and '
le 9 8' returns "
false". If either parameter cannot be interpreted as a number, performs a string comparison in bytewise lexicographic order. For example, '
eq 10x 10x' returns "
in foo bar foo' returns "
sprintf "%05x" 127' returns "
read abcdef' returns "
kill; it expands to the driver's process ID.
Generated by 'click-elem2man' from '../elements/standard/script.hh:9' on 12/Jul/2011.