[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/netgraph/ng_parse.h

Version: -  FREEBSD  -  FREEBSD10  -  FREEBSD9  -  FREEBSD92  -  FREEBSD91  -  FREEBSD90  -  FREEBSD8  -  FREEBSD82  -  FREEBSD81  -  FREEBSD80  -  FREEBSD7  -  FREEBSD74  -  FREEBSD73  -  FREEBSD72  -  FREEBSD71  -  FREEBSD70  -  FREEBSD6  -  FREEBSD64  -  FREEBSD63  -  FREEBSD62  -  FREEBSD61  -  FREEBSD60  -  FREEBSD5  -  FREEBSD55  -  FREEBSD54  -  FREEBSD53  -  FREEBSD52  -  FREEBSD51  -  FREEBSD50  -  FREEBSD4  -  FREEBSD3  -  FREEBSD22  -  cheribsd  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1  -  FREEBSD-LIBC  -  FREEBSD8-LIBC  -  FREEBSD7-LIBC  -  FREEBSD6-LIBC  -  GLIBC27 
SearchContext: -  none  -  3  -  10 

    1 
    2 /*
    3  * ng_parse.h
    4  *
    5  * Copyright (c) 1999 Whistle Communications, Inc.
    6  * All rights reserved.
    7  * 
    8  * Subject to the following obligations and disclaimer of warranty, use and
    9  * redistribution of this software, in source or object code forms, with or
   10  * without modifications are expressly permitted by Whistle Communications;
   11  * provided, however, that:
   12  * 1. Any and all reproductions of the source or object code must include the
   13  *    copyright notice above and the following disclaimer of warranties; and
   14  * 2. No rights are granted, in any manner or form, to use Whistle
   15  *    Communications, Inc. trademarks, including the mark "WHISTLE
   16  *    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
   17  *    such appears in the above copyright notice or in the software.
   18  * 
   19  * THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
   20  * TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
   21  * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
   22  * INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
   23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
   24  * WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
   25  * REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
   26  * SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
   27  * IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
   28  * RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
   29  * WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
   30  * PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
   31  * SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
   32  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   33  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   34  * THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
   35  * OF SUCH DAMAGE.
   36  *
   37  * Author: Archie Cobbs <archie@freebsd.org>
   38  *
   39  * $Whistle: ng_parse.h,v 1.2 1999/11/29 01:43:48 archie Exp $
   40  * $FreeBSD: src/sys/netgraph/ng_parse.h,v 1.7 2002/05/31 23:48:02 archie Exp $
   41  */
   42 
   43 #ifndef _NETGRAPH_PARSE_H_
   44 #define _NETGRAPH_PARSE_H_
   45 
   46 /*
   47 
   48   This defines a library of routines for converting between various C
   49   language types in binary form and ASCII strings.  Types are user
   50   definable.  Several pre-defined types are supplied, for some common
   51   C types: structures, variable and fixed length arrays, integer types,
   52   variable and fixed length strings, IP addresses, etc.
   53 
   54   A netgraph node type may provide a list of types that correspond to
   55   the structures it expects to send and receive in the arguments field
   56   of a control message.  This allows these messages to be converted
   57   between their native binary form and the corresponding ASCII form.
   58 
   59   A future use of the ASCII form may be for inter-machine communication
   60   of control messages, because the ASCII form is machine independent
   61   whereas the native binary form is not.
   62 
   63   Syntax
   64   ------
   65 
   66     Structures:
   67 
   68       '{' [ <name>=<value> ... ] '}'
   69 
   70       Omitted fields have their default values by implication.
   71       The order in which the fields are specified does not matter.
   72 
   73     Arrays:
   74 
   75       '[' [ [index=]<value> ... ] ']'
   76 
   77       Element value may be specified with or without the "<index>=" prefix;
   78       If omitted, the index after the previous element is used.
   79       Omitted fields have their default values by implication.
   80 
   81     Strings:
   82 
   83       "foo bar blah\r\n"
   84 
   85       That is, strings are specified just like C strings. The usual
   86       backslash escapes are accepted.
   87 
   88     Other simple types (integers, IP addresses) have their obvious forms.
   89 
   90   Example
   91   -------
   92 
   93     Suppose we have a netgraph command that takes as an argument
   94     a 'struct foo' shown below.  Here is an example of a possible
   95     value for the structure, and the corresponding ASCII encoding
   96     of that value:
   97 
   98         Structure                       Binary value
   99         ---------                       ------------
  100 
  101         struct foo {
  102             struct in_addr ip;          01 02 03 04
  103             int bar;                    00 00 00 00
  104             char label[8];              61 62 63 0a 00 00 00 00
  105             u_char alen;                03 00
  106             short ary[0];               05 00 00 00 0a 00
  107         };
  108 
  109         ASCII value
  110         -----------
  111 
  112         { ip=1.2.3.4 label="abc\n" alen=3 ary=[ 5 2=10 ] }
  113 
  114     Note that omitted fields and array elements get their default
  115     values ("bar" and ary[2]), and that the alignment is handled
  116     automatically (the extra 00 byte after "num").  Also, since byte
  117     order and alignment are inherently machine dependent, so is this
  118     conversion process.  The above example shows an x86 (little
  119     endian) encoding.  Also the above example is tricky because the
  120     structure is variable length, depending on 'alen', the number of
  121     elements in the array 'ary'.
  122 
  123     Here is how one would define a parse type for the above structure,
  124     subclassing the pre-defined types below.  We construct the type in
  125     a 'bottom up' fashion, defining each field's type first, then the
  126     type for the whole structure ('//' comments used to avoid breakage).
  127 
  128     // Super-type info for 'label' field
  129     struct ng_parse_fixedstring_info foo_label_info = { 8 };
  130 
  131     // Parse type for 'label' field
  132     struct ng_parse_type foo_label_type = {
  133             &ng_parse_fixedstring_type          // super-type
  134             &foo_label_info                     // super-type info
  135     };
  136 
  137     #define OFFSETOF(s, e) ((char *)&((s *)0)->e - (char *)((s *)0))
  138 
  139     // Function to compute the length of the array 'ary', which
  140     // is variable length, depending on the previous field 'alen'.
  141     // Upon entry 'buf' will be pointing at &ary[0].
  142     int
  143     foo_ary_getLength(const struct ng_parse_type *type,
  144             const u_char *start, const u_char *buf)
  145     {
  146             const struct foo *f;
  147 
  148             f = (const struct foo *)(buf - OFFSETOF(struct foo, ary));
  149             return f->alen;
  150     }
  151 
  152     // Super-type info for 'ary' field
  153     struct ng_parse_array_info foo_ary_info = {
  154             &ng_parse_int16_type,               // element type
  155             &foo_ary_getLength                  // func to get array length
  156     }
  157 
  158     // Parse type for 'ary' field
  159     struct ng_parse_type foo_ary_type = {
  160             &ng_parse_array_type,               // super-type
  161             &foo_ary_info                       // super-type info
  162     };
  163 
  164     // Super-type info for struct foo
  165     struct ng_parse_struct_field foo_fields[] = {
  166             { "ip",     &ng_parse_ipaddr_type   },
  167             { "bar",    &ng_parse_int32_type    },
  168             { "label",  &foo_label_type         },
  169             { "alen",   &ng_parse_uint8_type    },
  170             { "ary",    &foo_ary_type           },
  171             { NULL }
  172     };
  173 
  174     // Parse type for struct foo
  175     struct ng_parse_type foo_type = {
  176             &ng_parse_struct_type,              // super-type
  177             &foo_fields                         // super-type info
  178     };
  179 
  180   To define a type, you can define it as a sub-type of a predefined
  181   type as shown above, possibly overriding some of the predefined
  182   type's methods, or define an entirely new syntax, with the restriction
  183   that the ASCII representation of your type's value must not contain
  184   any whitespace or any of these characters: { } [ ] = "
  185 
  186   See ng_ksocket.c for an example of how to do this for 'struct sockaddr'.
  187   See ng_parse.c to see implementations of the pre-defined types below.
  188 
  189 */
  190 
  191 /************************************************************************
  192                         METHODS REQUIRED BY A TYPE
  193  ************************************************************************/
  194 
  195 /*
  196  * Three methods are required for a type. These may be given explicitly
  197  * or, if NULL, inherited from the super-type.  The 'getDefault' method
  198  * is always optional; the others are required if there is no super-type.
  199  */
  200 
  201 struct ng_parse_type;
  202 
  203 /*
  204  * Convert ASCII to binary according to the supplied type.
  205  *
  206  * The ASCII characters begin at offset *off in 'string'.  The binary
  207  * representation is put into 'buf', which has at least *buflen bytes.
  208  * 'start' points to the first byte output by ng_parse() (ie, start <= buf).
  209  *
  210  * Upon return, *buflen contains the length of the new binary data, and
  211  * *off is updated to point just past the end of the parsed range of
  212  * characters, or, in the case of an error, to the offending character(s).
  213  *
  214  * Return values:
  215  *      0               Success; *buflen holds the length of the data
  216  *                      and *off points just past the last char parsed.
  217  *      EALREADY        Field specified twice
  218  *      ENOENT          Unknown field
  219  *      E2BIG           Array or character string overflow
  220  *      ERANGE          Output was longer than *buflen bytes
  221  *      EINVAL          Parse failure or other invalid content
  222  *      ENOMEM          Out of memory
  223  *      EOPNOTSUPP      Mandatory array/structure element missing
  224  */
  225 typedef int     ng_parse_t(const struct ng_parse_type *type, const char *string,
  226                         int *off, const u_char *start,
  227                         u_char *buf, int *buflen);
  228 
  229 /*
  230  * Convert binary to ASCII according to the supplied type.
  231  *
  232  * The results are put into 'buf', which is at least buflen bytes long.
  233  * *off points to the current byte in 'data' and should be updated
  234  * before return to point just past the last byte unparsed.
  235  *
  236  * Returns:
  237  *      0               Success
  238  *      ERANGE          Output was longer than buflen bytes
  239  */
  240 typedef int     ng_unparse_t(const struct ng_parse_type *type,
  241                         const u_char *data, int *off, char *buf, int buflen);
  242 
  243 /*
  244  * Compute the default value according to the supplied type.
  245  *
  246  * Store the result in 'buf', which is at least *buflen bytes long.
  247  * Upon return *buflen contains the length of the output.
  248  *
  249  * Returns:
  250  *      0               Success
  251  *      ERANGE          Output was longer than *buflen bytes
  252  *      EOPNOTSUPP      Default value is not specified for this type
  253  */
  254 typedef int     ng_getDefault_t(const struct ng_parse_type *type,
  255                         const u_char *start, u_char *buf, int *buflen);
  256 
  257 /*
  258  * Return the alignment requirement of this type.  Zero is same as one.
  259  */
  260 typedef int     ng_getAlign_t(const struct ng_parse_type *type);
  261 
  262 /************************************************************************
  263                         TYPE DEFINITION
  264  ************************************************************************/
  265 
  266 /*
  267  * This structure describes a type, which may be a sub-type of another
  268  * type by pointing to it with 'supertype' and possibly omitting methods.
  269  * Typically the super-type requires some type-specific info, which is
  270  * supplied by the 'info' field.
  271  *
  272  * The 'private' field is ignored by all of the pre-defined types.
  273  * Sub-types may use it as they see fit.
  274  *
  275  * The 'getDefault' method may always be omitted (even if there is no
  276  * super-type), which means the value for any item of this type must
  277  * always be explicitly given.
  278  */
  279 struct ng_parse_type {
  280         const struct ng_parse_type *supertype;  /* super-type, if any */
  281         const void              *info;          /* type-specific info */
  282         void                    *private;       /* client private info */
  283         ng_parse_t              *parse;         /* parse method */
  284         ng_unparse_t            *unparse;       /* unparse method */
  285         ng_getDefault_t         *getDefault;    /* get default value method */
  286         ng_getAlign_t           *getAlign;      /* get alignment */
  287 };
  288 
  289 /************************************************************************
  290                         PRE-DEFINED TYPES
  291  ************************************************************************/
  292 
  293 /*
  294  * STRUCTURE TYPE
  295  *
  296  * This type supports arbitrary C structures.  The normal field alignment
  297  * rules for the local machine are applied.  Fields are always parsed in
  298  * field order, no matter what order they are listed in the ASCII string.
  299  *
  300  *   Default value:             Determined on a per-field basis
  301  *   Additional info:           struct ng_parse_struct_field *
  302  */
  303 extern const struct ng_parse_type ng_parse_struct_type;
  304 
  305 /* Each field has a name, type, and optional alignment override. If the
  306    override is non-zero, the alignment is determined from the field type.
  307    Note: add an extra struct ng_parse_struct_field with name == NULL
  308    to indicate the end of the list. */
  309 struct ng_parse_struct_field {
  310         const char                      *name;          /* field name */
  311         const struct ng_parse_type      *type;          /* field type */
  312         int                             alignment;      /* override alignment */
  313 };
  314 
  315 /*
  316  * FIXED LENGTH ARRAY TYPE
  317  *
  318  * This type supports fixed length arrays, having any element type.
  319  *
  320  *   Default value:             As returned by getDefault for each index
  321  *   Additional info:           struct ng_parse_fixedarray_info *
  322  */
  323 extern const struct ng_parse_type ng_parse_fixedarray_type;
  324 
  325 /*
  326  * Get the default value for the element at index 'index'.  This method
  327  * may be NULL, in which case the default value is computed from the
  328  * element type.  Otherwise, it should fill in the default value at *buf
  329  * (having size *buflen) and update *buflen to the length of the filled-in
  330  * value before return.  If there is not enough routine return ERANGE.
  331  */
  332 typedef int     ng_parse_array_getDefault_t(const struct ng_parse_type *type,
  333                                 int index, const u_char *start,
  334                                 u_char *buf, int *buflen);
  335 
  336 struct ng_parse_fixedarray_info {
  337         const struct ng_parse_type      *elementType;
  338         int                             length;
  339         ng_parse_array_getDefault_t     *getDefault;
  340 };
  341 
  342 /*
  343  * VARIABLE LENGTH ARRAY TYPE
  344  *
  345  * Same as fixed length arrays, except that the length is determined
  346  * by a function instead of a constant value.
  347  *
  348  *   Default value:             Same as with fixed length arrays
  349  *   Additional info:           struct ng_parse_array_info *
  350  */
  351 extern const struct ng_parse_type ng_parse_array_type;
  352 
  353 /*
  354  * Return the length of the array.  If the array is a field in a structure,
  355  * all prior fields are guaranteed to be filled in already.  Upon entry,
  356  * 'start' is equal to the first byte parsed in this run, while 'buf' points
  357  * to the first element of the array to be filled in.
  358  */
  359 typedef int     ng_parse_array_getLength_t(const struct ng_parse_type *type,
  360                                 const u_char *start, const u_char *buf);
  361 
  362 struct ng_parse_array_info {
  363         const struct ng_parse_type      *elementType;
  364         ng_parse_array_getLength_t      *getLength;
  365         ng_parse_array_getDefault_t     *getDefault;
  366 };
  367 
  368 /*
  369  * ARBITRARY LENGTH STRING TYPE
  370  *
  371  * For arbirary length, NUL-terminated strings.
  372  *
  373  *   Default value:             Empty string
  374  *   Additional info:           None required
  375  */
  376 extern const struct ng_parse_type ng_parse_string_type;
  377 
  378 /*
  379  * BOUNDED LENGTH STRING TYPE
  380  *
  381  * These are strings that have a fixed-size buffer, and always include
  382  * a terminating NUL character.
  383  *
  384  *   Default value:             Empty string
  385  *   Additional info:           struct ng_parse_fixedstring_info *
  386  */
  387 extern const struct ng_parse_type ng_parse_fixedstring_type;
  388 
  389 struct ng_parse_fixedstring_info {
  390         int     bufSize;        /* size of buffer (including NUL) */
  391 };
  392 
  393 /*
  394  * EXPLICITLY SIZED STRING TYPE
  395  *
  396  * These are strings that have a two byte length field preceding them.
  397  * Parsed strings are NOT NUL-terminated.
  398  *
  399  *   Default value:             Empty string
  400  *   Additional info:           None
  401  */
  402 extern const struct ng_parse_type ng_parse_sizedstring_type;
  403 
  404 /*
  405  * COMMONLY USED BOUNDED LENGTH STRING TYPES
  406  */
  407 extern const struct ng_parse_type ng_parse_nodebuf_type;  /* NG_NODELEN + 1 */
  408 extern const struct ng_parse_type ng_parse_hookbuf_type;  /* NG_HOOKLEN + 1 */
  409 extern const struct ng_parse_type ng_parse_pathbuf_type;  /* NG_PATHLEN + 1 */
  410 extern const struct ng_parse_type ng_parse_typebuf_type;  /* NG_TYPELEN + 1 */
  411 extern const struct ng_parse_type ng_parse_cmdbuf_type;   /* NG_CMDSTRLEN + 1 */
  412 
  413 /*
  414  * INTEGER TYPES
  415  *
  416  *   Default value:             0
  417  *   Additional info:           None required
  418  */
  419 extern const struct ng_parse_type ng_parse_int8_type;
  420 extern const struct ng_parse_type ng_parse_int16_type;
  421 extern const struct ng_parse_type ng_parse_int32_type;
  422 extern const struct ng_parse_type ng_parse_int64_type;
  423 
  424 /* Same thing but unparse as unsigned quantities */
  425 extern const struct ng_parse_type ng_parse_uint8_type;
  426 extern const struct ng_parse_type ng_parse_uint16_type;
  427 extern const struct ng_parse_type ng_parse_uint32_type;
  428 extern const struct ng_parse_type ng_parse_uint64_type;
  429 
  430 /* Same thing but unparse as hex quantities, e.g., "0xe7" */
  431 extern const struct ng_parse_type ng_parse_hint8_type;
  432 extern const struct ng_parse_type ng_parse_hint16_type;
  433 extern const struct ng_parse_type ng_parse_hint32_type;
  434 extern const struct ng_parse_type ng_parse_hint64_type;
  435 
  436 /*
  437  * IP ADDRESS TYPE
  438  *
  439  *   Default value:             0.0.0.0
  440  *   Additional info:           None required
  441  */
  442 extern const struct ng_parse_type ng_parse_ipaddr_type;
  443 
  444 /*
  445  * VARIABLE LENGTH BYTE ARRAY TYPE
  446  *
  447  * The bytes are displayed in hex.  The ASCII form may be either an
  448  * array of bytes or a string constant, in which case the array is
  449  * zero-filled after the string bytes.
  450  *
  451  *   Default value:             All bytes are zero
  452  *   Additional info:           ng_parse_array_getLength_t *
  453  */
  454 extern const struct ng_parse_type ng_parse_bytearray_type;
  455 
  456 /*
  457  * NETGRAPH CONTROL MESSAGE TYPE
  458  *
  459  * This is the parse type for a struct ng_mesg.
  460  *
  461  *   Default value:             All fields zero
  462  *   Additional info:           None required
  463  */
  464 extern const struct ng_parse_type ng_parse_ng_mesg_type;
  465 
  466 /************************************************************************
  467                 CONVERSTION AND PARSING ROUTINES
  468  ************************************************************************/
  469 
  470 /* Tokens for parsing structs and arrays */
  471 enum ng_parse_token {
  472         T_LBRACE,               /* '{' */
  473         T_RBRACE,               /* '}' */
  474         T_LBRACKET,             /* '[' */
  475         T_RBRACKET,             /* ']' */
  476         T_EQUALS,               /* '=' */
  477         T_STRING,               /* string in double quotes */
  478         T_ERROR,                /* error parsing string in double quotes */
  479         T_WORD,                 /* anything else containing no whitespace */
  480         T_EOF,                  /* end of string reached */
  481 };
  482 
  483 /*
  484  * See typedef ng_parse_t for definition
  485  */
  486 extern int      ng_parse(const struct ng_parse_type *type, const char *string,
  487                         int *off, u_char *buf, int *buflen);
  488 
  489 /*
  490  * See typedef ng_unparse_t for definition (*off assumed to be zero).
  491  */
  492 extern int      ng_unparse(const struct ng_parse_type *type,
  493                         const u_char *data, char *buf, int buflen);
  494 
  495 /*
  496  * See typedef ng_getDefault_t for definition
  497  */
  498 extern int      ng_parse_getDefault(const struct ng_parse_type *type,
  499                         u_char *buf, int *buflen);
  500 
  501 /*
  502  * Parse a token: '*startp' is the offset to start looking.  Upon
  503  * successful return, '*startp' equals the beginning of the token
  504  * and '*lenp' the length.  If error, '*startp' points at the
  505  * offending character(s).
  506  */
  507 extern enum     ng_parse_token ng_parse_get_token(const char *s,
  508                         int *startp, int *lenp);
  509 
  510 /*
  511  * Like above, but specifically for getting a string token and returning
  512  * the string value.  The string token must be enclosed in double quotes
  513  * and the normal C backslash escapes are recognized.  The caller must
  514  * eventually free() the returned result.  Returns NULL if token is
  515  * not a string token, or parse or other error. Otherwise, *lenp contains
  516  * the number of characters parsed, and *slenp (if not NULL) contains
  517  * the actual number of characters in the parsed string.
  518  */
  519 extern char     *ng_get_string_token(const char *s, int *startp,
  520                         int *lenp, int *slenp);
  521 
  522 /*
  523  * Convert a raw string into a doubly-quoted string including any
  524  * necessary backslash escapes.  Caller must free the result.
  525  * Returns NULL if ENOMEM. Normally "slen" should equal strlen(s)
  526  * unless you want to encode NUL bytes.
  527  */
  528 extern char     *ng_encode_string(const char *s, int slen);
  529 
  530 #endif /* _NETGRAPH_PARSE_H_ */
  531 

Cache object: c4b7298f54e442e6df1fe8583a782e00


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.