This is click.info, produced by makeinfo version 4.8 from click.texi. INFO-DIR-SECTION Click modular router START-INFO-DIR-ENTRY * Click: (click). The Click modular router programming manual. END-INFO-DIR-ENTRY  File: click.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) Click ***** This document describes the Click modular router's programming interface. Read this if you're interested in writing new elements for Click. You shouldn't need to read it if you are just building routers that use existing elements. * Menu: * Overview:: * Helper Classes:: * Packets:: * Element Characteristics:: * Element Initialization:: * Element Runtime:: * Configuration Strings:: * Tasks:: * Timers:: * Notification:: * Coding Standards:: * Index:: Index. --- The Detailed Node Listing --- Overview * Packet Transfer:: Helper Classes * String:: * StringAccum:: * Vector:: * Bitvector:: * HashMap:: * BigHashMap:: * ErrorHandler:: * IPAddress:: * IP6Address:: StringAccum * StringAccum Constructors:: * StringAccum operator<<:: * Special StringAccum operator<<:: * StringAccum Manipulation:: * StringAccum Contents:: * StringAccum Results:: * StringAccum Out-of-Memory:: ErrorHandler * ErrorHandler Initialization:: * Reporting Errors:: * Error Format Strings:: * Counting Errors:: * Basic ErrorHandlers:: * Error Veneers:: * Writing ErrorHandlers:: Packets * Packet Structure and Contents:: * Packet Creation:: * Packets and sk_buffs:: * Packet Sharing:: * Packet Buffer Manipulation:: * Annotations:: * Packet Out-of-Memory:: Annotations * Header Annotations:: * User Annotations:: * Specific User Annotations:: * Other Annotations:: * Annotations In General:: Other Annotations * Destination Address Annotation:: * Timestamp Annotation:: * Device Annotation:: * Packet Type Annotation:: * Performance Counter Annotation:: Element Runtime * Handling Packets:: * Handlers:: Handlers * Read and Write Handler Overview:: * Adding Handlers:: * Default Handlers:: * Accessing Handlers Internally:: * LLRPC Overview:: Accessing Handlers Internally * Handler Objects:: * Handlers By Name or Index:: Configuration Strings * Config String Structure:: * Quoting and Unquoting:: * Config String Splitting:: * Parsing Functions:: * cp_va:: Parsing Functions * Parsing Strings:: * Parsing Booleans:: * Parsing Integers:: * Parsing Reals:: * Parsing IP Addresses:: * Parsing IPv6 Addresses:: * Parsing Ethernet Addresses:: * Parsing Elements:: * Parsing Handlers:: * Parsing Miscellaneous:: Parsing Argument Lists * cp_va Concepts:: * cp_va Initialization:: Tasks * Task Initialization:: * Scheduling Tasks:: * Tickets:: * Task Thread Choice:: * Task Status:: * Task Handlers:: * Task Cleanup:: Timers * Timer Initialization:: * Scheduling Timers:: * Timer Status Methods:: * Timer Cleanup:: Coding Standards * Upper and lower case names:: * Common name patterns::  File: click.info, Node: Overview, Next: Helper Classes, Prev: Top, Up: Top 1 Overview ********** * Menu: * Packet Transfer::  File: click.info, Node: Packet Transfer, Prev: Overview, Up: Overview 1.1 Packet Transfer ===================  File: click.info, Node: Helper Classes, Next: Packets, Prev: Overview, Up: Top 2 Helper Classes **************** * Menu: * String:: * StringAccum:: * Vector:: * Bitvector:: * HashMap:: * BigHashMap:: * ErrorHandler:: * IPAddress:: * IP6Address::  File: click.info, Node: String, Next: StringAccum, Prev: Helper Classes, Up: Helper Classes 2.1 String ========== The `String' class represents a string of characters. `String's may be constructed from C strings, characters, numbers, and so forth. They may also be added together. The underlying character arrays are dynamically allocated; operations on `String's allocate and free memory as needed. A `String' and its substrings will generally share memory. `String's may be assigned, stored, and passed to functions. See the Doxygen documentation on class `String' for information.  File: click.info, Node: StringAccum, Next: Vector, Prev: String, Up: Helper Classes 2.2 StringAccum =============== The `StringAccum' class, like `String' (*note String::), represents a string of characters. `StringAccum' is optimized for building a string through "accumulation", or successively appending substrings until the whole string is ready. A `StringAccum' has both a "length"--the number of characters it currently contains--and a "capacity"--the maximum number of characters it could hold without reallocating memory. * Menu: * StringAccum Constructors:: * StringAccum operator<<:: * Special StringAccum operator<<:: * StringAccum Manipulation:: * StringAccum Contents:: * StringAccum Results:: * StringAccum Out-of-Memory::  File: click.info, Node: StringAccum Constructors, Next: StringAccum operator<<, Prev: StringAccum, Up: StringAccum 2.2.1 Constructors ------------------ -- Constructor on StringAccum: StringAccum () Creates a `StringAccum' with no characters. -- Constructor on StringAccum: StringAccum (int CAPACITY) Creates a `StringAccum' with no characters, but a capacity of CAPACITY. CAPACITY must be greater than zero. `StringAccum''s copy constructor (`StringAccum(const StringAccum &)') and assignment operator (`operator=(const StringAccum &)') are private. Thus, `StringAccum's cannot be assigned or passed as arguments. Of course, references to `StringAccum's may be passed as arguments, and this usage is quite common.  File: click.info, Node: StringAccum operator<<, Next: Special StringAccum operator<<, Prev: StringAccum Constructors, Up: StringAccum 2.2.2 Appending with `operator<<' --------------------------------- Generally, you append to a `StringAccum' using iostreams-like `<<' operators, which this section describes. The next section describes the low-level interface, the `append' and `pop_back' methods. Here is a conventional use of `StringAccum''s `<<' operators: struct timeval tv; StringAccum sa; int n; // ... sa << tv << ": There are " << n << " things.\n"; -- Function: StringAccum & operator<< (StringAccum &SA, char C) -- Function: StringAccum & operator<< (StringAccum &SA, unsigned char C) Appends the character C to the `StringAccum' SA and returns SA. -- Function: StringAccum & operator<< (StringAccum &SA, const char *S) -- Function: StringAccum & operator<< (StringAccum &SA, const String &S) -- Function: StringAccum & operator<< (StringAccum &SA, const StringAccum &SA2) Appends the string S, or the value of the `StringAccum' SA2, to SA and returns SA. -- Function: StringAccum & operator<< (StringAccum &SA, short N) -- Function: StringAccum & operator<< (StringAccum &SA, unsigned short N) -- Function: StringAccum & operator<< (StringAccum &SA, int N) -- Function: StringAccum & operator<< (StringAccum &SA, unsigned N) -- Function: StringAccum & operator<< (StringAccum &SA, long N) -- Function: StringAccum & operator<< (StringAccum &SA, unsigned long N) -- Function: StringAccum & operator<< (StringAccum &SA, long long N) -- Function: StringAccum & operator<< (StringAccum &SA, unsigned long long N) -- Function: StringAccum & operator<< (StringAccum &SA, double N) Appends an ASCII decimal representation of the number N to SA and returns SA. For example, if N is 20, then `SA << N' has the same effect as `SA << "20"'. The `double' operator is not available in the kernel.  File: click.info, Node: Special StringAccum operator<<, Next: StringAccum Manipulation, Prev: StringAccum operator<<, Up: StringAccum 2.2.3 Appending Data Types -------------------------- `StringAccum' comes with `operator<<' definitions for the `bool', `struct timeval', `IPAddress', and `EtherAddress' types. Of course, you can write your own `operator<<' functions for other data types, either using existing `operator<<'s or the manipulation functions described in the next section. -- Function: StringAccum & operator<< (StringAccum &SA, bool &VAL) Appends the string `true' or `false' to SA, according to the value of VAL. -- Function: StringAccum & operator<< (StringAccum &SA, const struct timeval &TV) Appends an ASCII decimal representation of the time value TV to SA and returns SA. The time value is printed as if by `printf("%ld.%06ld", TV.tv_sec, TV.tv_usec)'. -- Function: StringAccum & operator<< (StringAccum &SA, IPAddress &ADDR) Appends the conventional dotted-quad representation of the IP address ADDR to SA and returns SA. For example, `sa << addr' might have the same effect as `sa << "18.26.4.44"'. -- Function: StringAccum & operator<< (StringAccum &SA, const EtherAddress &ADDR) Appends the conventional colon-separated hexadecimal representation of the Ethernet address ADDR to SA and returns SA. For example, `sa << addr' might have the same effect as `sa << "00:02:B3:06:06:36:EE"'.  File: click.info, Node: StringAccum Manipulation, Next: StringAccum Contents, Prev: Special StringAccum operator<<, Up: StringAccum 2.2.4 Manipulation ------------------ This section describes lower-level methods for manipulating `StringAccum' objects. The `append' methods append data to the `StringAccum'; the `extend', `reserve', and `forward' methods add space to the end of it; and the `clear' and `pop_back' methods remove its characters. -- Method on StringAccum: void append (char C) -- Method on StringAccum: void append (unsigned char C) Appends the character C to the end of this `StringAccum'. Equivalent to `*this << C'. -- Method on StringAccum: void append (const char *S, int LEN) Appends the first LEN characters of S to the end of this `StringAccum'. If LEN is negative, then this function treats S as a C string, effectively setting LEN to `strlen(S)'. -- Method on StringAccum: char * extend (int LEN) Puts LEN arbitrary characters at the end of this `StringAccum' and returns a pointer to those characters. The return value may be a null pointer if there is not enough memory to grow the character array. This method increases the `StringAccum''s length by LEN, which must be greater than or equal to zero. -- Method on StringAccum: char * extend (int LEN, int EXTRA) Puts LEN arbitrary characters at the end of this `StringAccum' and returns a pointer to those characters. Also ensures space for EXTRA additional characters following the LEN new characters; however, these characters do not contribute to the `StringAccum''s length. The return value may be a null pointer if there is not enough memory to grow the character array. Increases the `StringAccum''s length by LEN, which must be greater than or equal to zero. This form of `extend' is generally used to compensate for the null character appended by C string functions like `sprintf'. For example: if (char *buf = string_accum.extend(4, 1)) // 4 real characters plus one terminating null sprintf(buf, "\\%03o", i); *Caution*: The pointer returned by `extend', or the `reserve' method described below, should be treated as transient. It may become invalid after the next call to a method that grows the `StringAccum', such as `append', `extend', or one of the `operator<<' functions, and will definitely become invalid when the `StringAccum' is destroyed. The `reserve' and `forward' methods together provide a convenient, fast interface for appending strings of unknown, but bounded, length. -- Method on StringAccum: char * reserve (int LEN) Reserves space for LEN characters at the end of this `StringAccum' and returns a pointer to those characters. The return value may be a null pointer if there is not enough memory to grow the character array. This method does not change the `StringAccum''s length, although it may change its capacity. Use `forward' to change the `StringAccum''s length. -- Method on StringAccum: void forward (int AMT) Adds AMT to the `StringAccum''s length without changing its data. This method is used in conjunction with `reserve', above. Use `reserve' to get space suitable for appending a string of unknown, but bounded, length. After finding the actual length, use `forward' to inform the `StringAccum'. AMT must be greater than or equal to zero, and less than or equal to the remaining capacity. Finally, these methods remove characters from a `StringAccum' rather than add characters to it. -- Method on StringAccum: void clear () Erases the `StringAccum', making its length zero (an empty string). -- Method on StringAccum: void pop_back () -- Method on StringAccum: void pop_back (int AMT) Remove the last character, or the last AMT characters, of the string. AMT must be greater than or equal to zero, and less than or equal to the `StringAccum''s length.  File: click.info, Node: StringAccum Contents, Next: StringAccum Results, Prev: StringAccum Manipulation, Up: StringAccum 2.2.5 Contents -------------- *Caution*: The pointer returned by `data' and `c_str' should be treated as transient. It may become invalid after the next call to a method that grows the `StringAccum', such as `append', `extend', or one of the `operator<<' functions, and will definitely become invalid when the `StringAccum' is destroyed. -- Method on StringAccum: const char * data () const -- Method on StringAccum: char * data () Returns a pointer to the character data contained in this `StringAccum'. -- Method on StringAccum: int length () const Returns the number of characters in this `StringAccum'. -- Method on String: operator bool () -- Method on String: operator bool () const Returns true iff this `StringAccum' has at least one character. -- Method on StringAccum: const char * c_str () -- Method on StringAccum: const char * cc () Returns a pointer to the character data contained in this `StringAccum'. Guarantees that the returned string is null-terminated: the `length()'th character will be `'\0''. This does not affect the `StringAccum''s contents or length. -- Method on StringAccum: char operator[] (int I) const -- Method on StringAccum: char & operator[] (int I) Returns the Ith character of this `StringAccum'. I must be greater than or equal to zero, and less than the `StringAccum''s length. Note that the non-`const' version of this method returns a mutable character reference, which facilitates code like StringAccum sa; // ... sa[5] = 'a';  File: click.info, Node: StringAccum Results, Next: StringAccum Out-of-Memory, Prev: StringAccum Contents, Up: StringAccum 2.2.6 Results ------------- `StringAccum''s `take' methods return the string accumulated by a series of calls to `operator<<' or similar methods. Each `take' method makes `StringAccum' relinquish responsibility for its character array memory, passing that responsibility on to its caller. The caller should free the memory when it is done--either with `delete[]', for the `take' and `take_bytes' methods, or by relying on `String' to handle it, for the `take_string' method. Each `take' method additionally restores the `StringAccum' to its original, empty state. Further `append's or similar operations will begin building a new string from scratch. -- Method on StringAccum: void take (unsigned char *&S, int &LEN) Sets the S variable to this `StringAccum''s character data and LEN to its length. Then clears the `StringAccum''s internal state. -- Method on StringAccum: char * take () -- Method on StringAccum: unsigned char * take_bytes () Returns this `StringAccum''s character data, then clears the `StringAccum''s internal state. The methods differ only in their return types. Note that `StringAccum::length' will always return zero immediately after a `take' or `take_bytes'. If you need to know the string's length, call `length' first. -- Method on StringAccum: String take_string () Returns this `StringAccum''s character data as a `String' object (*note String::), then clears the `StringAccum''s internal state. This method hands the character data over to the `String' implementation; no data copies are performed.  File: click.info, Node: StringAccum Out-of-Memory, Prev: StringAccum Results, Up: StringAccum 2.2.7 Out-of-Memory Conditions ------------------------------ `StringAccum' operations are robust against out-of-memory conditions. If there is not enough memory to complete a particular operation, the `StringAccum' is erased and turned into a special out-of-memory indicator. This is a contagious empty string. Every operation on such a buffer (except for `clear') leaves it in the out-of-memory state. -- Method on StringAccum: bool out_of_memory () const Returns true iff this `StringAccum' is an out-of-memory indicator. The `extend' and `reserve' methods can return null pointers on out-of-memory; their callers should always check that their return values are non-null.  File: click.info, Node: Vector, Next: Bitvector, Prev: StringAccum, Up: Helper Classes 2.3 Vector ==========  File: click.info, Node: Bitvector, Next: HashMap, Prev: Vector, Up: Helper Classes 2.4 Bitvector =============  File: click.info, Node: HashMap, Next: BigHashMap, Prev: Bitvector, Up: Helper Classes 2.5 HashMap ===========  File: click.info, Node: BigHashMap, Next: ErrorHandler, Prev: HashMap, Up: Helper Classes 2.6 BigHashMap ==============  File: click.info, Node: ErrorHandler, Next: IPAddress, Prev: BigHashMap, Up: Helper Classes 2.7 ErrorHandler ================ All Click error messages are passed to an instance of the `ErrorHandler' class. `ErrorHandler' separates the generation of error messages from the particular way those messages should be printed. It also makes it easy to automatically decorate errors with context information. Most Click users must know how to report errors to an `ErrorHandler', and how `ErrorHandler's count the messages they receive. This section also describes how to decorate error messages with error veneers, and how to write new `ErrorHandler's. `ErrorHandler' and its important subclasses are defined in `'. * Menu: * ErrorHandler Initialization:: * Reporting Errors:: * Error Format Strings:: * Counting Errors:: * Basic ErrorHandlers:: * Error Veneers:: * Writing ErrorHandlers::  File: click.info, Node: ErrorHandler Initialization, Next: Reporting Errors, Prev: ErrorHandler, Up: ErrorHandler 2.7.1 Class Initialization -------------------------- The `ErrorHandler' class maintains some global state that must be initialized by calling `static_initialize' at the beginning of the program, and may be freed by calling `static_cleanup' when execution is complete. -- Static Method on ErrorHandler: void static_initialize (ErrorHandler *DEFAULT_ERRH) Call this function exactly once, at the beginning of the program, before any error messages are reported to any `ErrorHandler'. It is OK to create arbitrary `ErrorHandler' objects before calling this method, however. The DEFAULT_ERRH argument becomes the default `ErrorHandler'; see *Note Basic ErrorHandlers::. -- Static Method on ErrorHandler: void static_cleanup () Call this function exactly once, just before the program exits. Destroys the default and silent `ErrorHandler's and cleans up other `ErrorHandler'-related memory. It is an error to call any `ErrorHandler' method after calling `static_cleanup'.  File: click.info, Node: Reporting Errors, Next: Error Format Strings, Prev: ErrorHandler Initialization, Up: ErrorHandler 2.7.2 Reporting Errors ---------------------- `ErrorHandler''s basic error reporting methods take a format string, which may use `printf'-like `%' escape sequences, and additional arguments as required by the format string. *Note Error Format Strings::, for more details on the format string. The five methods differ in the seriousness of the error they report. -- Method on ErrorHandler: void debug (const char *FORMAT, ...) -- Method on ErrorHandler: void message (const char *FORMAT, ...) -- Method on ErrorHandler: int warning (const char *FORMAT, ...) -- Method on ErrorHandler: int error (const char *FORMAT, ...) -- Method on ErrorHandler: int fatal (const char *FORMAT, ...) Report the error described by FORMAT and any additional arguments. The methods are listed by increasing seriousness. Use `debug' for debugging messages that should not be printed in a production environment; `message' for explanatory messages that do not indicate errors; `warning' for warnings (this function prepends the string `warning: ' to every line of the error message); `error' for errors; and `fatal' for errors so serious that they should halt the execution of the program. The three functions that indicate errors, `warning', `error', and `fatal', always return `-EINVAL'. In some environments, `fatal' will actually exit the program with exit code 1. Each of these methods has an analogue that additionally takes a "landmark": a string representing where the error took place. A typical landmark contains a file name and line number, separated by a colon--`foo.click:31', for example. -- Method on ErrorHandler: void ldebug (const String &LANDMARK, const char *FORMAT, ...) -- Method on ErrorHandler: void lmessage (const String &LANDMARK, const char *FORMAT, ...) -- Method on ErrorHandler: int lwarning (const String &LANDMARK, const char *FORMAT, ...) -- Method on ErrorHandler: int lerror (const String &LANDMARK, const char *FORMAT, ...) -- Method on ErrorHandler: int lfatal (const String &LANDMARK, const char *FORMAT, ...) Report the error described by FORMAT and any additional arguments. The error took place at LANDMARK. Most `ErrorHandler's will simply prepend `LANDMARK: ' to each line of the error message. These methods are all implemented as wrappers around the `verror' function. This function takes a landmark, a format string, a `va_list' packaging up any additional arguments, and a "seriousness value", which encodes how serious the error was. The `Seriousness' enumerated type, which is defined in the `ErrorHandler' class, represents seriousness values. There are five constants, corresponding to the five error-reporting methods: `ERR_DEBUG' Corresponds to `debug' and `ldebug'. `ERR_MESSAGE' Corresponds to `message' and `lmessage'. `ERR_WARNING' Corresponds to `warning' and `lwarning'. `ERR_ERROR' Corresponds to `error' and `lerror'. `ERR_FATAL' Corresponds to `fatal' and `lfatal'. -- Method on ErrorHandler: int verror (Seriousness SERIOUSNESS, const String &LANDMARK, const char *FORMAT, va_list VAL) Report the error described by FORMAT and VAL. The error took place at LANDMARK, if LANDMARK is nonempty. The SERIOUSNESS value is one of the five constants described above. Always returns `-EINVAL'.  File: click.info, Node: Error Format Strings, Next: Counting Errors, Prev: Reporting Errors, Up: ErrorHandler 2.7.3 Format Strings -------------------- `ErrorHandler''s format strings closely follow C's standard `printf' format strings. Most characters in the format string are printed verbatim. The `%' character introduces a "conversion", which prints data read from the remaining arguments. The format string may contain newlines `\n', but it need not end with a newline; `ErrorHandler' will add a final newline if one does not exist. Each conversion, or formatting escape, follows this pattern: * First, the `%' character introduces each conversion. * Next comes zero or more "flag characters"; * then an optional "field width"; * then an optional "precision"; * then an optional "length modifier"; * and finally, the mandatory "conversion specifier", which is usually a single character, but may be a name enclosed in braces. We discuss each of these is turn. Any conversion may be modified by zero or more of these flag characters. `#' The value should be converted to an "alternate form". For `o' conversions, the first character of the output string is made `0', by prepending a `0' if there was not one already. For `x' and `X' conversions, nonzero values have `0x' or `0X' prepended, respectively. `0' The value should be zero padded. For `d', `i', `u', `o', `x', and `X' conversions, the converted value is padded on the left with `0' characters rather than spaces. `-' The value should be left-justified within the field width. ` ' (a space) Leave a blank before a nonnegative number produced by a signed conversion. `+' Print a `+' character before a nonnegative number produced by a signed conversion. The optional "field width", a decimal digit string, forces the conversion to use a minimum number of characters. The result of a conversion is padded on the left with space characters to reach the minimum field width, unless one of the `0' or `-' flags was supplied. The optional "precision" is a decimal digit string preceded by a period `.'. For `d', `i', `u', `o', `x', and `X' conversions, the precision specifies the minimum number of digits that must appear; results with fewer digits are padded on the left with `0' characters. For the `s' conversion, the precision specifies the maximum number of characters that can be printed. For `e', `f', `E', and `F' conversions, it specifies the number of digits to appear after the radix character; for `g' and `G' conversions, the number of significant digits. If either the field width or precision is specified as a star `*', `ErrorHandler' reads the next argument as an integer and uses that instead. Length modifiers affect the argument type read by the conversion. There are three modifiers: `h' The next argument is a `short' or `unsigned short'. Affects the `d', `i', `u', `o', `x', and `X' conversions. `l' The next argument is a `long' or `unsigned long'. Affects the `d', `i', `u', `o', `x', and `X' conversions. `ll' The next argument is a `long long' or `unsigned long long'. Affects the `d', `i', `u', `o', `x', and `X' conversions. Finally, these are the conversions themselves. `s' Print the `const char *' argument, treated as a C string. `c' The `int' argument is treated as a character constant. Printable ASCII characters (values between 32 and 126) are printed verbatim. Characters `\n', `\t', `\r', and `\0' use those C escape representations. Other characters use the representation `\%03o'. `d', `i' The argument is an `int'; print its decimal representation. `u' The argument is an `unsigned int'; print its decimal representation. `o' The argument is an `unsigned int'; print its octal representation. `x', `X' The argument is an `unsigned int'; print its hexadecimal representation. The `%x' conversion uses lowercase letters; `%X' uses uppercase letters. `e', `f', `g', `E', `F', `G' The argument is a `double'; print its representation as if by `printf' (user-level drivers only). `p' The `void *' argument is cast to `unsigned long' and printed as by `%#lx'. `%' Print a literal `%' character. `{element}' The argument is an `Element *'. Print that element's declaration. Note that `ErrorHandler' does not support the `n' conversion.  File: click.info, Node: Counting Errors, Next: Basic ErrorHandlers, Prev: Error Format Strings, Up: ErrorHandler 2.7.4 Counting Errors --------------------- `ErrorHandler' objects count the number of errors and warnings they have received and make those values available to the user. -- Method on ErrorHandler: virtual int nwarnings () const -- Method on ErrorHandler: virtual int nerrors () const Returns the number of warnings or errors received by this `ErrorHandler' so far. -- Method on ErrorHandler: virtual void reset_counts () Resets the `nwarnings' and `nerrors' counters to zero. These counters are typically used to determine whether an error has taken place in some complex piece of code. For example: int before_nerrors = errh->nerrors(); // ... complex code that may report errors to `errh' ... if (errh->nerrors() != before_nerrors) { // an error has taken place }  File: click.info, Node: Basic ErrorHandlers, Next: Error Veneers, Prev: Counting Errors, Up: ErrorHandler 2.7.5 Basic `ErrorHandler's --------------------------- Every Click error message eventually reaches some "basic" `ErrorHandler', which generally prints the messages it receives. The user-level driver's basic `ErrorHandler' prints error messages to standard error, while in the Linux kernel module, the basic `ErrorHandler' logs messages to the syslog and stores them for access via `/proc/click/errors'. Two basic `ErrorHandlers' are always accessible via static methods: the "default `ErrorHandler'", returned by `default_handler' and set by `set_default_handler'; and the "silent `ErrorHandler'", returned by `silent_handler', which ignores any error messages it receives. -- Static Method on ErrorHandler: ErrorHandler * default_handler () Returns the default `ErrorHandler'. -- Static Method on ErrorHandler: void set_default_handler (ErrorHandler *errh) Sets the default `ErrorHandler' to ERRH. The `static_initialize' method also sets the default `ErrorHandler'; see *Note ErrorHandler Initialization::. -- Static Method on ErrorHandler: ErrorHandler * silent_handler () Returns the silent `ErrorHandler'. This handler ignores any error messages it receives. It maintains correct `nwarnings' and `nerrors' counts, however. `FileErrorHandler', a kind of basic `ErrorHandler', is available in any user-level program. It prints every message it receives to some file, usually standard error. It can also prepend an optional context string to every line of every error message. -- Constructor on FileErrorHandler: FileErrorHandler (FILE *F, const String &PREFIX = "") Constructs a `FileErrorHandler' that prints error messages to file F. If PREFIX is nonempty, then every line of every error message is prepended by PREFIX.  File: click.info, Node: Error Veneers, Next: Writing ErrorHandlers, Prev: Basic ErrorHandlers, Up: ErrorHandler 2.7.6 Error Veneers ------------------- "Error veneers" wrap around basic `ErrorHandler' objects and change how error text is generated. An error veneer generally changes each error message's text in some way, perhaps by adding a context message or some indentation. It then passes the altered text to the basic `ErrorHandler' for printing. Error veneers can be easily nested. The first argument to each error veneer constructor is a pointer to another `ErrorHandler' object. The veneer will pass altered error text to this handler, the "base handler", for further processing and printing. It also delegates `nwarnings()' and `nerrors()' calls to the base handler. Click comes with three error veneers: one for adding context, one for prepending text to every line, and one for supplying missing landmarks. It is easy to write others; see *Note Writing ErrorHandlers::, for details. -- Constructor on ContextErrorHandler: ContextErrorHandler (ErrorHandler *BASE_ERRH, const String &CONTEXT, const String &INDENT = " ") Constructs a `ContextErrorHandler' with BASE_ERRH as base. The first time this handler receives an error message, it will precede the message with the CONTEXT string--generally more detailed information about where the error has occurred. Every line in every received error message is prepended with INDENT, two spaces by default, to set off the message from its context. -- Constructor on PrefixErrorHandler: PrefixErrorHandler (ErrorHandler *BASE_ERRH, const String &PREFIX) Constructs a `PrefixErrorHandler' with BASE_ERRH as base. This handler precedes every line of every error message with PREFIX. -- Constructor on LandmarkErrorHandler: LandmarkErrorHandler (ErrorHandler *BASE_ERRH, const String &LANDMARK) Constructs a `LandmarkErrorHandler' with BASE_ERRH as base. This handler supplies LANDMARK in place of any blank landmark passed to it. This will cause the base handler to include LANDMARK in its error message. To demonstrate these veneers in practice, we'll use the following function, which prints two error messages: void f(ErrorHandler *errh) { errh->error("First line\nSecond line"); errh->lwarning("here", "Third line"); } A simple `FileErrorHandler' shows the base case. FileErrorHandler errh1(stderr); f(&errh1); -| First line -| Second line -| here: warning: Third line The simplest error veneer, `PrefixErrorHandler', just prepends text to every line. PrefixErrorHandler errh2(&errh1, "prefix - "); f(&errh2); -| prefix - First line -| prefix - Second line -| prefix - here: warning: Third line `ContextErrorHandler' supplies a line of context before the first error message, and indents all messages except the context. ContextErrorHandler errh3(&errh1, "This was called from ...", "** "); f(&errh3); -| This was called from ... -| ** First line -| ** Second line -| here: ** warning: Third line Note that the indentation `** ' is printed after the landmark. This often looks better than the alternative. Of course, an error veneer can take another error veneer as its "base handler", leading to cumulative effects. ContextErrorHandler errh4(&errh2, "This was called from ...", "** "); f(&errh4); -| prefix - This was called from ... -| prefix - ** First line -| prefix - ** Second line -| prefix - here: ** warning: Third line  File: click.info, Node: Writing ErrorHandlers, Prev: Error Veneers, Up: ErrorHandler 2.7.7 Writing `ErrorHandler's ----------------------------- `ErrorHandler' constructs an error message using three virtual functions. The first, `make_text', parses a format string and argument list into a single `String'. This is passed to the second function, `decorate_text', which may transform the string. The final function, `handle_text', prints the resulting error message. This structure makes `ErrorHandler' easy to extend. To write a new basic `ErrorHandler', you will need to override just `handle_text' and the counting functions (`nwarnings', `nerrors', and `reset_counts'). The `ErrorVeneer' helper class, described below, lets you override just `decorate_text' when writing an error veneer. -- Method on ErrorHandler: virtual String make_text (Seriousness S, const char *FORMAT, va_list VAL) Parses the format string FORMAT with arguments from VAL, returning the results as a STRING object. The default implementation processes the formatting escapes described above (*note Error Format Strings::). It also prepends every line of the error message with `warning: ' if S equals `ERR_WARNING'. -- Method on ErrorHandler: virtual String decorate_text (Seriousness S, const String &PREFIX, const String &LANDMARK, const String &TEXT) Decorates the error message TEXT as appropriate and returns the result. At minimum, every line of the result should be prepended by PREFIX and, if it is nonempty, the landmark string LANDMARK. The default implementation creates lines like this: PREFIXLANDMARK: TEXT (if LANDMARK is nonempty) PREFIXTEXT (if LANDMARK is empty) Any spaces and/or a final colon are stripped from the end of LANDMARK. Special landmarks, which begin and end with a backslash `\', are ignored. -- Method on ErrorHandler: virtual void handle_text (Seriousness S, const String &TEXT) This method is responsible for printing or otherwise informing the user about the error message TEXT. If S equals `ERR_FATAL', the method should exit the program or perform some other drastic action. It should also maintain the `nwarnings()' and `nerrors()' counters. In most cases, it should ensure that the last character in TEXT is a newline. This method has no default implementation. The `ErrorVeneer' class, a subclass of `ErrorHandler', supplies default implementations for these functions that ease the construction of new error veneers. `ErrorVeneer''s single instance variable, `ErrorHandler *_errh', is the base handler. `ErrorVeneer' overrides all the relevant virtual functions--`nwarnings', `nerrors', `reset_counts', `make_text', `decorate_text', and `handle_text'. Its versions simply delegate to the corresponding methods on `_errh'. An error veneer designer will generally subclass `ErrorVeneer' rather than `ErrorHandler'; then she will override only the methods she cares about (usually `decorate_text'), relying on `ErrorVeneer''s default implementations for the rest. -- Constructor on ErrorVeneer: ErrorVeneer (ErrorHandler *BASE_ERRH) Constructs an `ErrorVeneer' helper class with BASE_ERRH as its base error handler. This constructor simply sets `_errh = base_errh'.  File: click.info, Node: IPAddress, Next: IP6Address, Prev: ErrorHandler, Up: Helper Classes 2.8 IPAddress ============= The `IPAddress' type represents an IPv4 address. It supports bitwise operations like `&' and `|' and provides methods for unparsing IP addresses into ASCII dotted-quad form. See the Doxygen documentation on class `IPAddress' for information.  File: click.info, Node: IP6Address, Prev: IPAddress, Up: Helper Classes 2.9 IP6Address ==============  File: click.info, Node: Packets, Next: Element Characteristics, Prev: Helper Classes, Up: Top 3 Packets ********* The `Packet' class represents Click packets. The single `Packet' interface has multiple implementations, one per driver. Inside the Linux kernel driver, a `Packet' object is equivalent to a Linux `sk_buff' structure; most `Packet' methods are inline functions that expand to `sk_buff' calls. The user-level driver, however, uses a purpose-built `Packet' implementation. Click packets separate header information from data. The `Packet *' pointer points to a header structure, which holds pointers to the actual packet data and a set of "annotations". Packet data may be shared by two or more packet headers. Packet headers, however, should never be shared. Packets come in two flavors, `Packet' and `WritablePacket'. A `Packet' object represents a packet header whose data might be shared with other packets. Because of this potential sharing, `Packet' data is read-only, and its methods return `const' pointers to data. A `WritablePacket' object, in contrast, represents a packet header whose data is known not to be shared. Its methods return non-`const' pointers. The `uniqueify' method turns a `Packet' into a `WritablePacket', possibly by making a copy of the packet's data. `WritablePacket' is a subclass of `Packet', so you can turn a `WritablePacket' into a `Packet' implicitly. The `Packet' and `WritablePacket' classes are defined in `'. * Menu: * Packet Structure and Contents:: * Packet Creation:: * Packets and sk_buffs:: * Packet Sharing:: * Packet Buffer Manipulation:: * Annotations:: * Packet Out-of-Memory::  File: click.info, Node: Packet Structure and Contents, Next: Packet Creation, Prev: Packets, Up: Packets 3.1 Structure and Contents ========================== Packet data is stored in a single flat array of bytes. There is no support for linked chains a` la BSD `mbuf'. The actual packet data is embedded inside a buffer that may be much larger, leaving unused spaces called "headroom" and "tailroom" before and after the data proper. Therefore, tasks like prepending a header need not always reallocate memory. If the headroom is big enough, prepending space for a new header just requires bumping a pointer. This diagram shows how a typical packet is laid out, with the relevant `Packet' methods' names. data |<- headroom ->|<----- length ----->|<- tailroom ->| | | | | +==============+====================+==============+ |XXXXXXXXXXXXXX| PACKET CONTENTS... |XXXXXXXXXXXXXX| +==============+====================+==============+ | | |<---------------- buffer_length ----------------->| buffer_data And here are those methods' descriptions. -- Method on Packet: const unsigned char * data () const Returns a pointer to the packet data proper. -- Method on Packet: unsigned length () const Returns the length of the packet data proper. -- Method on Packet: const unsigned char * buffer_data () const Returns a pointer to the buffer that contains the packet data. -- Method on Packet: unsigned headroom () const -- Method on Packet: unsigned tailroom () const -- Method on Packet: unsigned buffer_length () const Returns the length of the headroom area, the tailroom area, and the whole buffer, respectively. -- Method on WritablePacket: unsigned char * data () const -- Method on WritablePacket: unsigned char * buffer_data () const These `WritablePacket' methods are identical to `Packet''s `data' and `buffer_data' methods except for their non-`const' return type. Two invariants relate these methods' values: buffer_length() = headroom() + length() + tailroom() data() = buffer_data() + headroom()  File: click.info, Node: Packet Creation, Next: Packets and sk_buffs, Prev: Packet Structure and Contents, Up: Packets 3.2 Creation and Destruction ============================ Packets are created with the `Packet::make' static methods, and destroyed with the `Packet::kill' method. (The `Packet' and `WritablePacket' classes have private constructors and destructors; you cannot create or destroy packets with `new' or `delete'.) 3.2.1 `Packet::make' -------------------- The `make' methods always take the length of the packet data; some of them take the packet contents and the headroom and tailroom lengths as well. (The contents of any headroom and tailroom areas are always undefined.) Most of them return a `WritablePacket *', since new packets are not shared. The `Packet' class defines two constants related to packet creation, `DEFAULT_HEADROOM' and `MIN_BUFFER_LENGTH'. Those `make' methods that do not take an explicit headroom parameter use `DEFAULT_HEADROOM' instead. Furthermore, no `make' method will create a packet with buffer length less than `MIN_BUFFER_LENGTH'. If the sum of a packet's headroom and length is less than this, the packet buffer is given extra tailroom to bump the buffer length up to `MIN_BUFFER_LENGTH'. These constants have the values `DEFAULT_HEADROOM' = 28 and `MIN_BUFFER_LENGTH' = 64. -- Static Method on Packet: WritablePacket * make (unsigned LEN) Returns a new packet containing LEN bytes of undefined data. -- Static Method on Packet: WritablePacket * make (const char *DATA, unsigned LEN) -- Static Method on Packet: WritablePacket * make (const unsigned char *DATA, unsigned LEN) Returns a new packet whose contents equal the first LEN bytes of DATA. DATA may be a null pointer, in which case the packet contains LEN bytes of undefined data. -- Static Method on Packet: WritablePacket * make (unsigned HEADROOM, const unsigned char *DATA, unsigned LEN, unsigned TAILROOM) Returns a new packet containing HEADROOM bytes of headroom, LEN bytes of contents, and at least TAILROOM bytes of tailroom. The packet contents will equal the first LEN bytes of DATA unless DATA is a null pointer, in which case the contents are undefined. The following `make' method is only available in the user-level driver. -- Static Method on Packet: WritablePacket * make (unsigned char *DATA, unsigned LEN, void (*DESTRUCTOR)(unsigned char *, size_t)) Returns a new packet that uses DATA as a buffer. That is, the new packet will have the following characteristics: `buffer_data' DATA `buffer_length' LEN `headroom' 0 `length' LEN `tailroom' 0 When the resulting packet is destroyed, the function DESTRUCTOR will be called with DATA and LEN as arguments. DESTRUCTOR may be a null pointer, in which case `Packet' calls `delete[] DATA' instead. This method lets a user-level element manage packet memory itself, rather than relying on `Packet'. *Note Packets and sk_buffs::, for a `make' method only available in the Linux kernel driver. 3.2.2 `Packet::kill' -------------------- To destroy a `Packet', simply call its `kill' method. -- Method on Packet: void kill () Frees this packet. If this packet contained the last reference to its data buffer, then frees the data buffer as well.  File: click.info, Node: Packets and sk_buffs, Next: Packet Sharing, Prev: Packet Creation, Up: Packets 3.3 `Packet's and `sk_buff's ============================ In the Linux kernel driver, `Packet' objects are equivalent to `struct sk_buff's. This avoids indirection overhead and makes it cheap to pass packets back and forth between Linux and Click. The `Packet' operations described in this section are mostly inline functions that expand to conventional `sk_buff' calls like `skb_clone()'. Click `Packet' `sk_buff's should always have `skb->users' equal to 1. That is, the `sk_buff' headers should not be shared, although the data buffers they point to may be shared. The `make', `skb', and `steal_skb' methods described in this section convert `Packet's to `sk_buff's and vice versa. -- Static Method on Packet: Packet * make (struct sk_buff *SKB) Returns a new packet equivalent to the `sk_buff' SKB. All of SKB's data pointers and annotations are left unchanged. This method generally does nothing, since `Packet's and `sk_buff's are equivalent in the Linux kernel. However, if `SKB->users' field is bigger than 1, the method will return a clone of SKB. This method returns a `Packet *', not a `WritablePacket *', because the SKB argument might share data with some other `sk_buff'. Do not use or manipulate SKB after passing it to this method, since Click and the `Packet' implementation now own SKB. -- Method on Packet: struct sk_buff * skb () -- Method on Packet: const struct sk_buff * skb () const Returns the `sk_buff' corresponding to this packet. Use this method to examine the `sk_buff' version of a `Packet'. Do not pass the result to a function that might free it or increment its `users' field; use `steal_skb' for that. -- Method on Packet: struct sk_buff * steal_skb () Returns the `sk_buff' corresponding to this packet. Use this method to permanently change a `Packet' into an `sk_buff'--for example, to create an `sk_buff' you'd like to send to Linux. Do not use or manipulate a `Packet' after calling its `steal_skb' method, since Linux now owns the resulting `sk_buff'.  File: click.info, Node: Packet Sharing, Next: Packet Buffer Manipulation, Prev: Packets and sk_buffs, Up: Packets 3.4 Sharing--`clone' and `uniqueify' ==================================== The `clone' method creates a new packet header that shares data with an existing packet. The `uniqueify' method, in contrast, ensures that a packet's data is not shared by anyone, perhaps by making a copy of the data. -- Method on Packet: Packet * clone () Creates and returns a new packet header that shares this packet's data. The new packet's annotations are copied from this packet's annotations. The result may be a null pointer if there was not enough memory to make a new packet header. -- Method on Packet: WritablePacket * uniqueify () Ensures that this packet does not share data with any other packet. This may involve copying the packet data, and perhaps creating a new packet header, but if this packet is already unshared, no real work is required. Returns a `WritablePacket *' because the new packet is unshared. Do not use, manipulate, or free a `Packet' after calling its `uniqueify' method. Manipulate the returned `WritablePacket *' instead. The result may be a null pointer if there was not enough memory to make a required data copy. In this case, the old packet is freed. -- Method on Packet: bool shared () const Returns true if and only if this packet shares data with some other packet.  File: click.info, Node: Packet Buffer Manipulation, Next: Annotations, Prev: Packet Sharing, Up: Packets 3.5 Buffer Manipulation--`push', `pull', `put', and `take' ========================================================== The `push', `pull', `put', and `take' methods manipulate a packet's contents by adding or removing space from its headroom or tailroom. Given a packet, use `push' to add space to its beginning, `pull' to remove space from its beginning, `put' to add space to its end, and `take' to remove space from its end. The methods that add space, `push' and `put', uniqueify the relevant packet as a side effect. This ensures that the packet's data is unshared so you can immediately manipulate the added space. -- Method on Packet: WritablePacket * push (unsigned AMT) Adds AMT bytes of space to the beginning of the packet's data and returns the resulting packet. The new space is uninitialized. The result will not share data with any other packet; thus, it is a `WritablePacket *'. If this packet is unshared and its headroom is bigger than AMT, then this operation is cheap, amounting to a bit of pointer arithmetic. Otherwise, it requires copying the packet data and possibly creating a new packet header. Do not use, manipulate, or free a `Packet' after calling its `push' method. Manipulate the returned `WritablePacket *' instead. The result may be a null pointer if there was not enough memory to make a required new packet. In this case, the old packet is freed. -- Method on Packet: void pull (unsigned AMT) Removes AMT bytes of space from the beginning of the packet's data. AMT must be less than or equal to the packet's `length()'. This operation is always cheap, amounting to a bit of pointer arithmetic. -- Method on Packet: WritablePacket * put (unsigned AMT) Adds AMT bytes of space to the end of the packet's data and returns the resulting packet. The new space is uninitialized. The result will not share data with any other packet; thus, it is a `WritablePacket *'. If this packet is unshared and its tailroom is bigger than AMT, then this operation is cheap, amounting to a bit of pointer arithmetic. Otherwise, it requires copying the packet data and possibly creating a new packet header. Do not use, manipulate, or free a `Packet' after calling its `put' method. Manipulate the returned `WritablePacket *' instead. The result may be a null pointer if there was not enough memory to make a required new packet. In this case, the old packet is freed. -- Method on Packet: void take (unsigned AMT) Removes AMT bytes of space from the end of the packet's data. AMT must be less than or equal to the packet's `length()'. This operation is always cheap, amounting to a bit of pointer arithmetic. The `push' and `put' methods have "nonunique" variants, `nonunique_push' and `nonunique_put', which do not have the side effect of uniqueifying their resulting packet. These methods are rarely used. -- Method on Packet: Packet * nonunique_push (unsigned AMT) Adds AMT bytes of space to the beginning of the packet's data and returns the resulting packet. The new space is uninitialized. The result may share data with other packets. If this packet's headroom is bigger than AMT, then this operation is cheap, amounting to a bit of pointer arithmetic. Otherwise, it requires copying the packet data and possibly creating a new packet header. Do not use, manipulate, or free a `Packet' after calling its `nonunique_push' method. Manipulate the returned `Packet *' instead. The result may be a null pointer if there was not enough memory to make a required new packet. In this case, the old packet is freed. -- Method on Packet: Packet * nonunique_put (unsigned AMT) Adds AMT bytes of space to the end of the packet's data, returning the resulting packet. The new space is uninitialized. The result may share data with other packets. If this packet's tailroom is bigger than AMT, then this operation is cheap, amounting to a bit of pointer arithmetic. Otherwise, it requires copying the packet data and possibly creating a new packet header. Do not use, manipulate, or free a `Packet' after calling its `nonunique_put' method. Manipulate the returned `Packet *' instead. The result may be a null pointer if there was not enough memory to make a required new packet. In this case, the old packet is freed.  File: click.info, Node: Annotations, Next: Packet Out-of-Memory, Prev: Packet Buffer Manipulation, Up: Packets 3.6 Annotations =============== Each packet header has space for a number of "annotations", extra information about the packet that is not contained in its data. Click supports "header annotations", which indicate where in the packet a network header, such as an IP header, is located; "user annotations", whose semantics are left undefined by Click--different elements can treat them in different ways; and other specialized annotations, such as the "timestamp annotation", the "destination IP address annotation", and so forth. New packets begin with all annotations cleared: numeric annotations are zero, pointer annotations are null pointers. `clone', `uniqueify', and their equivalents always copy each of the original packet's annotations in the appropriate way. (For example, the new header annotations will point into the new data, if a data copy was made.) * Menu: * Header Annotations:: * User Annotations:: * Specific User Annotations:: * Other Annotations:: * Annotations In General::  File: click.info, Node: Header Annotations, Next: User Annotations, Prev: Annotations, Up: Annotations 3.6.1 Header Annotations ------------------------ Many packets contain a network header of some kind, such as an IP header. This header may be located anywhere in the packet depending on how the packet was encapsulated. Furthermore, the data encapsulated by that network header may be located anywhere after the network header, given the presence of options. With the "network header annotation" and the "transport header annotation", one element can determine where a network header is and how long it is, then store this information for other elements to use. For example, the `CheckIPHeader' element sets the header annotations on packets it receives. Elements like `SetIPDSCP' then require a non-null IP header annotation on their input packets. The header annotations on new packets are each set to a null pointer. -- Method on Packet: const unsigned char * network_header () const -- Method on WritablePacket: unsigned char * network_header () const Returns the network header annotation. The resulting pointer is read-only on `Packet's and read/write on `WritablePacket's. -- Method on Packet: const unsigned char * transport_header () const -- Method on WritablePacket: unsigned char * transport_header () const Returns the transport header annotation. The resulting pointer is read-only on `Packet's and read/write on `WritablePacket's. -- Method on Packet: int network_header_offset () const Returns the offset from `data()' to `network_header()'. The result might be negative, since the `data' pointer may have been advanced past the network header annotation with the `pull' method. -- Method on Packet: int network_header_length () const Returns the network header's length. This equals `transport_header()' - `network_header()'. -- Method on Packet: unsigned transport_header_offset () const Returns the offset from `data()' to `transport_header()'. The result might be negative, since the `data' pointer may have been advanced past the transport header annotation with the `pull' method. Several invariants relate these methods' values whenever the header annotations are non-null: `buffer_data()' <= `network_header()' <= `transport_header()' <= `buffer_data()' + `buffer_length()' `network_header_offset()' = `network_header()' - `data()' `transport_header_offset()' = `transport_header()' - `data()' `network_header_length()' = `transport_header()' - `network_header()' Set the network and transport header annotations simultaneously with the `set_network_header' method. -- Method on Packet: void set_network_header (const unsigned char *HEADER, unsigned LEN) Sets the network header annotation to HEADER, which must lie between `buffer_data()' and `buffer_data()' + `buffer_length()'. The network header is LEN bytes long, so `network_header_length()' will equal LEN and `transport_header()' will equal HEADER + LEN. 3.6.1.1 Typed Header Annotations ................................ For convenience, `Packet' provides methods for accessing and setting the network header annotation as an IP or IPv6 header. These methods use the same annotations as the generic `network_header' methods; they are just typed differently. -- Method on Packet: const click_ip * ip_header () const -- Method on WritablePacket: click_ip * ip_header () const -- Method on Packet: const click_ip6 * ip6_header () const -- Method on WritablePacket: click_ip6 * ip6_header () const Returns `network_header()' as a pointer to an IP or IPv6 header structure. -- Method on Packet: int ip_header_offset () const -- Method on Packet: unsigned ip_header_length () const -- Method on Packet: int ip6_header_offset () const -- Method on Packet: unsigned ip6_header_length () const Equivalent to `network_header_offset()' and `network_header_length()'. -- Method on Packet: void set_ip_header (const click_ip *HEADER, unsigned LEN) -- Method on Packet: void set_ip6_header (const click_ip6 *HEADER, unsigned LEN) Equivalent to `set_network_header(HEADER, LEN)'. -- Method on Packet: void set_ip6_header (const click_ip6 *HEADER) Equivalent to `set_ip6_header(HEADER, 40)'. -- Method on Packet: const click_tcp * tcp_header () const -- Method on WritablePacket: click_tcp * tcp_header () const -- Method on Packet: const click_udp * udp_header () const -- Method on WritablePacket: click_udp * udp_header () const Returns `transport_header()' as a pointer to a TCP or UDP header structure.  File: click.info, Node: User Annotations, Next: Specific User Annotations, Prev: Header Annotations, Up: Annotations 3.6.2 User Annotations ---------------------- Each packet header has a "user annotation area", space reserved for arbitrary annotations. Different methods access this space as an array of bytes, integers, or unsigned integers. The `Packet' class does not assign semantics to any particular byte in the user annotation area. Instead, macros in `' provide names for particular bytes. Some of these names have overlapping byte ranges; the user must take care not to define a configuration whose elements use an annotation byte on a packet for different purposes. The next section describes the macros in Click's default `'. These constants define the size of the annotation area. `Packet::USER_ANNO_SIZE' The size of the annotation area in bytes. `Packet::USER_ANNO_US_SIZE' The size of the annotation area in `unsigned short's. `Packet::USER_ANNO_S_SIZE' The size of the annotation area in `short's. `Packet::USER_ANNO_U_SIZE' The size of the annotation area in `unsigned int's. `Packet::USER_ANNO_I_SIZE' The size of the annotation area in `int's. Currently, `USER_ANNO_SIZE' is 24, `USER_ANNO_U_SIZE' and `USER_ANNO_I_SIZE' are both 6, and `USER_ANNO_US_SIZE' and `USER_ANNO_S_SIZE' are both 12. The user annotation area may be accessed as an array of bytes, an array of `unsigned int's, or an array of `int's. The elements of these arrays are numbered from 0 to K - 1, where K is the appropriate `SIZE' constant. -- Method on Packet: unsigned char user_anno_c (int I) const Returns the Ith byte in the user annotation area. I must be between 0 and `USER_ANNO_SIZE' - 1. -- Method on Packet: unsigned user_anno_u (int I) -- Method on Packet: int user_anno_i (int I) Returns the Ith `unsigned int' or `int' in the user annotation area. I must be between 0 and `USER_ANNO_U_SIZE' - 1. The Ith `unsigned int' or `int' annotation occupies bytes 4I through 4I + 3 of the user annotation area. -- Method on Packet: void set_user_anno_c (int I, unsigned char VALUE) -- Method on Packet: void set_user_anno_u (int I, unsigned VALUE) -- Method on Packet: void set_user_anno_i (int I, int VALUE) Sets the Ith byte, `unsigned int', or `int' user annotation to VALUE. -- Method on Packet: unsigned * all_user_anno_u () Returns a pointer to the user annotation area, treated as an array of `unsigned int's.  File: click.info, Node: Specific User Annotations, Next: Other Annotations, Prev: User Annotations, Up: Annotations 3.6.3 Specific User Annotations ------------------------------- The `' header file defines macros for accessing a packet's user annotation area by name. These macros follow some simple guidelines. Each user annotation is given a name like `PAINT' or `FIX_IP_SRC'. Then, two macros are written for each annotation, `NAME_ANNO' and `SET_NAME_ANNO'. -- Macro: NAME_ANNO (const Packet *P) Returns the value of P's NAME annotation. -- Macro: SET_NAME_ANNO (Packet *P, VALUE) Sets P's NAME annotation to VALUE. For example, here are the definitions of `PAINT_ANNO' and `SET_PAINT_ANNO' from Click's default `'. #define PAINT_ANNO(p) ((p)->user_anno_c(0)) #define SET_PAINT_ANNO(p, v) ((p)->set_user_anno_c(0, (v))) This table lists the annotations declared in Click's default `'. Annotation name Type Bytes Some relevant elements `PAINT' `unsigned char' 0 `Paint', `CheckPaint', `PaintTee' `ICMP_PARAM_PROB' `unsigned char' 1 `IPGWOptions', `ICMPError' `FIX_IP_SRC' `unsigned char' 3 `ICMPError', `FixIPSrc' `FWD_RATE' `int' 4-7 `IPRateMonitor' `REV_RATE' `int' 8-11 `IPRateMonitor'  File: click.info, Node: Other Annotations, Next: Annotations In General, Prev: Specific User Annotations, Up: Annotations 3.6.4 Other Annotations ----------------------- Packet headers have space for four other particular annotations, and special methods for accessing them. These annotations do not overlap the user annotation area. There are annotations that hold a destination IP address, a timestamp, the device on which the packet arrived, a packet type constant, and, in the Linux kernel module, a performance counter value. * Menu: * Destination Address Annotation:: * Timestamp Annotation:: * Device Annotation:: * Packet Type Annotation:: * Performance Counter Annotation::  File: click.info, Node: Destination Address Annotation, Next: Timestamp Annotation, Prev: Other Annotations, Up: Other Annotations 3.6.4.1 Destination Address ........................... The destination address annotation stores the IP or IPv6 address of the next hop towards the packet's destination. Elements check and manipulate this address, rather than the IP header's destination address, since the next-hop address often differs from the final destination. The destination IP address and IPv6 address are different annotations, but they overlap; you may set only one at a time. -- Method on Packet: IPAddress dst_ip_anno () const Returns this packet's destination IP address annotation. -- Method on Packet: const IP6Address & dst_ip6_anno () const Returns a reference to this packet's destination IPv6 address annotation. -- Method on Packet: void set_dst_ip_anno (IPAddress VALUE) -- Method on Packet: void set_dst_ip6_anno (const IP6Address &VALUE) Sets this packet's destination IP or IPv6 address annotation to VALUE. The destination IP address annotation is set by the `GetIPAddress' and `SetIPAddress' elements, manipulated by `LookupIPRoute' and its cousins, and used by `ARPQuerier'. It defaults to zero.  File: click.info, Node: Timestamp Annotation, Next: Device Annotation, Prev: Destination Address Annotation, Up: Other Annotations 3.6.4.2 Timestamp ................. The timestamp annotation generally indicates when a packet was received. -- Method on Packet: const struct timeval & timestamp_anno () const -- Method on Packet: struct timeval & timestamp_anno () Returns a reference to this packet's timestamp annotation. -- Method on Packet: void set_timestamp_anno (const struct timeval &VALUE) Sets this packet's timestamp annotation to VALUE. -- Method on Packet: void set_timestamp_anno (int SEC, int USEC) Sets this packet's timestamp annotation to SEC and USEC. Equivalent to `struct timeval tv; tv.tv_sec = SEC; tv.tv_usec = USEC; set_timestamp_anno(tv)'. Linux device drivers set this annotation, so packets emitted by `FromDevice' and `PollDevice' in the Linux kernel driver have the annotation set. Packet sources like `InfiniteSource' and `RatedSource' also set the annotation, as does `FromDump' in the user-level driver. Debugging elements like `Print' generally take a keyword argument that makes them print packet timestamps. The timestamp annotation defaults to zero.  File: click.info, Node: Device Annotation, Next: Packet Type Annotation, Prev: Timestamp Annotation, Up: Other Annotations 3.6.4.3 Device .............. In the Linux kernel, packets received from some device are annotated with a pointer to the relevant `struct net_device' object. (In versions of the kernel prior to 2.3, this type was called `struct device'.) The `Packet' class provides access to this annotation. The annotation has type `net_device *'; Click defines `net_device' as a synonym for `struct device' in kernel versions 2.2 and prior. -- Method on Packet: net_device * device_anno () const Returns this packet's device annotation. -- Method on Packet: void set_device_anno (net_device *VALUE) Sets this packet's device annotation to VALUE. In the user-level driver, `device_anno' always returns 0, and `set_device_anno' does nothing. The `ARPResponder' element sets this annotation on every generated response to the value of the annotation on the relevant query. Because of this, those responses can be safely forwarded to Linux: Linux's ARP-response code requires a correct device annotation. The device annotation defaults to a null pointer.  File: click.info, Node: Packet Type Annotation, Next: Performance Counter Annotation, Prev: Device Annotation, Up: Other Annotations 3.6.4.4 Packet Type ................... The packet type annotation specifies how a packet was received. Its value is one of the following constants, which are defined in the `Packet::PacketType' enumeration. `HOST' The packet was sent to this host. `BROADCAST' The packet was sent to a link-level broadcast address. `MULTICAST' The packet was sent to a link-level multicast address. `OTHERHOST' The packet was sent to a different host, but received anyway. The relevant device is probably in promiscuous mode. `OUTGOING' The packet was generated at this host and is being sent to another host. `LOOPBACK', `FASTROUTE' See the Linux kernel documentation. These values correspond to `PACKET_LOOPBACK' and `PACKET_FASTROUTE', which are defined in `'. -- Method on Packet: Packet::PacketType packet_type_anno () const Returns this packet's packet type annotation. -- Method on Packet: void set_packet_type_anno (Packet::PacketType VALUE) Sets this packet's packet type annotation to VALUE. In the Linux kernel, device drivers set the packet type annotation for the packets they receive. Thus, the `FromDevice' and `PollDevice' elements generate packets with correct packet type annotations. The user-level driver's `FromDevice' also sets the packet type annotation. The `ICMPError' and `DropBroadcasts' elements use the annotation's value. The packet type annotation defaults to `Packet::HOST'.  File: click.info, Node: Performance Counter Annotation, Prev: Packet Type Annotation, Up: Other Annotations 3.6.4.5 Performance Counter ........................... This annotation is available only in the Linux kernel driver. Its value is an `unsigned long long' that generally corresponds to some performance counter value. -- Method on Packet: unsigned long long perfctr_anno () const Returns this packet's performance counter annotation. -- Method on Packet: void set_perfctr_anno (unsigned long long VALUE) Sets this packet's performance counter annotation to VALUE. The `SetCycleCount', `SetPerfCount', `CycleCountAccum', and `PerfCountAccum' elements manipulate this annotation. Its default value is zero.  File: click.info, Node: Annotations In General, Prev: Other Annotations, Up: Annotations 3.6.5 Annotations In General ---------------------------- `Packet' provides methods for clearing a packet's annotations, and for copying all of a packet's annotations from another packet. -- Method on Packet: void clear_annotations () Clears all of this packet's annotations to their default state, which is generally zero. -- Method on Packet: void copy_annotations (const Packet *P) Copies all of P's annotations into this packet except for its header annotations. (This packet's current header annotations are left unchanged.)  File: click.info, Node: Packet Out-of-Memory, Prev: Annotations, Up: Packets 3.7 Out-of-Memory Conditions ============================ Any method that potentially allocates memory for a `Packet' may fail due to an out-of-memory condition. The complete list of these methods follows: * `make' variants * `clone' * `uniqueify' * `push' * `put' * `nonunique_push' * `nonunique_put' These methods always return a null pointer on out-of-memory. Methods that manipulate existing packets--`uniqueify', `push', `put', `nonunique_push', and `nonunique_put'--additionally free any existing packet before returning a null pointer. You should always check the results of these methods to see if you have run out of memory.  File: click.info, Node: Element Characteristics, Next: Element Initialization, Prev: Packets, Up: Top 4 Element Characteristics ************************* See the Doxygen documentation on class `Element' for information on element characteristics.  File: click.info, Node: Element Initialization, Next: Element Runtime, Prev: Element Characteristics, Up: Top 5 Element Initialization ************************ See the Doxygen documentation on class `Element' for information on element initialization.  File: click.info, Node: Element Runtime, Next: Configuration Strings, Prev: Element Initialization, Up: Top 6 Element Runtime ***************** See the Doxygen documentation on class `Element' for information on moving packets, handling packets, running tasks. * Menu: * Handling Packets:: * Handlers::  File: click.info, Node: Handling Packets, Next: Handlers, Prev: Element Runtime, Up: Element Runtime 6.1 Handling Packets ==================== Every `Packet' object should be single-threaded through Click: the same `Packet' pointer should never be in use in two different places. In particular, an element should not use a `Packet' after passing it downstream to the rest of the configuration (by calling `output().push', for example). This, for example, is the wrong way to write a `Tee' with two outputs. void BadTee::push(int, Packet *p) { output(0).push(p); output(1).push(p); } The same packet pointer, `p', has been pushed to two different outputs. This is always illegal; the rest of the configuration may have modified or even freed the packet before returning control to `BadTee'. The correct definition uses the `clone' method: void GoodTee::push(int, Packet *p) { output(0).push(p->clone()); output(1).push(p); } Every `push' or `pull' method must account for every packet it receives by freeing it, emitting it on some output, or perhaps explicitly storing it for later. This `push' method, for example, contains a memory leak: void Leaky::push(int, Packet *p) { const click_ip *iph = p->ip_header(); // ... more processing ... _counter++; return; // XXX Oops! // Must push the packet on, store it, or kill it before returning. }  File: click.info, Node: Handlers, Prev: Handling Packets, Up: Element Runtime 6.2 Handlers ============ "Handlers" are access points through which users can interact with elements in a running Click router, or with the router as a whole. "Read" and "write handlers" behave like files in a file system, while "LLRPCs" provide a remote procedure call interface. * Menu: * Read and Write Handler Overview:: * Adding Handlers:: * Default Handlers:: * Accessing Handlers Internally:: * LLRPC Overview::  File: click.info, Node: Read and Write Handler Overview, Next: Adding Handlers, Prev: Handlers, Up: Handlers 6.2.1 Read and Write Handler Overview ------------------------------------- Read and write handlers appear to the user like files in a file system, or alternatively, like a limited RPC mechanism that uses ASCII strings for data transfer. To the element programmer, a read handler is simply a function that takes an element and returns a String; a write handler is a function that takes an element and a String and returns an error code. -- Function Type: String (*ReadHandler) (Element *ELEMENT, void *THUNK) Read handler functions have this type. When the user accesses a read handler on an element, Click calls some `ReadHandler' function and passes the element as an argument. The THUNK argument contains callback data specified when the handler was added. The function's String return value is passed back to the user. -- Function Type: int (*WriteHandler) (const String &DATA, Element *ELEMENT, void *THUNK, ErrorHandler *ERRH) Write handler functions have this type. When the user accesses some element write handler by passing in a string, Click calls some `WriteHandler' function and passes the data and the relevant element as arguments. The THUNK argument contains callback data specified when the handler was added. The return value is an error code: zero when there are no errors, and the negative of some `errno' value when there is an error. More detailed information about any errors should be reported to the ERRH argument. Each handler has an ASCII "name". Handler names must be unique within each element; for example, there can be at most one `x' read handler in a given element. A given name can be shared by a read handler and a write handler, however. Such a handler pair is colloquially called a "read/write handler", although its two components need not have anything to do with one another. There is currently no way to pass data to a read handler or return data from a write handler. Use LLRPCs if you need a more RPC-like read-write interface. Note that read and write handler functions are regular functions, not virtual functions. Often, therefore, handler functions are defined as private static member functions in the relevant element class. Read and write handlers need not use ASCII-formatted data. Most existing handlers do format their data in ASCII, however, and use `cp_uncomment' to ignore leading and trailing whitespace and comments (*note Quoting and Unquoting::). You may want to do the same for consistency's sake. Be careful when writing handlers that modify element state, or read state that packet processing can modify. On an SMP machine, a handler may be called on one processor while packets are passing through the router on another processor. Furthermore, multiple read handlers and safe LLRPCs (*note LLRPC Overview::) may be active simultaneously on different processors. Write handlers are serialized with respect to other handlers and LLRPCs (but not packet processing). That is, no other handler or LLRPC will proceed while a write handler is active.  File: click.info, Node: Adding Handlers, Next: Default Handlers, Prev: Read and Write Handler Overview, Up: Handlers 6.2.2 Adding Handlers --------------------- Use `Element''s `add_read_handler' and `add_write_handler' methods to add handlers for an element. You will generally call these methods only from within your element's `add_handlers' method, although nothing prevents you from adding handlers at any time. -- Method on Element: void add_read_handler (const String &NAME, ReadHandler FUNC, void *THUNK) Adds a read handler named NAME for this element. When the handler is accessed, FUNC will be called with `this' and THUNK as parameters. -- Method on Element: void add_write_handler (const String &NAME, WriteHandler FUNC, void *THUNK) Adds a write handler named NAME for this element. When the handler is accessed, FUNC will be called with the relevant data, `this', THUNK, and an `ErrorHandler' as parameters. To create a read/write handler, call `add_read_handler' and `add_write_handler' and supply the same handler name. These methods simply forward their requests to static `add_read_handler' and `add_write_handler' methods on the `Router' class. Call those methods directly to add handlers to other elements, or to add global handlers. -- Static Method on Router: void add_read_handler (const Element *ELEMENT, const String &NAME, ReadHandler FUNC, void *THUNK) -- Static Method on Router: void add_write_handler (const Element *ELEMENT, const String &NAME, WriteHandler FUNC, void *THUNK) Adds a read or write handler for ELEMENT, or a global read or write handler if ELEMENT is null. The handler is named NAME. The `change_handler_flags' method lets you change a handler's flags word (*note Handler Objects::). -- Static Method on Router: void change_handler_flags (Element *ELEMENT, const String &NAME, uint32_t CLEAR_FLAGS, uint32_t SET_FLAGS) Changes the flags for ELEMENT's NAME handler, or the global NAME handler if ELEMENT is null. The flags are changed by first clearing the bits set in CLEAR_FLAGS, then setting the bits set in SET_FLAGS. This method fails and returns -1 when the specified handler does not exist; otherwise, it returns 0.  File: click.info, Node: Default Handlers, Next: Accessing Handlers Internally, Prev: Adding Handlers, Up: Handlers 6.2.3 Default Read and Write Handlers ------------------------------------- Every element automatically provides five handlers, `class', `name', `config', `ports', and `handlers'. There is no need to add these handlers yourself. The default handlers behave as follows: `class' Returns the element's class name, as returned by `class_name()', followed by a newline. Example result: "ARPQueriern". `name' Returns the element's name, as returned by `id()', followed by a newline. Example result: "arpq_0n". `config' Returns the element's configuration string. If the configuration string does not end in newline, the hander appends a newline itself. Example result: "18.26.7.1, 00:00:C0:4F:71:EFn". If `can_live_reconfigure' returns true, `config' is also a write handler, and writing to it reconfigures the element. `ports' Returns a multi-line string describing the element's ports and what they are connected to. The string has the form M input[s] ... M input port descriptions, one per line ... N output[s] ... N output port descriptions, one per line ... Each port description lists the port's processing type, a dash, and then a comma-separated list of all the ports to which this port is connected. The processing type is either `push' or `pull'; formerly agnostic ports are indicated by a trailing tilde (`push~' or `pull~'). Example result: 1 input push~ - Strip@2 [0] 2 outputs push~ - [0] GetIPAddress@4 push - [0] Print@7 If Click was compiled with statistics collection enabled, the dash on each line is replaced by a packet count. `handlers' Returns a string listing the element's visible handlers, one per line. Each line contains the handler name, a tab, and then either `r', `w', or `rw', depending on whether the handler is read-only, write-only, or read/write. Example result for an `InfiniteSource' element, which has many handlers: scheduled r tickets r reset w count r active rw burstsize rw limit rw data rw handlers r ports r config rw name r class r  File: click.info, Node: Accessing Handlers Internally, Next: LLRPC Overview, Prev: Default Handlers, Up: Handlers 6.2.4 Accessing Handlers Internally ----------------------------------- Element handlers are stored in the relevant `Router' as objects of type `Router::Handler'. (This design allows handler objects to be shared between elements when possible.) Handlers are often referred to by index; indexes between 0 and `Router::FIRST_GLOBAL_HANDLER - 1' refer to element handlers, while indexes above `Router::FIRST_GLOBAL_HANDLER' refer to global handlers. Indexes less than 0 are used for error returns, such as nonexistent handlers. `Router' methods translate between handler indexes and `Router::Handler' objects, and find handlers or handler indexes given handler names. * Menu: * Handler Objects:: * Handlers By Name or Index::  File: click.info, Node: Handler Objects, Next: Handlers By Name or Index, Prev: Accessing Handlers Internally, Up: Accessing Handlers Internally 6.2.4.1 The Router::Handler Type ................................ The `Router::Handler' type allows you to check a handler's properties and call the handler. All of its methods are `const'; you must go through `Router' to change a handler's properties. `Router::Handler' objects do not contain element references, since they are shared among elements. That means you can't easily find the element (if any) to which a particular `Router::Handler' is attached. -- Method on Router::Handler: const String & name () const Returns the handler's name. -- Method on Router::Handler: uint32_t flags () const Returns the handler's flags as an integer. The lower bits of the flags word are reserved for the system, and four bits are reserved for drivers, but the upper bits (at least 16) are left uninterpreted, and may be used by elements. The first user flag bit is called `Router::Handler::USER_FLAG_0'; its position in the word equals `Router::Handler::USER_FLAG_SHIFT'. To change a handler's flags, use the `Router::change_handler_flags' method (*note Changing Handler Flags::). -- Method on Router::Handler: bool readable () const Returns true iff this handler is readable. -- Method on Router::Handler: bool read_visible () const Returns true iff this handler is readable, and that read handler should be externally visible. Drivers and the ControlSocket element use `read_visible' rather than `readable' when deciding whether to tell the user that a read handler exists. Inter-element communication within the router, however, may use `readable' rather than `read_visible'. -- Method on Router::Handler: bool writable () const -- Method on Router::Handler: bool write_visible () const The analogous methods for write handlers. -- Method on Router::Handler: bool visible () const Equivalent to `read_visible() || write_visible()'. -- Method on Router::Handler: String unparse_name (Element *ELEMENT) const Returns the handler's name, including its attached element's name if ELEMENT is non-null. For example, calling `unparse_name' on element `e''s `foo' handler would return `e.foo', while calling it on a global `bar' handler would return `bar'. -- Static Method on Router::Handler: String unparse_name (Element *ELEMENT, const String &NAME) Returns a string representing ELEMENT's hypothetical NAME handler, or the global NAME handler if ELEMENT is null. -- Method on Router::Handler: String call_read (Element *ELEMENT) const Calls this read handler on ELEMENT and returns the result. Do not use this method unless you know the handler is `readable()'. -- Method on Router::Handler: int call_write (const String &DATA, Element *ELEMENT, ErrorHandler *ERRH) const Calls this write handler on ELEMENT, passing it DATA and ERRH, and returns the result. Do not use this method unless you know the handler is `writable()'.  File: click.info, Node: Handlers By Name or Index, Prev: Handler Objects, Up: Accessing Handlers Internally 6.2.4.2 Handlers By Name or Index ................................. These `Router' methods locate handlers by name, returning either a pointer to a handler object or a handler index. The methods are static to allow access to global handlers outside the context of a running router. -- Static Method on Router: const Router::Handler * handler (const Element *ELEMENT, const String &NAME) Returns a pointer to the handler object for ELEMENT's handler named NAME, or null if no such handler exists. ELEMENT may be null, in which case the method looks for a global handler named NAME. *Caution*: Handler pointers returned by `Router::handler' and similar methods should be treated as transient, since they may become invalid when new handlers are added. -- Static Method on Router: int hindex (const Element *ELEMENT, const String &NAME) Like `Router::handler', above, but returns an integer handler index for the named handler, or a negative number if no such handler exists. All valid handler indexes are nonnegative. -- Static Method on Router: const Router::Handler * handler (const Router *ROUTER, int HINDEX) Returns ROUTER's handler object corresponding to HINDEX, or a null pointer if HINDEX is invalid with respect to ROUTER. There are three possibilities: (1) HINDEX coresponds to a valid global handler, which is returned. In this case, ROUTER need not be valid. (2) HINDEX corresponds to a valid local handler in class ROUTER, which is returned. (3) Otherwise, a null pointer is returned. -- Static Method on Router: const Router::Handler * handler (const Element *ELEMENT, int HINDEX) Convenience function equivalent to `handler(ELEMENT->router(), HINDEX)'. Note that HINDEX need not refer to one of ELEMENT's handlers. -- Method on Router: const Router::Handler * handler (int HINDEX) const Convenience function equivalent to `handler(this, HINDEX)'. Finally, the `element_hindexes' static method returns all the handler indices that apply to a given element. -- Static Method on Router: void element_hindexes (const Element *ELEMENT, Vector &RESULTS) Appends to RESULTS all the handler indexes for ELEMENT's handlers, or all global handlers if ELEMENT is null.  File: click.info, Node: LLRPC Overview, Prev: Accessing Handlers Internally, Up: Handlers 6.2.5 LLRPC Overview --------------------  File: click.info, Node: Configuration Strings, Next: Tasks, Prev: Element Runtime, Up: Top 7 Configuration Strings *********************** * Menu: * Config String Structure:: * Quoting and Unquoting:: * Config String Splitting:: * Parsing Functions:: * cp_va::  File: click.info, Node: Config String Structure, Next: Quoting and Unquoting, Prev: Configuration Strings, Up: Configuration Strings 7.1 Structure ============= Configuration strings consist of a list of comma-separated "arguments". For example, this configuration string has three arguments, `a', `b', and `c': a, b , c Leading and trailing whitespace is trimmed from each argument. Configuration strings can contain two kinds of "comments" and three kinds of "quoted strings". Comments let you document a configuration string; they behave like spaces. With quoted strings, you can protect special characters like whitespace, commas, and comment-starting sequences from interpretation. `//' comments Begins with two adjacent slashes, `//', and continues up to and including the next end-of-line (`\n', `\r', or `\r\n'). Comment starters (`//' and `/*') and the quote sequences (`'', `"', and `\<') have no special meaning inside `//' comments. `/* ... */' comments Begins with slash-star, `/*', and continues up to and including the next star-slash, `*/'. Comment starters (`/*' and `//') and the quote sequences (`'', `"', and `\<') have no special meaning inside `/*' comments. Single-quoted strings `' ... '' Begins with a single-quote character `'' and continues up to the next single quote. Comments, double quotes, and backslashes have no special meaning inside single quotes. There is no way to include a single quote in a single-quoted string. Double-quoted strings `" ... "' Begins with a double-quote character `"' and continues up to the next unescaped double quote. Backslash `\' acts as an escape character inside double quotes, as in C. Click's escape sequences are described below. Comments and single quotes have no special meaning inside double quotes. `\<' retains its usual meaning, however. Hex strings `\< ... >' The `\<' sequence begins a string of hexadecimal digits terminated by `>'. Each pair of digits expands to the corresponding character value. For example, `\<48454c4c4F>' expands to `HELLO'. Whitespace and comments (either `//' or `/*' style) may be arbitrarily interleaved with the hex digits; any `>' characters inside comments are ignored. Characters other than whitespace, hex digits, comments, and `>' should not appear inside a hex string. Hex strings may be placed within double-quoted strings. Escape Sequences ................ Most of Click's escape sequences are borrowed from C, and behave the same way. The `\< ... >' escape sequence is new, however. `\' A backslash followed by an end-of-line sequence--`\n', `\r', or `\r\n'--is removed from the string. This string "a\ b" is equivalent to "ab". `\a', `\b', `\t', `\n', `\v', `\f', `\r' These escape sequences produce the characters with decimal ASCII values 7, 8, 9, 10, 11, 12, and 13, respectively. `\\', `\"', `\'', `\$' These escape sequences expand to a literal backslash, double quote, single quote, and dollar sign, respectively. `\<1 TO 3 OCTAL DIGITS>' A backslash followed by 1 to 3 octal digits (`0' ... `7') expands to the character with that octal value. For example, `\046' expands to `&'. `\x' `\x' followed by an arbitrary number of hexadecimal digits expands to the single character whose value equals the lower 8 bits of that number. Thus, `\x45' and `\x94839E89DB00ACF45' both expand to `E'. `\< >' `\<' introduces a hex string, as described above. Any other escape sequence `\' is an error. Currently, such sequences expand to `', but their semantics may eventually change.  File: click.info, Node: Quoting and Unquoting, Next: Config String Splitting, Prev: Config String Structure, Up: Configuration Strings 7.2 Quoting and Unquoting ========================= These functions interpret quote sequences and comments in configuration strings. `cp_uncomment' removes comments and leading and trailing whitespace, but does not expand quote sequences. `cp_unquote' both removes comments and expands quote sequences. Finally, `cp_quote' protects special characters, such as whitespace and commas, within double quotes. -- Function: String cp_uncomment (const String &STR) Replaces any comments in STR by single spaces, then removes any leading and trailing whitespace and returns the result. -- Function: String cp_unquote (const String &STR) Replaces any comments in STR by single spaces, then removes any leading and trailing whitespace. Finally, replaces every quoted string by its expansion and returns the result. -- Function: String cp_quote (const String &STR, bool ALLOW_NEWLINES = false) Returns a quoted version of STR. Any whitespace, commas, comments, quote sequences, and non-ASCII characters in STR are protected within double quotes. If ALLOW_NEWLINES is true, then the result may contain newline characters (within double quotes); otherwise, any newline characters in STR are replaced by `\n' sequences. The returned result is never empty (unless Click has run out of memory). If STR is the empty string, `cp_quote' will return `""' (a string containing two double quotes). For example: cp_uncomment("/* blah */ "quote"/*xx*/<2 c>") => ""quote" <2 c>" cp_unquote("/* blah */ "quote"/*xx*/<2 c>") => "quote ," cp_quote("quote ,") => ""quote ,""  File: click.info, Node: Config String Splitting, Next: Parsing Functions, Prev: Quoting and Unquoting, Up: Configuration Strings 7.3 Splitting and Combining =========================== -- Function: void cp_argvec (const String &STR, Vector &CONF) Splits STR into arguments by breaking it at every comma not part of a quote or comment. Comments and leading and trailing whitespace are removed from each argument, as by `cp_uncomment', and the results are pushed, in order, onto the vector CONF. If STR contains only whitespace and comments, nothing is pushed onto CONF. -- Function: void cp_spacevec (const String &STR, Vector &CONF) Splits STR into arguments by breaking it at every sequence of whitespace characters and/or comments. Leading and trailing whitespace is removed from each argument, as by `cp_uncomment', and the results are pushed, in order, onto the vector CONF. If STR contains only whitespace and comments, nothing is pushed onto CONF. For example: cp_argvec("x/* ,,, */ab" c", , ','", VEC) => 3 arguments: "x ab" c"" "" "','" cp_argvec("/* blah, blah, blah, blah */ ", VEC) => 0 arguments cp_argvec("/* blah, blah, blah, blah */, ", VEC) => 2 empty arguments: "" "" cp_spacevec("x/* ,,, */yz" w" """, VEC) => 4 arguments: "x" "yz" w"" "" """" cp_spacevec("/* blah, blah, blah, blah */ ", VEC) => 0 arguments cp_spacevec("/* blah, blah, blah, blah */, ", VEC) => 1 argument: "," Since the `const Vector &CONF' arguments passed to elements' `configure' methods have been processed by `cp_argvec', there is no need to process them with `cp_uncomment'. The `cp_unargvec' and `cp_unspacevec' functions take a vector of arguments and combine them into a single string. These functions do not protect their arguments by quoting; use `cp_quote' explicitly when necessary (*note Quoting and Unquoting::). If the arguments are properly quoted, then calling `cp_argvec(cp_unargvec(CONF), CONF2)' or `cp_spacevec(cp_unspacevec(CONF), CONF2)' will produce a new vector of arguments equal to the original. -- Function: String cp_unargvec (const Vector &CONF) Returns a string consisting of the elements of CONF separated by `, '. -- Function: String cp_unspacevec (const Vector &CONF) Returns a string consisting of the elements of CONF separated by ` '. For example: cp_unargvec(["x ab" c"", "", "','"]) => "x ab" c", , ','" cp_unargvec(["whatever"]) => "whatever" cp_unargvec([ ]) => "" cp_unargvec([",", ","]) (Probably a mistake: caller should have quoted the arguments!) => ",, ," cp_unspacevec(["xy" z"", "", "','"]) => "xy" z" ','"  File: click.info, Node: Parsing Functions, Next: cp_va, Prev: Config String Splitting, Up: Configuration Strings 7.4 Parsing Functions ===================== Click's "parsing functions" parse strings into various kinds of data, such as integers, fixed-point real numbers, and IP addresses. Parsing functions follow some consistent conventions: * Their first argument, `const String &STR', contains the string to be parsed. * At least one additional argument points to a location where any parsed result should be stored. These RESULT arguments have pointer type. * Their return type is `bool'. * They return true if and only if parsing succeeds. * The values pointed to by the RESULT arguments are modified only if parsing succeeds. * Most parsing functions expect to parse the entire supplied string. Any extraneous characters, such as trailing whitespace, cause parsing to fail. * Parsing functions never report errors to any source; they simply return false when parsing fails. * Menu: * Parsing Strings:: * Parsing Booleans:: * Parsing Integers:: * Parsing Reals:: * Parsing IP Addresses:: * Parsing IPv6 Addresses:: * Parsing Ethernet Addresses:: * Parsing Elements:: * Parsing Handlers:: * Parsing Miscellaneous::  File: click.info, Node: Parsing Strings, Next: Parsing Booleans, Prev: Parsing Functions, Up: Parsing Functions 7.4.1 Strings and Words ----------------------- These functions parse strings from their input strings. The resulting strings may be arbitrary (`cp_string') or constrained (`cp_word', `cp_keyword'). As noted above (*note Parsing Functions::), the functions have `bool' return type; they return true if parsing was successful. -- Parsing Function: bool cp_string (const String &STR, String *RESULT, String *REST = 0) Parses a string from the beginning of STR and stores the result in `*RESULT'. The parsed string may contain single and double quotes and hex strings ("< ... >"), which are processed as by `cp_unquote' (*note Quoting and Unquoting::). If the REST argument is null and STR contains any unquoted whitespace, then parsing will fail. If REST is not null, then parsing stops at the first unquoted whitespace character, and any leftover portion of STR is stored in `*REST'. For example: cp_string(""a b c d"", RESULT) => true *RESULT = "a b c d" cp_string("", RESULT) => false cp_string("""", RESULT) => true *RESULT = "" cp_string(""a b c d"", RESULT) => false (STR began with an unquoted space) cp_string(""a b c d" e", RESULT) => false (STR contained an unquoted space) cp_string(""a b c d" e", RESULT, REST) => true *RESULT = "a b c d", *REST = "e" -- Parsing Function: bool cp_word (const String &STR, String *RESULT, String *REST = 0) Parses a word from the beginning of STR and stores the result in `*RESULT'. A "word" is a string that does not contain whitespace, control characters, non-ASCII characters (with values 127 or higher), or special characters (`'', `"', `\', or `,'). STR may contain single and double quotes and hex strings ("< ... >"), which are processed as by `cp_unquote' (*note Quoting and Unquoting::). The unquoted result must not contain quote marks, whitespace, or other special characters, however. Returns true if and only if STR contained a valid word. If the REST argument is null and STR contains any unquoted whitespace, then parsing will fail. If REST is not null, then parsing stops at the first unquoted whitespace character, and any leftover portion of STR is stored in `*REST'. For example: cp_word("word", RESULT) => true *RESULT = "word" cp_word(""wor"<64>", RESULT) => true *RESULT = "word" cp_word(""wor d"", RESULT) => false (processed string contained a space) -- Parsing Function: bool cp_keyword (const String &STR, String *RESULT, String *REST = 0) Parses a keyword from the beginning of STR and stores the result in `*RESULT'. A "keyword" is a string consisting of one or more letters, numbers, underscores (`_'), periods (`.'), and colons (`:'). Keywords may not contain quoted substrings--`'', `"', and `\<' are not allowed. Returns true if and only if STR contained a valid keyword. If the REST argument is null and STR contains any unquoted whitespace, then parsing will fail. If REST is not null, then parsing stops at the first unquoted whitespace character, and any leftover portion of STR is stored in `*REST'. For example: cp_keyword("word", RESULT) => true *RESULT = "word" cp_keyword(""wor"<64>", RESULT) => false (quotes not allowed in keywords) To summarize: * `cp_string' and `cp_word' allow quoted substrings; `cp_keyword' does not. * `cp_string' results may contain arbitrary characters; `cp_word' and `cp_keyword' restrict the characters allowed in their results. * If `cp_keyword(STR, RESULT)' is true, then `cp_word(STR, RESULT)' is true. * If `cp_word(STR, RESULT)' is true, then `cp_string(STR, RESULT)' is true.  File: click.info, Node: Parsing Booleans, Next: Parsing Integers, Prev: Parsing Strings, Up: Parsing Functions 7.4.2 Booleans -------------- The `cp_bool' function parses a string into a Boolean value. -- Parsing Function: bool cp_bool (const String &STR, bool *RESULT) Parses STR into a Boolean value and stores the result in `*RESULT'. Allowable Boolean strings are as follows: `0', `false', `no' `*RESULT' becomes false. `1', `true', `yes' `*RESULT' becomes true. The words must be all lower case.  File: click.info, Node: Parsing Integers, Next: Parsing Reals, Prev: Parsing Booleans, Up: Parsing Functions 7.4.3 Integers -------------- `cp_integer' and `cp_unsigned' parse strings into `int' and `unsigned int' values, respectively. Each function comes in two variants, one with a BASE parameter and one without. If BASE is 0 or unspecified, then the function examines the string to determine the relevant base. Strings beginning with `0x' or `0X' (after the optional sign) use base 16; other strings beginning with `0' use base 8; and all other strings use base 10. Nonzero BASEs must be at least 2 and no more than 36. The functions accept the same strings as C's `strtol' function, except that `strtol' will accept leading whitespace and trailing characters that are not part of the parsed integer. The string should contain, in order: * An optional `+' or `-' sign. (The `cp_unsigned' functions do not accept a minus sign.) * An optional `0x' or `0X', if the BASE argument is 0 or 16. * One or more alphanumeric digits. The maximum allowed digit is specified by BASE. If a string contains a valid number too large (or small) to represent, the parsing function sets `cp_errno' to `CPE_OVERFLOW', stores the largest (or smallest) allowable number in RESULT, and returns true. If a function succeeds without overflow, `cp_errno' is set to `CPE_OK'. -- Parsing Function: bool cp_integer (const String &STR, int *RESULT) -- Parsing Function: bool cp_integer (const String &STR, int BASE, int *RESULT) Parses STR into a signed integer in base BASE and stores the result in `*RESULT'. Detects overflow on numbers greater than 2147483647 or less than -2147483648. -- Parsing Function: bool cp_unsigned (const String &STR, unsigned *RESULT) -- Parsing Function: bool cp_unsigned (const String &STR, int BASE, unsigned *RESULT) Parses STR into an unsigned integer in base BASE and stores the result in `*RESULT'. Detects overflow on numbers greater than 4294967295. For example: cp_integer(`-0x8000', RESULT) => true *RESULT = -32768, cp_errno = CPE_OK cp_integer(`-0x8000 ', RESULT) => false (trailing whitespace not allowed) cp_unsigned(`3333333333333333', 4, RESULT) => true *RESULT = 4294967295, cp_errno = CPE_OK cp_unsigned(`33333333333333333', 4, RESULT) => true *RESULT = 4294967295, cp_errno = CPE_OVERFLOW  File: click.info, Node: Parsing Reals, Next: Parsing IP Addresses, Prev: Parsing Integers, Up: Parsing Functions 7.4.4 Real Numbers ------------------ Several functions parse real numbers into fixed-point integers. (Some drivers, such as the Linux kernel driver, can't use floating point arithmetic, so `double's are not allowed.) Each function takes an integer argument that determines how many digits of fraction the result should have. Since the result is a single fixed-point number, the more digits of fraction in the result, the fewer digits are available for the integer part. You may request binary or decimal digits of fraction. The `real10' function variants use decimal digits, while the `real2' variants use binary digits: bits. For example, cp_real10(`1', 2, RESULT), which parses the string `1' with 2 decimal digits of fraction, yields the number 100 (10^2). The similar call to a binary-digit function, cp_real2(`1', 2, RESULT), yields 4 (2^2). Parsing `0.5' with the same functions yields 50 and 2, respectively. A real number string should contain, in order: * An optional `+' or `-' sign. (The `unsigned' variants do not accept minus signs.) * An optional sequence of decimal digits representing the integer part. * An optional fraction point `.'. * An optional sequence of decimal digits representing the fraction part. * An optional "exponent"--an `E' or `e' character followed by a signed decimal integer. The string must contain at least one digit in either the integer part or the fraction part. All the parsing functions round to the nearest relevant number. For example, cp_real10(`0.59', 1, RESULT) stores 6 in RESULT, since 0.59 rounded to one digit of fraction is 0.6. If a string contains a real number too large in magnitude for the specified format, the parsing function will set `cp_errno' to `CPE_OVERFLOW', store the largest representable number in RESULT, and return true. For example, the largest number representable as an unsigned integer with 16 bits of fraction is 65535.99998, which has the bit pattern 0xFFFFFFFF. Therefore, cp_unsigned_real2(`65536', 16, RESULT) stores 0xFFFFFFFF in RESULT and sets `cp_errno' to `CPE_OVERFLOW'. If there was no overflow or other error, `cp_errno' is set to `CPE_OK'. -- Parsing Function: bool cp_unsigned_real10 (const String &STR, int FRAC_DIGITS, unsigned *RESULT) Parses STR into an unsigned real number, and stores the result in RESULT as an unsigned integer with FRAC_DIGITS decimal digits of fraction. -- Parsing Function: bool cp_real10 (const String &STR, int FRAC_DIGITS, int *RESULT) Parses STR into a unsigned real number, and stores the result in RESULT as an integer with FRAC_DIGITS decimal digits of fraction. -- Parsing Function: bool cp_unsigned_real2 (const String &STR, int FRAC_BITS, unsigned *RESULT) Parses STR into an unsigned real number, and stores the result in RESULT as an unsigned integer with FRAC_BITS bits of fraction. -- Parsing Function: bool cp_real2 (const String &STR, int FRAC_BITS, int *RESULT) Parses STR into a real number, and stores the result in RESULT as an integer with FRAC_BITS bits of fraction. The fixed-point real parsing functions are built on a lower-level variant that returns the integer and fraction parts in two different `unsigned int's. -- Parsing Function: bool cp_unsigned_real10 (const String &STR, int FRAC_DIGITS, unsigned *INT_RESULT, unsigned *FRAC_RESULT) Parses STR into an unsigned real number and stores the result in INT_RESULT and FRAC_RESULT. INT_RESULT holds the integral part of the resulting real, while FRAC_RESULT holds its fractional part as a fixed-point number with FRAC_DIGITS decimal digits of fraction. FRAC_RESULT is always less than 10^FRAC_DIGITS. For example: cp_unsigned_real10(`10.952', 3, INT_RESULT, FRAC_RESULT) => true *INT_RESULT = 10, *FRAC_RESULT = 952 cp_unsigned_real10(`10.9526', 3, INT_RESULT, FRAC_RESULT) => true *INT_RESULT = 10, *FRAC_RESULT = 953 (note rounding) cp_unsigned_real10(`10.9996', 3, INT_RESULT, FRAC_RESULT) => true *INT_RESULT = 11, *FRAC_RESULT = 0  File: click.info, Node: Parsing IP Addresses, Next: Parsing IPv6 Addresses, Prev: Parsing Reals, Up: Parsing Functions 7.4.5 IP Addresses ------------------ The `cp_ip_address' functions parse strings into IP addresses. Related `cp_ip_prefix' and `cp_ip_address_set' functions parse strings into IP address/netmask pairs and sets of IP addresses, respectively. Parsable IP addresses are simply dotted quads like `18.26.4.44'. IP prefixes may be specified using CIDR notation, such as `18.26.4.44/16'; as explicit address/netmask pairs, such as `18.26.4.44/255.255.0.0'; or, optionally, as bare IP addresses, such as `18.26.4.44' (which means `18.26.4.44/255.255.255.255'). Besides these conventional forms, the `cp_ip' functions understand user-defined shorthand names for IP addresses and prefixes. Shorthand names are router-specific; users define them with `AddressInfo' elements. Furthermore, a name's meaning is dependent on its context: an `AddressInfo' inside a compound element defines shorthand names local to that compound element. The `cp_ip' functions, then, take optional `Element *CONTEXT' arguments to specify any router and compound-element context. If a `cp_ip' function's CONTEXT argument is null, it will parse only the conventional IP address forms described above. -- Parsing Function: bool cp_ip_address (const String &STR, unsigned char *RESULT, Element *CONTEXT = 0) -- Parsing Function: bool cp_ip_address (const String &STR, IPAddress *RESULT, Element *CONTEXT = 0) Parses STR into an IP address and stores the result in `*RESULT'. CONTEXT supplies any element context. -- Parsing Function: bool cp_ip_prefix (const String &STR, unsigned char *RESULT_ADDR, unsigned char *RESULT_MASK, Element *CONTEXT = 0) -- Parsing Function: bool cp_ip_prefix (const String &STR, IPAddress *RESULT_ADDR, IPAddress *RESULT_MASK, Element *CONTEXT = 0) Parses STR into an IP address/netmask pair and stores the resulting address in `*RESULT_ADDR', and the resulting netmask in `*RESULT_MASK'. The resulting address is not pre-masked by the resulting mask. For example, cp_ip_prefix(`18.26.4.44/16', RESULT_ADDR, RESULT_MASK) stores 18.26.4.44 in RESULT_ADDR, not 18.26.0.0. Bare addresses, such as `18.26.4.44', are never allowed. -- Parsing Function: bool cp_ip_prefix (const String &STR, unsigned char *RESULT_ADDR, unsigned char *RESULT_MASK, bool ALLOW_BARE_ADDR, Element *CONTEXT = 0) -- Parsing Function: bool cp_ip_prefix (const String &STR, IPAddress *RESULT_ADDR, IPAddress *RESULT_MASK, bool ALLOW_BARE_ADDR, Element *CONTEXT = 0) Parses STR into an IP address/netmask pair and stores the resulting address in `*RESULT_ADDR' and netmask in `*RESULT_MASK'. Bare addresses, such as `18.26.4.44', are allowed if and only if ALLOW_BARE_ADDR is true. The netmask corresponding to a bare address is 255.255.255.255. Finally, the `cp_ip_address_list' function parses a whitespace-separated list of IP addresses into to an `IPAddressList' object. -- Parsing Function: bool cp_ip_address_list (const String &STR, IPAddressList *RESULT, Element *CONTEXT = 0) Parses STR into a list of IP addresses and stores the result in `*RESULT'. STR must be a whitespace-separated list of IP addresses, which can take any of the forms accepted by `cp_ip_address'.  File: click.info, Node: Parsing IPv6 Addresses, Next: Parsing Ethernet Addresses, Prev: Parsing IP Addresses, Up: Parsing Functions 7.4.6 IPv6 Addresses -------------------- The `cp_ip6_address' functions parse strings into IPv6 addresses. Related `cp_ip6_prefix' functions parse strings into IPv6 address/netmask pairs. Parsable IPv6 addresses and prefixes take any of the forms described in RFC 2373, IP Version 6 Addressing Architecture. A nonabbreviated address consists of eight colon-separated 16-bit hexadecimal numbers, as in `1080:0:0:0:8:800:200C:417A'. Strings of zero bits may be abbreviated with two colons, as in `1080::8:800:200C:417A', and an address may end in an embedded IPv4 address, as in `::13.1.68.3' and `::FFFF:129.144.52.38'. IPv6 prefixes are written in `ADDRESS/PREFIXLEN' form, like `12AB:0:0:CD30::/60'. Click also supports `ADDRESS/NETMASK' syntax, where NETMASK is an IPv6 address. NETMASK must correspond to some contiguous prefix, however: `12AB:0:0:CD30::/60' and `12AB:0:0:CD30::/FFFF:FFFF:FFFF:FFF0::' are equivalent, but `12AB:0:0:CD30::/FFFF::1' is illegal. Analogously to the `cp_ip' functions (*note Parsing IP Addresses::), the `cp_ip6' functions understand `AddressInfo''s shorthand names for IPv6 addresses, and take optional `Element *CONTEXT' arguments to specify any router and compound-element context. -- Parsing Function: bool cp_ip6_address (const String &STR, unsigned char *RESULT, Element *CONTEXT = 0) -- Parsing Function: bool cp_ip6_address (const String &STR, IP6Address *RESULT, Element *CONTEXT = 0) Parses STR into an IPv6 address and stores the result in `*RESULT'. CONTEXT supplies any element context. -- Parsing Function: bool cp_ip6_prefix (const String &STR, unsigned char *RESULT_ADDR, int *RESULT_PREFIX_LEN, bool ALLOW_BARE_ADDR, Element *CONTEXT = 0) -- Parsing Function: bool cp_ip6_prefix (const String &STR, IP6Address *RESULT_ADDR, int *RESULT_PREFIX_LEN, bool ALLOW_BARE_ADDR, Element *CONTEXT = 0) Parse STR into an IPv6 address/prefix length pair and stores the resulting address in `*RESULT_ADDR', and the resulting prefix length in `*RESULT_PREFIX_LEN'. Bare addresses, such as `1080::8:800:200C:417A', are allowed if and only if ALLOW_BARE_ADDR is true. The prefix length corresponding to a bare address is 128. -- Parsing Function: bool cp_ip6_prefix (const String &STR, unsigned char *RESULT_ADDR, unsigned char *RESULT_MASK, bool ALLOW_BARE_ADDR, Element *CONTEXT = 0) -- Parsing Function: bool cp_ip6_prefix (const String &STR, IP6Address *RESULT_ADDR, IP6Address *RESULT_MASK, bool ALLOW_BARE_ADDR, Element *CONTEXT = 0) Parse STR into an IPv6 address/prefix length pair and stores the resulting address in `*RESULT_ADDR', and the netmask corresponding to the resulting prefix length in `*RESULT_MASK'. Bare addresses are allowed if and only if ALLOW_BARE_ADDR is true.  File: click.info, Node: Parsing Ethernet Addresses, Next: Parsing Elements, Prev: Parsing IPv6 Addresses, Up: Parsing Functions 7.4.7 Ethernet Addresses ------------------------ The `cp_ethernet_address' functions parse strings into Ethernet addresses. A parsable Ethernet address consists of six colon-separated 8-bit hexadecimal numbers, as in `0:2:B3:06:36:EE'. Analogously to the `cp_ip' functions (*note Parsing IP Addresses::), the `cp_ethernet_address' functions understand `AddressInfo''s shorthand names for Ethernet addresses, and take optional `Element *CONTEXT' arguments to specify any router and compound-element context. -- Parsing Function: bool cp_ethernet_address (const String &STR, unsigned char *RESULT, Element *CONTEXT = 0) -- Parsing Function: bool cp_ethernet_address (const String &STR, EtherAddress *RESULT, Element *CONTEXT = 0) Parses STR into an Ethernet address and stores the result in `*RESULT'. CONTEXT supplies any element context.  File: click.info, Node: Parsing Elements, Next: Parsing Handlers, Prev: Parsing Ethernet Addresses, Up: Parsing Functions 7.4.8 Elements -------------- `cp_element' parses an element name into a pointer to an element in some router configuration. It differs from other parsing functions in two important ways. First, it returns its result, or a null pointer on error; parsing functions store their results in some pointer. Second, it reports errors to the supplied `ErrorHandler'. The `cp_element' function follows lexical scoping rules when called from a compound element: it will check for components of that compound element first. For instance, say you've called `cp_element' on the string `e'. Normally, this would check the router for an element named, simply, `e'. However, if called within a compound element `x', `cp_element' will first check for an element named `x/e' before looking for the global `e' element. The function uses its CONTEXT argument, an element pointer, to determine both the relevant router object and any compound element context. More explicitly, the `cp_element' function uses the following procedure to search for an element named STR: 1. Set PREFIX to `CONTEXT->id()'. 2. Remove the final component of PREFIX. 3. Search for an element named `PREFIXSTR' in `CONTEXT->router()'. If one is found, return it. 4. Otherwise, no element was found. If PREFIX is already empty, parsing fails; report an error to ERRH and return a null pointer. Otherwise, return to step 2. -- Function: Element * cp_element (const String &STR, Element *CONTEXT, ErrorHandler *ERRH) Returns a element named STR in CONTEXT's router configuration. STR is first processed as by `cp_unquote'. CONTEXT determines both the relevant router configuration and any compound element context. Returns a null pointer if no element is found; if ERRH is nonnull and no element is found, additionally reports an error to ERRH. A variant function does not perform a lexically scoped search, so its STR argument must contain a fully-qualified element name. -- Function: Element * cp_element (const String &STR, Router *ROUTER, ErrorHandler *ERRH) Returns a element named STR in ROUTER. STR is first processed as by `cp_unquote'. Returns a null pointer if no element is found; if ERRH is nonnull and no element is found, additionally reports an error to ERRH.  File: click.info, Node: Parsing Handlers, Next: Parsing Miscellaneous, Prev: Parsing Elements, Up: Parsing Functions 7.4.9 Handlers -------------- The `cp_handler' functions parse a handler specification, such as `e.config', into the relevant pair of element and handler ID. Unlike most other parsing functions, it can report errors to an `ErrorHandler', if one is supplied. Most handler specifications consists of an element name and a handler name separated by a period: `ELEMENT.HANDLER'. The simplest `cp_handler' function parses such a specification into an element pointer, corresponding to ELEMENT, and the handler name, HANDLER. Like `cp_element' (*note Parsing Elements::), `cp_handler' uses a lexically-scoped search to find the element corresponding to a given name. Click also supports a few global handlers, such as `config'. `cp_handler' will also parse global handler names, returning null for the element pointer. -- Parsing Function: bool cp_handler (const String &STR, Element *CONTEXT, Element **RESULT_ELEMENT, String *RESULT_HNAME, ErrorHandler *ERRH) Parses STR into a handler specification, storing the resulting element (if any) in `*RESULT_ELEMENT' and handler name in `*RESULT_HNAME'. STR is first processed as by `cp_unquote'. CONTEXT determines both the relevant router configuration and any compound element context. Returns true if and only if STR contained a valid handler specification whose element part named an actual element. Note that this function will not check whether `*RESULT_ELEMENT' actually has a handler named `*RESULT_HNAME'--or, for global handlers, whether the global handler `*RESULT_HNAME' actually exists. The other `cp_handler' variants ensure that the input string names an actual handler. These variants are useless until handlers are added to the router configuration. Therefore, they should be called in elements' `initialize' methods, not their `configure' methods, since handlers are not added until `initialize' time. -- Parsing Function: bool cp_handler (const String &STR, Element *CONTEXT, Element **RESULT_ELEMENT, int *RESULT_HID, ErrorHandler *ERRH) Parses STR into a handler specification, storing the resulting element in `*RESULT_ELEMENT' and handler ID in `*RESULT_HID'. This function just calls the simpler `cp_handler', above, then checks that the resulting element has the named handler. -- Parsing Function: bool cp_handler (const String &STR, Element *CONTEXT, bool NEED_READ, bool NEED_WRITE, Element **RESULT_ELEMENT, int *RESULT_HID, ErrorHandler *ERRH) Similar, but additionally checks for read and/or write handlers. If NEED_READ is true, then STR must name a valid read handler; if NEED_WRITE is true, then STR must name a valid write handler. Returns false if these checks aren't met.  File: click.info, Node: Parsing Miscellaneous, Prev: Parsing Handlers, Up: Parsing Functions 7.4.10 Miscellaneous -------------------- The `cp_seconds_as' and `cp_timeval' functions parse strings into time. -- Parsing Function: bool cp_seconds_as (int P, const String &STR, int *RESULT) Parses STR as a possibly fractional length of time in seconds. The returned RESULT is measured in (seconds * 10^-P); for example, if P is 3, then RESULT is measured in milliseconds, and `cp_seconds_as(3, "8", RESULT)' stores 8000 in `*RESULT'. STR may contain an optional time unit suffix. Valid units are `h' or `hr' for hours, `m'/`min' for minutes, `s'/`sec' for seconds, `ms'/`msec' for milliseconds, `us'/`usec' for microseconds, and `ns'/`nsec' for nanoseconds. For example, `cp_seconds_as(0, "1h", RESULT)' stores 3600 in `*RESULT'. Negative values are not allowed. -- Parsing Function: bool cp_seconds_as_milli (const String &STR, int *RESULT) -- Parsing Function: bool cp_seconds_as_micro (const String &STR, int *RESULT) Same as `cp_seconds_as(3, S, RESULT)' and `cp_seconds_as(6, S, RESULT)', respectively. -- Parsing Function: bool cp_timeval (const String &STR, struct timeval *RESULT) Parses STR as a `struct timeval' representing some number of seconds and microseconds. Textually, this looks like a nonnegative real number with 6 decimal digits of fraction. Stores the integer part of the result in `RESULT->tv_sec' and the fraction part in `RESULT->tv_usec'. Basically equivalent to `cp_unsigned_real10(STR, 6, 0, &RESULT->tv_sec, &RESULT->tv_usec)'.  File: click.info, Node: cp_va, Prev: Parsing Functions, Up: Configuration Strings 7.5 Parsing Argument Lists ========================== * Menu: * cp_va Concepts:: * cp_va Initialization::  File: click.info, Node: cp_va Concepts, Next: cp_va Initialization, Prev: cp_va, Up: cp_va 7.5.1 Concepts --------------  File: click.info, Node: cp_va Initialization, Prev: cp_va Concepts, Up: cp_va 7.5.2 Global Initialization --------------------------- The `cp_va' functions maintain some private global state--for example, a list of the data types they understand. You must explicitly initialize this state with `cp_va_static_initialize' before calling any other `cp_va' function. You can free this state, if you'd like, with `cp_va_static_cleanup'. -- Function: void cp_va_static_initialize () Call this function exactly once, at the beginning of the program, before calling any other `cp_va' functions. -- Function: void cp_va_static_cleanup () Call this function exactly once, at the end of the program. It is an error to call any `cp_va' function after calling `cp_va_static_cleanup'. *Constant* *Storage Arguments* `cpArgument' `String *RESULT' `cpString' `String *RESULT' `cpWord' `String *RESULT' `cpKeyword' `String *RESULT' `cpByte' `unsigned char *RESULT' `cpShort' `short *RESULT' `cpUnsignedShort' `unsigned short *RESULT' `cpInteger' `int *RESULT' `cpUnsigned' `unsigned *RESULT' `cpReal2' `int FRAC_BITS, int *RESULT' `cpUnsignedReal2' `int FRAC_BITS, unsigned *RESULT' `cpReal10' `int FRAC_DIGITS, int *RESULT' `cpUnsignedReal10' `int FRAC_DIGITS, unsigned *RESULT' `cpIPAddress' `IPAddress *RESULT' `cpIPPrefix' `IPAddress *RESULT_ADDRESS, IPAddress *RESULT_MASK' `cpIPAddressOrPrefix' `IPAddress *RESULT_ADDRESS, IPAddress *RESULT_MASK' `cpIPAddressList' `IPAddressList *RESULT' `cpEtherAddress' `EtherAddress *RESULT' `cpIP6Address' `IP6Address *RESULT' `cpIP6Prefix' `IP6Address *RESULT_ADDRESS, IP6Address *RESULT_MASK' `cpIP6AddressOrPrefix' `IP6Address *RESULT_ADDRESS, IP6Address *RESULT_MASK' `cpElement' `Element **RESULT' `cpHandlerName' `Element **RESULT_ELEMENT,' `String *RESULT_HNAME' `cpHandler' `Element **RESULT_ELEMENT, int *RESULT_HID' `cpReadHandler' `Element **RESULT_ELEMENT, int *RESULT_HID' `cpWriteHandler' `Element **RESULT_ELEMENT, int *RESULT_HID' `cpBool' `bool *RESULT' `cpSeconds' `int *RESULT' `cpSecondsAsMilli' `int *RESULT' `cpSecondsAsMicro' `int *RESULT' `cpTimeval' `struct timeval *RESULT' *Constant* *Corresponding Parsing Function* `cpArgument' `*RESULT = arg' `cpString' `cp_string(arg, RESULT)' `cpWord' `cp_string(arg, RESULT)' `cpKeyword' `cp_keyword(arg, RESULT)' `cpByte' `cp_unsigned(arg, &tmp)', check range, store in RESULT `cpShort' `cp_integer(arg, &tmp)', check range, store in RESULT `cpUnsignedShort' `cp_unsigned(arg, &tmp)', check range, store in RESULT `cpInteger' `cp_integer(arg, RESULT)' `cpUnsigned' `cp_unsigned(arg, RESULT)' `cpReal2' `cp_real2(arg, FRAC_BITS, RESULT)' `cpUnsignedReal2' `cp_unsigned_real2(arg, FRAC_BITS, RESULT)' `cpReal10' `cp_real10(arg, FRAC_DIGITS, RESULT)' `cpUnsignedReal10' `cp_unsigned_real10(arg, FRAC_DIGITS, RESULT)' `cpIPAddress' `cp_ip_address(arg, RESULT, context)' `cpIPPrefix' `cp_ip_prefix(arg, RESULT_ADDRESS, RESULT_MASK, false, context)' `cpIPAddressOrPrefix' `cp_ip_prefix(arg, RESULT_ADDRESS, RESULT_MASK, true, context)' `cpIPAddressList' `cp_ip_address_list(arg, RESULT, context)' `cpEtherAddress' `cp_ether_address(arg, RESULT, context)' `cpIP6Address' `cp_ip6_address(arg, RESULT, context)' `cpIP6Prefix' `cp_ip6_prefix(arg, RESULT_ADDRESS, RESULT_MASK, false, context)' `cpIP6AddressOrPrefix' `cp_ip6_prefix(arg, RESULT_ADDRESS, RESULT_MASK, false, context)' `cpElement' `cp_element(arg, context, RESULT)' `cpHandlerName' `cp_handler(arg, context, RESULT_ELEMENT, RESULT_HNAME)' `cpHandler' `cp_handler(arg, context, RESULT_ELEMENT, RESULT_HID)' `cpReadHandler' `cp_handler(arg, context, true, false, RESULT_ELEMENT, RESULT_HID)' `cpWriteHandler' `cp_handler(arg, context, false, true, RESULT_ELEMENT, RESULT_HID)' `cpBool' `cp_bool(arg, RESULT)' `cpSeconds' `cp_seconds_as(0, arg, RESULT)' `cpSecondsAsMilli' `cp_seconds_as(3, arg, RESULT)' `cpSecondsAsMicro' `cp_seconds_as(6, arg, RESULT)' `cpTimeval' `cp_timeval(arg, RESULT)'  File: click.info, Node: Tasks, Next: Timers, Prev: Configuration Strings, Up: Top 8 Tasks ******* Click schedules a router's CPU or CPUs with one or more "task queues". These queues are simply lists of "tasks", which represent functions that would like access to the CPU. Tasks are generally associated with elements. When scheduled, most tasks call some element's `run_task' method. Click tasks are represented by `Task' objects. An element that would like special access to a router's CPU should include and initialize a `Task' instance variable. Tasks are generally called very frequently, up to tens of thousands of times per second. For infrequent events, it is far more efficient to use timers than to use tasks; see *Note Timers::. Executing a task should not take a long time. The Click driver loop is not currently adaptive, so very long tasks can inappropriately delay timers and other periodic events. We may address this problem in a future release, but for now, keep tasks short. See the Doxygen documentation on class `Task' for more information. The `Task' class is defined in the `' header file. * Menu: * Task Initialization:: * Scheduling Tasks:: * Tickets:: * Task Thread Choice:: * Task Status:: * Task Handlers:: * Task Cleanup::  File: click.info, Node: Task Initialization, Next: Scheduling Tasks, Prev: Tasks, Up: Tasks 8.1 Task Initialization ======================= Task initialization is a two-step process. First, when a `Task' object is constructed, you must supply information about the function that it should call when it is scheduled. Second, when the router is initialized, you must initialize the task by supplying it with the relevant router. (You must initialize the task even if it will not be scheduled right away.) `Task' has two constructors. One of them asks the task to call an element's `run_task' method when scheduled; the other asks it to call an arbitrary function pointer. -- Constructor on Task: Task (Element *E) When this task is scheduled, call `E->run_task()'. -- Constructor on Task: Task (TaskHook HOOK, void *THUNK) When this task is scheduled, call `HOOK(this, THUNK)'. The HOOK argument is a function pointer with type `void (*)(Task *, void *)'. The `Task::initialize' method places the task on a router-wide list of `Task's, associates the task with a particular task queue, and, optionally, schedules it. Typically, an element's `initialize' method calls `Task::initialize'. -- Method on Task: void initialize (Router *R, bool SCHEDULED) -- Method on Task: void initialize (Element *E, bool SCHEDULED) Attaches the task to the router object R (or `E->router()'). Additionally sets the task's tickets to a default value, and schedules the task if SCHEDULED is true. Many elements call `ScheduleInfo::initialize_task' instead of calling `Task::initialize' directly. This method queries any `ScheduleInfo' elements in the configuration to determine the task's scheduling parameters, sets those parameters, and calls `Task::initialize' to schedule the task. The `ScheduleInfo::initialize_task' method is defined in the `' header file. -- Static Method on ScheduleInfo: void initialize_task (Element *E, Task *TASK, bool SCHEDULE, ErrorHandler *ERRH) Sets TASK's scheduling parameters as specified by any `ScheduleInfo' elements in the router configuration. The element E is used to find the correct router, and provides the relevant name for parameter lookup--the user supplies parameters to `ScheduleInfo' by element name. If SCHEDULE is true, also schedules TASK on `E->router()''s task queue. Reports any errors to ERRH. -- Static Method on ScheduleInfo: void initialize_task (Element *E, Task *TASK, ErrorHandler *ERRH) A synonym for `initialize_task(E, TASK, true, ERRH)'. -- Static Method on ScheduleInfo: void join_scheduler (Element *E, Task *TASK, ErrorHandler *ERRH) A synonym for `initialize_task(E, TASK, true, ERRH)'. The `initialize_task' method is generally called like this: int SomeElement::initialize(ErrorHandler *errh) { ScheduleInfo::initialize_task(this, &_task, errh); } Here, `_task', a `Task' object, is one of `SomeElement''s instance variables.  File: click.info, Node: Scheduling Tasks, Next: Tickets, Prev: Task Initialization, Up: Tasks 8.2 Scheduling Tasks ==================== The user may take a task off its task queue with the `unschedule' method, and place it back onto its task queue with the `reschedule' method. As tasks move to the head of the task queue, they are unscheduled and their callbacks are called. Within these callback functions, the user will typically call `fast_reschedule', which is like `reschedule' without the locking overhead. -- Method on Task: void unschedule () Unschedules the task by removing it from its task queue. Does nothing if if the task is currently unscheduled, or if it was never initialized. When this function returns, the task will not be scheduled. -- Method on Task: void reschedule () Reschedules the task by placing it on its task queue. If the task is already scheduled, then this method does nothing. All three functions lock the task queue before manipulating it. This avoids corruption when there are multiple processors executing simultaneously. If `reschedule' cannot immediately lock a task queue--perhaps because it is being used on another processor--then they register a task request, which will be executed in the near future. In contrast, the `unschedule' function will wait until it can lock the task queue. Sometimes unscheduling a task is not enough: you don't want the task to run, even if someone else (an upstream queue, for example) were to reschedule it. The `strong_unschedule' method both unschedules the task and shifts the task to the quiescent thread, which never runs. Thus, a `strong_unschedule'd task will not run until someone calls `strong_reschedule', which reschedules the task on its original preferred thread. -- Method on Task: void strong_unschedule () Unschedules the task by removing it from its task queue and shifting it to the quiescent thread. Does nothing if if the task is currently unscheduled, or if it was never initialized. When this function returns, the task will not be scheduled. -- Method on Task: void strong_reschedule () Reschedules the task by placing it on the task queue corresponding to its thread preference. The task will not be scheduled immediately upon return, but it will become scheduled soon--`strong_reschedule' uses a task request to avoid locking. The `fast_reschedule' method avoids locking overhead in the common case that a task must be rescheduled from within its callback. -- Method on Task: void fast_reschedule () Reschedules the task by placing it on its preferred task queue. This method avoids locking overhead, so it is faster than `reschedule'. *Caution*: You may call a `Task''s `fast_reschedule' method only from within its callback function. For instance, if an element has a task, `_task', that calls the element's `run_task' method when scheduled, and if `run_task' is called only by that task's callback, then that element's `run_task' method should call `_task.fast_reschedule()' instead of `_task.reschedule()'. The `fast_unschedule' method is to `unschedule' as `fast_reschedule' is to `reschedule'. It is rarely used, since tasks are automatically unscheduled before they are run. -- Method on Task: void fast_unschedule () Unschedules the task by removing it from its task queue. Does nothing if if the task is currently unscheduled, or if it was never initialized. This method avoids locking overhead, so it is faster than `unschedule'. *Caution*: You may call a `Task''s `fast_unschedule' method only from within its callback function.  File: click.info, Node: Tickets, Next: Task Thread Choice, Prev: Scheduling Tasks, Up: Tasks 8.3 Tickets =========== Click tasks are scheduled using the flexible, lightweight stride scheduling algorithm.(1) This algorithm assigns each task a parameter called its "tickets". A task with twice as many tickets as usual is scheduled twice as frequently. `Task's have methods for querying, setting, and adjusting their tickets. -- Method on Task: int tickets () const Returns this task's tickets. This number will be at least 1 and no more than `Task::MAX_TICKETS', which equals 32768. -- Method on Task: void set_tickets (int T) Sets this task's tickets to T. The T parameter should lie between 1 and `Task::MAX_TICKETS', inclusive; numbers outside this range are constrained to the nearest valid value. -- Method on Task: void adj_tickets (int DELTA) Equivalent to `set_tickets(tickets() + DELTA)'. ---------- Footnotes ---------- (1) For more information, see MIT Laboratory for Computer Science Technical Memo MIT/LCS/TM-528, `Stride scheduling: deterministic proportional-share resource management', by Carl A. Waldspurger and William E. Weihl, June 1995.  File: click.info, Node: Task Thread Choice, Next: Task Status, Prev: Tickets, Up: Tasks 8.4 Choosing a Thread ===================== Each task belongs to some task queue, which generally corresponds to a thread of control. Single-threaded Click has one active thread, and therefore one task queue, but multithreaded Click can have an arbitrary number of threads. Either Click hasĀ a special thread, the "quiescent thread", numbered -1; tasks belonging to the quiescent thread never run, whether or not they are scheduled. Every task starts out belonging to the first thread, thread 0. The `change_thread' method moves a task to another thread. -- Method on Task: void change_thread (int THREAD_ID) Move this task to thread THREAD_ID, which should be a number between -1 and the relevant `Router''s `nthreads()'. The task is scheduled on the new task queue if and only if it was scheduled on the old task queue. Like `reschedule', `change_thread' must lock the task queue before manipulating it. (Unlike those methods, `change_thread' must lock two task queues, the old and the new.) If `change_thread' cannot lock a task queue, then it registers a task request that will be executed in the near future. This implies that a task may remain on the same thread, or become unscheduled, for some time after `change_thread' is called.  File: click.info, Node: Task Status, Next: Task Handlers, Prev: Task Thread Choice, Up: Tasks 8.5 Task Status Methods ======================= These methods let a user check various properties of a task--for instance, whether it is initialized or scheduled. -- Method on Task: bool initialized () const Returns true iff the task has been initialized--that is, if it is associated with some router. -- Method on Task: bool scheduled () const Returns true iff the task is currently scheduled on some task queue. -- Method on Task: RouterThread * scheduled_list () const Returns the task queue with which this task is associated. Even unscheduled tasks are associated with some task queue; this is the task queue on which the task will be placed if `reschedule' is called. -- Method on Task: TaskHook hook () const Returns the callback function that is called when the task is scheduled. If the task is associated with some element, this method returns a null pointer. -- Method on Task: void * thunk () const Returns the extra data passed to the callback function when the task is scheduled. -- Method on Task: Element * element () const If the task is associated with some element, this method returns that element. Otherwise, returns a null pointer.  File: click.info, Node: Task Handlers, Next: Task Cleanup, Prev: Task Status, Up: Tasks 8.6 Task Handlers ================= By convention, elements with tasks should provide handlers that access task properties. The `Element::add_task_handlers' method automatically adds these handlers for a given `Task' object. -- Method on Element: void add_task_handlers (Task *TASK, const String &PREFIX = String()) Adds task handlers for TASK to this element. The string PREFIX is prepended to every handler name. This method adds at least the following handlers: `scheduled' Returns a Boolean value saying whether the task is currently scheduled on some task queue. Example result: "truen". `tickets' Returns or sets the task's currently allocated tickets. This handler is only available if Click was compiled to support stride scheduling. Example result: "1024n". `thread_preference' Returns the task's thread preference. This handler is only available on multithreaded Click. Example result: "2n".  File: click.info, Node: Task Cleanup, Prev: Task Handlers, Up: Tasks 8.7 Task Cleanup ================ You generally don't need to worry about destroying `Task' objects: they are automatically unscheduled and removed when the `Router' is destroyed. This only works if the `Task' objects have the same lifetime as the `Router', however. This includes the normal case, when `Task's are element instance variables. If you create and destroy `Task' objects as the router runs, however, you will need to call the following method before deleting the `Task'. -- Method on Task: void cleanup () Cleans up the `Task' object.  File: click.info, Node: Timers, Next: Notification, Prev: Tasks, Up: Top 9 Timers ******** Click "timers", like Click tasks, represent callback functions that the driver calls when appropriate. Unlike tasks, however, you schedule timers to go off at a specified time. Timers are intended for more infrequent and/or slower tasks. As with `Task', most `Timer' objects are declared as instance variables of elements and scheduled when needed. Timers may be scheduled with microsecond precision, but on current hardware, only millisecond precision is likely to be achievable. The `Timer' class is defined in the `' header file. * Menu: * Timer Initialization:: * Scheduling Timers:: * Timer Status Methods:: * Timer Cleanup::  File: click.info, Node: Timer Initialization, Next: Scheduling Timers, Prev: Timers, Up: Timers 9.1 Timer Initialization ======================== Timer initialization resembles task initialization. When the timer is constructed, you must supply it with information about its callback function. Later, after the router is initialized, you must initialize and, optionally, schedule it. -- Constructor on Timer: Timer (Element *E) When this timer goes off, call `E->run_timer()'. -- Constructor on Timer: Timer (Task *T) When this timer goes off, call `T->reschedule()'. -- Constructor on Timer: Timer (TimerHook HOOK, void *THUNK) When this timer goes off, call `HOOK(this, THUNK)'. The HOOK argument is a function pointer with type `void (*)(Timer *, void *)'. -- Method on Timer: void initialize (Router *R) -- Method on Timer: void initialize (Element *E) Attaches the timer to the router object R (or `E->router()'). Typically, an element's `initialize' method calls `Timer::initialize', and possibly one of the `schedule' functions described below.  File: click.info, Node: Scheduling Timers, Next: Timer Status Methods, Prev: Timer Initialization, Up: Timers 9.2 Scheduling Timers ===================== A variety of methods schedule timers to go off at specified times. The basic method is `schedule_at', which schedules the timer for a specified time. Subsidiary methods schedule the timer relative to the current time (the `schedule_after' methods), or relative to the last time the timer was scheduled to run (the `reschedule_after' methods). Finally, `unschedule' unschedules the timer. All `schedule' and `reschedule' functions first unschedule the timer if it was already scheduled. The `reschedule' methods are particularly useful for timers that should occur periodically. For example, this callback function will cause its timer to go off at 20-second intervals: void timer_callback(Timer *t, void *) { t->reschedule_after_s(20); } -- Method on Timer: void schedule_at (const struct timeval &WHEN) Schedule the timer to go off at WHEN. You must have initialized the timer earlier. -- Method on Timer: void schedule_now () Schedule the timer to go off as soon as possible. -- Method on Timer: void schedule_after (const struct timeval &DELAY) Schedule the timer to go off DELAY after the current time. -- Method on Timer: void schedule_after_s (uint32_t DELAY) Schedule the timer to go off DELAY seconds after the current time. -- Method on Timer: void schedule_after_ms (uint32_t DELAY) Schedule the timer to go off DELAY milliseconds after the current time. -- Method on Timer: void reschedule_after (const struct timeval &DELAY) Schedule the timer to go off DELAY after it was last scheduled to go off. If the timer was never previously scheduled, this method will schedule the timer for some arbitrary time. -- Method on Timer: void reschedule_after_s (uint32_t DELAY) Schedule the timer to go off DELAY seconds after it was last scheduled to go off. -- Method on Timer: void reschedule_after_ms (uint32_t DELAY) Schedule the timer to go off DELAY milliseconds after it was last scheduled to go off. -- Method on Timer: void unschedule () Unschedules the timer, if it was scheduled.  File: click.info, Node: Timer Status Methods, Next: Timer Cleanup, Prev: Scheduling Timers, Up: Timers 9.3 Timer Status Methods ======================== These methods return information about a timer, including when it is scheduled to expire. -- Method on Timer: bool initialized () const Returns true iff the timer has been initialized with a call to `initialize()'. Uninitialized timers must not be scheduled. -- Method on Timer: bool scheduled () const Returns true iff the timer is scheduled to expire some time in the future. -- Method on Timer: const struct timeval & expiry () const Returns the time that the timer is set to expire. If the timer has never been scheduled, the value is garbage. If the timer was scheduled but is not scheduled currently, the value is most recently set expiry time.  File: click.info, Node: Timer Cleanup, Prev: Timer Status Methods, Up: Timers 9.4 Timer Cleanup ================= You don't need to worry about cleaning up `Timer' objects. They are automatically unscheduled and removed when the `Router' is destroyed, and deleting a `Timer' automatically removes it from any relevant lists. The following function is nevertheless provided for consistency with `Task's, which do need to be cleaned up in certain circumstances (*note Task Cleanup::). -- Method on Timer: void cleanup () Cleans up the `Timer' object.  File: click.info, Node: Notification, Next: Coding Standards, Prev: Timers, Up: Top 10 Notification ***************  File: click.info, Node: Coding Standards, Next: Index, Prev: Notification, Up: Top 11 Coding Standards ******************* * Menu: * Upper and lower case names:: * Common name patterns::  File: click.info, Node: Upper and lower case names, Next: Common name patterns, Prev: Coding Standards, Up: Coding Standards 11.1 Upper and Lower Case in Names ================================== Keep to the following consistent scheme for choosing between upper and lower case when naming variables, types, and functions. *Classes* Use mixed case with an initial capital letter and no underscores: `LookupIPRoute'. *Methods* Use all lower case with underscores separating words: `negation_is_simple'. *Constants* Use all upper case with underscores separating words: `TYPE_ICMP_TYPE'. *Instance variables* Begin with an underscore, then use all lower case with underscores separating words: `_length'. *Regular variables* Use all lower case with underscores separating words: `i', `the_handler'. *Class variables* These variables are declared as `static' in the class header. Name them like regular variables: `nelements_allocated'. *Functions* Name them like methods: `quicksort_hook'. *Other types* This includes typedefs and enumerated types. Name them like classes: `CpVaParseCmd', `ConfigurePhase'. There are exceptions to these guidelines. In particular: * Instance variables in C structs--that is, classes with few methods whose instance variables are mostly public--may be named like regular variables, without a preceding underscore. The same goes for the components of unions. * Classes that act like simple types, such as `uatomic32_t', take names similar to the types they replace (in this case `uint32_t').  File: click.info, Node: Common name patterns, Prev: Upper and lower case names, Up: Coding Standards 11.2 Common Name Patterns ========================= * Many instance variables have associated "getter methods" that return their values, and/or "setter methods" that change their values. For an instance variable named `_x', the getter method should be named `x()' and the setter method should be named `set_x()'. * A variable or method which counts something is often named `nOBJECTs'--for instance, `_nwarnings', `ninputs()', `_npackets'. * Use a bare `0' for a null pointer, except where some ambiguity might arise (for example, where an incorrect overloading might be selected).  File: click.info, Node: Index, Prev: Coding Standards, Up: Top Index ***** [index] * Menu: * (*ReadHandler): Read and Write Handler Overview. (line 13) * (*WriteHandler): Read and Write Handler Overview. (line 21) * add_read_handler on Element: Adding Handlers. (line 13) * add_read_handler on Router: Adding Handlers. (line 34) * add_task_handlers on Element: Task Handlers. (line 12) * add_write_handler on Element: Adding Handlers. (line 19) * add_write_handler on Router: Adding Handlers. (line 37) * adj_tickets on Task: Tickets. (line 24) * all_user_anno_u on Packet: User Annotations. (line 60) * append on StringAccum: StringAccum Manipulation. (line 13) * buffer_data on Packet: Packet Structure and Contents. (line 37) * buffer_data on WritablePacket: Packet Structure and Contents. (line 47) * buffer_length on Packet: Packet Structure and Contents. (line 42) * c_str on StringAccum: StringAccum Contents. (line 25) * call_read on Router::Handler: Handler Objects. (line 57) * call_write on Router::Handler: Handler Objects. (line 62) * cc on StringAccum: StringAccum Contents. (line 26) * change_handler_flags on Router: Adding Handlers. (line 46) * change_thread on Task: Task Thread Choice. (line 16) * cleanup on Task: Task Cleanup. (line 15) * cleanup on Timer: Timer Cleanup. (line 14) * clear on StringAccum: StringAccum Manipulation. (line 77) * clear_annotations on Packet: Annotations In General. (line 10) * clone on Packet: Packet Sharing. (line 12) * ContextErrorHandler on ContextErrorHandler: Error Veneers. (line 26) * copy_annotations on Packet: Annotations In General. (line 14) * cp_argvec: Config String Splitting. (line 7) * cp_bool: Parsing Booleans. (line 9) * cp_element: Parsing Elements. (line 38) * cp_ethernet_address: Parsing Ethernet Addresses. (line 18) * cp_handler: Parsing Handlers. (line 26) * cp_integer: Parsing Integers. (line 36) * cp_ip6_address: Parsing IPv6 Addresses. (line 30) * cp_ip6_prefix: Parsing IPv6 Addresses. (line 38) * cp_ip_address: Parsing IP Addresses. (line 28) * cp_ip_address_list: Parsing IP Addresses. (line 64) * cp_ip_prefix: Parsing IP Addresses. (line 36) * cp_keyword: Parsing Strings. (line 66) * cp_quote: Quoting and Unquoting. (line 24) * cp_real10: Parsing Reals. (line 64) * cp_real2: Parsing Reals. (line 74) * cp_seconds_as: Parsing Miscellaneous. (line 10) * cp_seconds_as_micro: Parsing Miscellaneous. (line 27) * cp_seconds_as_milli: Parsing Miscellaneous. (line 25) * cp_spacevec: Config String Splitting. (line 14) * cp_string: Parsing Strings. (line 14) * cp_timeval: Parsing Miscellaneous. (line 32) * cp_unargvec: Config String Splitting. (line 48) * cp_uncomment: Quoting and Unquoting. (line 14) * cp_unquote: Quoting and Unquoting. (line 18) * cp_unsigned: Parsing Integers. (line 44) * cp_unsigned_real10: Parsing Reals. (line 58) * cp_unsigned_real2: Parsing Reals. (line 69) * cp_unspacevec: Config String Splitting. (line 52) * cp_va: cp_va. (line 6) * cp_va_static_cleanup: cp_va Initialization. (line 17) * cp_va_static_initialize: cp_va Initialization. (line 13) * cp_word: Parsing Strings. (line 40) * data on Packet: Packet Structure and Contents. (line 31) * data on StringAccum: StringAccum Contents. (line 13) * data on WritablePacket: Packet Structure and Contents. (line 46) * debug on ErrorHandler: Reporting Errors. (line 13) * decorate_text on ErrorHandler: Writing ErrorHandlers. (line 30) * default ErrorHandler: Basic ErrorHandlers. (line 13) * default_handler on ErrorHandler: Basic ErrorHandlers. (line 19) * device_anno on Packet: Device Annotation. (line 14) * dst_ip6_anno on Packet: Destination Address Annotation. (line 17) * dst_ip_anno on Packet: Destination Address Annotation. (line 14) * element on Task: Task Status. (line 33) * element_hindexes on Router: Handlers By Name or Index. (line 52) * error on ErrorHandler: Reporting Errors. (line 16) * ErrorHandler, default: Basic ErrorHandlers. (line 13) * ErrorVeneer: Writing ErrorHandlers. (line 54) * ErrorVeneer on ErrorVeneer: Writing ErrorHandlers. (line 67) * expiry on Timer: Timer Status Methods. (line 18) * extend on StringAccum: StringAccum Manipulation. (line 23) * fast_reschedule on Task: Scheduling Tasks. (line 55) * fast_unschedule on Task: Scheduling Tasks. (line 72) * fatal on ErrorHandler: Reporting Errors. (line 17) * FileErrorHandler on FileErrorHandler: Basic ErrorHandlers. (line 39) * flags on Router::Handler: Handler Objects. (line 17) * forward on StringAccum: StringAccum Manipulation. (line 66) * handle_text on ErrorHandler: Writing ErrorHandlers. (line 45) * handler on Router: Handlers By Name or Index. (line 13) * headroom on Packet: Packet Structure and Contents. (line 40) * hindex on Router: Handlers By Name or Index. (line 24) * hook on Task: Task Status. (line 24) * initialize on Task: Task Initialization. (line 31) * initialize on Timer: Timer Initialization. (line 23) * initialize_task on ScheduleInfo: Task Initialization. (line 46) * initialized on Task: Task Status. (line 10) * initialized on Timer: Timer Status Methods. (line 10) * ip6_header on Packet: Header Annotations. (line 76) * ip6_header on WritablePacket: Header Annotations. (line 77) * ip6_header_length on Packet: Header Annotations. (line 84) * ip6_header_offset on Packet: Header Annotations. (line 83) * ip_header on Packet: Header Annotations. (line 74) * ip_header on WritablePacket: Header Annotations. (line 75) * ip_header_length on Packet: Header Annotations. (line 82) * ip_header_offset on Packet: Header Annotations. (line 81) * join_scheduler on ScheduleInfo: Task Initialization. (line 60) * kill on Packet: Packet Creation. (line 80) * LandmarkErrorHandler on LandmarkErrorHandler: Error Veneers. (line 43) * ldebug on ErrorHandler: Reporting Errors. (line 36) * length on Packet: Packet Structure and Contents. (line 34) * length on StringAccum: StringAccum Contents. (line 18) * lerror on ErrorHandler: Reporting Errors. (line 42) * lfatal on ErrorHandler: Reporting Errors. (line 44) * lmessage on ErrorHandler: Reporting Errors. (line 38) * lwarning on ErrorHandler: Reporting Errors. (line 40) * make on Packet <1>: Packets and sk_buffs. (line 20) * make on Packet: Packet Creation. (line 31) * make_text on ErrorHandler: Writing ErrorHandlers. (line 19) * message on ErrorHandler: Reporting Errors. (line 14) * name on Router::Handler: Handler Objects. (line 14) * NAME_ANNO: Specific User Annotations. (line 13) * nerrors on ErrorHandler: Counting Errors. (line 11) * network_header on Packet: Header Annotations. (line 21) * network_header on WritablePacket: Header Annotations. (line 22) * network_header_length on Packet: Header Annotations. (line 36) * network_header_offset on Packet: Header Annotations. (line 31) * nonunique_push on Packet: Packet Buffer Manipulation. (line 62) * nonunique_put on Packet: Packet Buffer Manipulation. (line 77) * nwarnings on ErrorHandler: Counting Errors. (line 10) * operator bool on String: StringAccum Contents. (line 21) * operator<< <1>: Special StringAccum operator<<. (line 13) * operator<<: StringAccum operator<<. (line 16) * operator[] on StringAccum: StringAccum Contents. (line 32) * out_of_memory on StringAccum: StringAccum Out-of-Memory. (line 13) * packet_type_anno on Packet: Packet Type Annotation. (line 33) * perfctr_anno on Packet: Performance Counter Annotation. (line 11) * pop_back on StringAccum: StringAccum Manipulation. (line 80) * PrefixErrorHandler on PrefixErrorHandler: Error Veneers. (line 36) * pull on Packet: Packet Buffer Manipulation. (line 31) * push on Packet: Packet Buffer Manipulation. (line 16) * put on Packet: Packet Buffer Manipulation. (line 37) * read_visible on Router::Handler: Handler Objects. (line 30) * readable on Router::Handler: Handler Objects. (line 27) * reschedule on Task: Scheduling Tasks. (line 20) * reschedule_after on Timer: Scheduling Timers. (line 42) * reschedule_after_ms on Timer: Scheduling Timers. (line 51) * reschedule_after_s on Timer: Scheduling Timers. (line 47) * reserve on StringAccum: StringAccum Manipulation. (line 58) * reset_counts on ErrorHandler: Counting Errors. (line 15) * schedule_after on Timer: Scheduling Timers. (line 32) * schedule_after_ms on Timer: Scheduling Timers. (line 38) * schedule_after_s on Timer: Scheduling Timers. (line 35) * schedule_at on Timer: Scheduling Timers. (line 25) * schedule_now on Timer: Scheduling Timers. (line 29) * scheduled on Task: Task Status. (line 14) * scheduled on Timer: Timer Status Methods. (line 14) * scheduled_list on Task: Task Status. (line 18) * set_default_handler on ErrorHandler: Basic ErrorHandlers. (line 23) * set_device_anno on Packet: Device Annotation. (line 17) * set_dst_ip6_anno on Packet: Destination Address Annotation. (line 22) * set_dst_ip_anno on Packet: Destination Address Annotation. (line 21) * set_ip6_header on Packet: Header Annotations. (line 91) * set_ip_header on Packet: Header Annotations. (line 89) * SET_NAME_ANNO: Specific User Annotations. (line 16) * set_network_header on Packet: Header Annotations. (line 60) * set_packet_type_anno on Packet: Packet Type Annotation. (line 37) * set_perfctr_anno on Packet: Performance Counter Annotation. (line 14) * set_tickets on Task: Tickets. (line 19) * set_timestamp_anno on Packet: Timestamp Annotation. (line 14) * set_user_anno_c on Packet: User Annotations. (line 54) * set_user_anno_i on Packet: User Annotations. (line 56) * set_user_anno_u on Packet: User Annotations. (line 55) * shared on Packet: Packet Sharing. (line 34) * silent_handler on ErrorHandler: Basic ErrorHandlers. (line 28) * skb on Packet: Packets and sk_buffs. (line 32) * static_cleanup on ErrorHandler: ErrorHandler Initialization. (line 20) * static_initialize on ErrorHandler: ErrorHandler Initialization. (line 13) * steal_skb on Packet: Packets and sk_buffs. (line 40) * StringAccum on StringAccum: StringAccum Constructors. (line 7) * strong_reschedule on Task: Scheduling Tasks. (line 46) * strong_unschedule on Task: Scheduling Tasks. (line 40) * tailroom on Packet: Packet Structure and Contents. (line 41) * take on Packet: Packet Buffer Manipulation. (line 52) * take on StringAccum: StringAccum Results. (line 19) * take_bytes on StringAccum: StringAccum Results. (line 24) * take_string on StringAccum: StringAccum Results. (line 31) * Task on Task: Task Initialization. (line 18) * tcp_header on Packet: Header Annotations. (line 97) * tcp_header on WritablePacket: Header Annotations. (line 98) * thunk on Task: Task Status. (line 29) * tickets on Task: Tickets. (line 15) * Timer on Timer: Timer Initialization. (line 12) * timestamp_anno on Packet: Timestamp Annotation. (line 9) * transport_header on Packet: Header Annotations. (line 26) * transport_header on WritablePacket: Header Annotations. (line 27) * transport_header_offset on Packet: Header Annotations. (line 40) * udp_header on Packet: Header Annotations. (line 99) * udp_header on WritablePacket: Header Annotations. (line 100) * uniqueify on Packet: Packet Sharing. (line 20) * unparse_name on Router::Handler: Handler Objects. (line 46) * unschedule on Task: Scheduling Tasks. (line 14) * unschedule on Timer: Scheduling Timers. (line 55) * user_anno_c on Packet: User Annotations. (line 43) * user_anno_i on Packet: User Annotations. (line 48) * user_anno_u on Packet: User Annotations. (line 47) * verror on ErrorHandler: Reporting Errors. (line 73) * visible on Router::Handler: Handler Objects. (line 42) * warning on ErrorHandler: Reporting Errors. (line 15) * writable on Router::Handler: Handler Objects. (line 38) * write_visible on Router::Handler: Handler Objects. (line 39)  Tag Table: Node: Top223 Node: Overview2926 Node: Packet Transfer3061 Node: Helper Classes3178 Node: String3434 Node: StringAccum4032 Node: StringAccum Constructors4780 Node: StringAccum operator<<5528 Node: Special StringAccum operator<<7560 Node: StringAccum Manipulation9079 Node: StringAccum Contents13147 Node: StringAccum Results14871 Node: StringAccum Out-of-Memory16597 Node: Vector17386 Node: Bitvector17503 Node: HashMap17622 Node: BigHashMap17741 Node: ErrorHandler17869 Node: ErrorHandler Initialization18788 Node: Reporting Errors19938 Node: Error Format Strings23494 Node: Counting Errors27999 Node: Basic ErrorHandlers28942 Node: Error Veneers30872 Node: Writing ErrorHandlers34613 Node: IPAddress38018 Node: IP6Address38393 Node: Packets38502 Node: Packet Structure and Contents40183 Node: Packet Creation42486 Node: Packets and sk_buffs45930 Node: Packet Sharing48144 Node: Packet Buffer Manipulation49648 Node: Annotations54269 Node: Header Annotations55392 Node: User Annotations60121 Node: Specific User Annotations62685 Node: Other Annotations64111 Node: Destination Address Annotation64805 Node: Timestamp Annotation66071 Node: Device Annotation67316 Node: Packet Type Annotation68509 Node: Performance Counter Annotation70149 Node: Annotations In General70887 Node: Packet Out-of-Memory71543 Node: Element Characteristics72291 Node: Element Initialization72547 Node: Element Runtime72808 Node: Handling Packets73122 Node: Handlers74627 Node: Read and Write Handler Overview75135 Node: Adding Handlers78360 Ref: Changing Handler Flags80220 Node: Default Handlers80705 Node: Accessing Handlers Internally83211 Node: Handler Objects84060 Node: Handlers By Name or Index87230 Node: LLRPC Overview89705 Node: Configuration Strings89844 Node: Config String Structure90115 Node: Quoting and Unquoting93930 Node: Config String Splitting95721 Node: Parsing Functions98673 Node: Parsing Strings99967 Node: Parsing Booleans104118 Node: Parsing Integers104676 Node: Parsing Reals107171 Node: Parsing IP Addresses111492 Node: Parsing IPv6 Addresses114981 Node: Parsing Ethernet Addresses118023 Node: Parsing Elements119036 Node: Parsing Handlers121507 Node: Parsing Miscellaneous124452 Node: cp_va126154 Node: cp_va Concepts126351 Node: cp_va Initialization126480 Node: Tasks131375 Node: Task Initialization132672 Node: Scheduling Tasks135764 Node: Tickets139541 Ref: Tickets-Footnote-1140523 Node: Task Thread Choice140755 Node: Task Status142119 Node: Task Handlers143465 Node: Task Cleanup144529 Node: Timers145161 Node: Timer Initialization145922 Node: Scheduling Timers147029 Node: Timer Status Methods149305 Node: Timer Cleanup150164 Node: Notification150728 Node: Coding Standards150852 Node: Upper and lower case names151049 Node: Common name patterns152693 Node: Index153430  End Tag Table