N Code Functions |
N Code FunctionsAlertThe alert buitin allows .nfr code to submit an alert to the alert daemon. Any alerts which can be generated by the engine, or other components, can be signaled by using the alert builtin function. The first parameter to the alert builtin function is the facility. This can be quickly described as the `originator' or reason for the alert. The second parameter describes the alert string which is to processed by the alert daemon, and any additional parameters are data for the alert string. The first two parameters to the alert builtin are special values Generated by the resouce compiler, rc. To make these values available to the engine, a special scope, alert, exists. To reference values from that scope, a fully qualified name can be used. For example, to reference the `NFR_ERR_UNDEFINED' error, the variable name `alert:NFR_ERR_UNDEFINED' can be used. Example:
3", "string 4" ); } DisplayThe display builtin allows .nfr code to dump detailed information About the current packet. This builtin is intended to be helpful in Debugging .nfr code. It accepts multiple parameters. The last string Parameter is used as a label for the display information. If the last integer in the parameter list is nonzero, it sets the verbose option. The verbose option can also be set by using a string "verbose", or "hex", because using the verbose option will display the packet contents in hex. The display builtin prints its output onto the active connection that loaded the procedure. The control command can be used to request the 'read'ing of the example code which follows. If the connection via the control command remains intact, the display command will dump its output on that socket. Example:The following example is a filter, using a trigger to be called on every packet received. Once called, the packet's contents are displayed.
EchoThe echo builtin echos all of the arguments, displaying the associated value depending on the type of the value. Like the display builtin, echo is intended primarily as a debuggin aid. Here are the values that get displayed:
The echo builtin prints its output onto the active connection which loaded the procedure. The control command can be used to request the 'read'ing of the example code which follows. If the connection via the control command remains intact, the display command will dump its output on that socket. Example:
The first echo will only send a newline to the output stream. The second will display the value of the integer expression 1, which will appear as '1'. The third echo will display the value of the list, which will appear as '[1,2,3,4]' errnoThe bltin errno returns the integer value associated with an error. The current errors returned during .nfr code execution are:
Example:
If the function above is run, and the variable named 'variableWhichDoesNotExist' actually does not exist, then the echo will display '7'. recorderThe recorder builtin returns a new recorder type. Parameters to the builtin describe how to build the new recorder. NOTE: The parameters are likely to change. At some point the only parameter will be the name of a config file to read to describe how to construct the recorder. Currently, the recorder builtin accepts either two or three parameters. The first parameter is a string type, whose value is some command which will get run to become the backend. The command is parsed by the engine; common shell syntax will not work (for example redirecting the output, or using file name globbing or pipes, or trying to send the command into the background via `&'). The command is run in the background (via fork/exec), and is managed by the nfrd engine. The second parameter of the recorder builtin is the name of some Schema to associate with the recorder. The schema describes what data the backend expects. It lists the number of values the backend expects and the types of each values. To send data to a backend,.nfr code uses the RECORD statement. A RECORD statement lists all the values to send to a recorder, and the number and type of values must match with the number and types of values described in the schema description (.sch file). When these are mismatched, the engine will send an alert, and will Not send the data from the RECORD statement to the backend. Example:
This example describes a very simple recorder, the unix cat command. When the record statement is executed, the values associated with the variables `first' and `second' are sent to firstRecorder. Example:
This example sends data from port 80, any characters between a GET and a space, to the file ../recorder/save. Expert UsageTypical usage of the recorder builtin uses two parameters, the command, and the schema. It is possible to create a recorder with only one parameter, leaving the schema unnamed. However, use caution because every record statement must then describe the schema name to be used. This is done by using a list as the value to the record statement and having the first parameter of the list describe the schema. Example:
The builtin listadd returns a new list constructed from a (possibly null) existing list, and new additional values. That list is then handed to the record statement. The first element of the list is the schema to use to record values to `sampleRecorder' strerrorThis builtin is similar to the errno builtin, but returns a string describing the error. Example:
This statement, when executed by the engine, echo's "Error for a missing variable: nonexistent object" strlenThe strlen builtin computes the length of a single string parameter. Any additional parameters are silently ignored. If the parameter Passed in is nott a string, the error type is returned, indicating a user error. Example:
The example computes the length of the string called str... strcatStrcat concatenates a variable number of arguments, and returns a new string, with the concatenated values. Although it is primarily intended to concatenate strings, it will also concatenate integers and lists. For integer types, the value of the interger is converted into a string, and appended. For list types, each member is concatenated onto the retuned new strings value. Types other than strings, lists, and integers are currently silently ignored. Example:
The example ought to echo "One 1 two 2 three 4 5". substrThis builtin creates a string from a string. It accepts either two or three arguments. The first parameter is always a string, the the second parameter is an index into the string. The first character of the string is zero (0). If a third parameter is included, it is the number of characters to include in the new returned string. If the third parameter is excluded, then it implies the rest of the characters in the first parameter, starting at the index (second parameter). If the index is less than zero, it is silently changed to zero. If the length is less than zero, it is silently changed to zero. If the length starting at the index, extends beyond the end of the first string parameter, the returned value is truncated to the length of the first string parameter (starting at the index). Example:
The first substr call creates a string "cdefg", which is echo'ed. The second call generates "cd". indexThis builtin locates one substring string within another. It needs Two parameters: index( big, little ). The builtin tries to match the string `little' within the string `big'. If it succeeds, it returns the index, an index which can be used as the index of substr. If it fails, it returns -1. Example:
The example will echo "2", indicating the index builtin returned an integer 2. listadd The listadd builtin adds additional types to the end of an existing list, and returns the new list. The original list passed as the first argument is left unmodified (because parameters are passed by value, this ought to be the case). Any types can be added to a list. The syntax of .nfr code does not Allow the direct description of lists with anything but strings, integer, hosts, and net descriptions. In particular, the syntax does not provide for lists within lists. But by using the listadd, complex list types can be built. Example:
In this example, the echo of a displays "[[1,2,3],[1,2,3],[1,2,3]]". Notice that the list builtin provides a mechanism for constructing complex lists. listlenThis builtin returns the number of elements of the list. The only Parameter must be a list, otherwise an error (user error) is returned. The length returned is a length of only elements; traversal of any sublists is not done. Example:
The above example will echo "3", indicating that the number of Elements in the list is three. Notice that the first element is a list, as are the second and third elements. sublistThe sublist builtin is like the substr, but the first parameter is a list, not a string. As in substr, the builtin accepts either two or three parameters, the second parameter indicating the index and the third parameter indication a length. When the third parameter, the length parameter, is missing, the sublist builtin will return the sublist starting at the index, returning the rest of the list; to get a list of 1 element, the length of 1 must be used. If the index is less than zero, it is silently changed to zero. If the length is less than zero, it is silently changed to zero. If the length starting at the index, extends beyond the end of the first list parameter, the returned value is truncated to the length of the first list parameter (starting at the index). Example:
This example echo's three different strings. The first string echo'ed is "sublist( list, 2 ) => [821,hello,dolly,-3,3,3,dolly]", the second echo generates the string "sublist( list, 2, 1 ) => [821]", the third parameter generates the string "sublist( list, 2, 10 ) => [821,hello,dolly,-3,3,3,dolly]". Also notice that the returned type is a string, even when there is a single element in the string. strcasecmpThis builtin compares two strings, returning negative if the first String is less, 0 if they are equal, and positive if the second is greater than the first. To determine equality, the two strings are compared character by character. If the characters are unequal, no further tests are made, if they are equal, testing continues until all of the characters of both strings are compared, character by character. Two characters are equal when they either have the same ascii value, or if they are alphabetic, if the two characters are the same, except for case. Example:
Four different strings are printed. In order, they are "0", "0", "0", and "-3" (a negative value). Note that the only guarantee is that the value be less than 0, 0, or greater than 0. Implementations may vary on different systems. lsortThis builtin sorts elements of an existing list, returning a new list. Only the first argument is sorted, any additional arguments are ignored. The new list is sorted in ascending order, with similar types arranged together. Order depends on types, with integers being sorted by their value, strings being sorted by their value, and lists being sorted by their length. No recursive descent is done to perform fine grain sorting of lists. Currently no other types are sorted, although it is likely many of the other tests will be sortable when a need arises. Example:list = [ 3, 5, 821, "hello", "dolly", -3, 3, 3, "dolly" ]; echo( "Sorted ", list, " -> ", lsort(list), "\n" ); This example will echo the string:
luniqThis builtin returns a new list, with unique elements. Adjacent elements are compared to see if they are equal, and only one is then added. For the builtin to work correctly on unsorted lists, the list must first be sorted, typically by using the `lsort' builtin. The luniq builtin accepts multiple parameters, but only operates on the first parameter. If the first parameter is not a list, the builtin returns 'error(user error)'. Example:
The previous .nfr code example generates "Uniq/sorted... luniq( lsort( list )) => [-3,3,5,821,dolly,hello]". typeofThis builtin returns a string, describing the type of the parameter. When multiple parameters are passed, a list is returned, with elements in 1-1 coorespondence with the parameters. These strings are returned for these types:
Example:
The first echo will display "typeof biglist: list". The second echo will display "typeof(typeof(biglist)): str". The third echo will display "typeof (biglist, list): [list,list]" pattern, regcompThese two builtin's are synonyms for each other. They return a new type, a pattern type, which can be used to compare with string, or used in the match/regexec builtin functions. The first paramter must be a string. It is the pattern to match against, a regular expression. The returned value can then be used to compare against strings. Example:pattern = pattern( "abc+" );
func foo { } foo( "abc" ); pattern = pattern( "^abc" ); pattern = pattern( "^abc|^def" ); The above example generates the following output:
regexec, matchThese two builtin functions are synonyms for each other. They accept two parameters, a string, and a pattern, in any order. They return an integer 0 when the match fails, and an integer 1 when the pattern matches. We can rewrite the example in regcomp/pattern as follows (though whether the example is clearer is up to the reader) pattern = pattern( "abc+" );
func foo { } foo( "abc" ); pattern = pattern( "^abc" ); pattern = pattern( "^abc|^def" ); And again, as in the regcomp/pattern builitin example, the output from the example:
|
|