6 * Copyright (c) 1999 Whistle Communications, Inc.
9 * Subject to the following obligations and disclaimer of warranty, use and
10 * redistribution of this software, in source or object code forms, with or
11 * without modifications are expressly permitted by Whistle Communications;
12 * provided, however, that:
13 * 1. Any and all reproductions of the source or object code must include the
14 * copyright notice above and the following disclaimer of warranties; and
15 * 2. No rights are granted, in any manner or form, to use Whistle
16 * Communications, Inc. trademarks, including the mark "WHISTLE
17 * COMMUNICATIONS" on advertising, endorsements, or otherwise except as
18 * such appears in the above copyright notice or in the software.
20 * THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
21 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
22 * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
23 * INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
24 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
25 * WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
26 * REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
27 * SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
28 * IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
29 * RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
30 * WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
31 * PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
32 * SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35 * THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
38 * Author: Archie Cobbs <archie@freebsd.org>
40 * $Whistle: ng_parse.h,v 1.2 1999/11/29 01:43:48 archie Exp $
44 #ifndef _NETGRAPH_NG_PARSE_H_
45 #define _NETGRAPH_NG_PARSE_H_
49 This defines a library of routines for converting between various C
50 language types in binary form and ASCII strings. Types are user
51 definable. Several pre-defined types are supplied, for some common
52 C types: structures, variable and fixed length arrays, integer types,
53 variable and fixed length strings, IP addresses, etc.
55 A netgraph node type may provide a list of types that correspond to
56 the structures it expects to send and receive in the arguments field
57 of a control message. This allows these messages to be converted
58 between their native binary form and the corresponding ASCII form.
60 A future use of the ASCII form may be for inter-machine communication
61 of control messages, because the ASCII form is machine independent
62 whereas the native binary form is not.
69 '{' [ <name>=<value> ... ] '}'
71 Omitted fields have their default values by implication.
72 The order in which the fields are specified does not matter.
76 '[' [ [index=]<value> ... ] ']'
78 Element value may be specified with or without the "<index>=" prefix;
79 If omitted, the index after the previous element is used.
80 Omitted fields have their default values by implication.
86 That is, strings are specified just like C strings. The usual
87 backslash escapes are accepted.
89 Other simple types (integers, IP addresses) have their obvious forms.
94 Suppose we have a netgraph command that takes as an argument
95 a 'struct foo' shown below. Here is an example of a possible
96 value for the structure, and the corresponding ASCII encoding
99 Structure Binary value
100 --------- ------------
103 struct in_addr ip; 01 02 03 04
105 char label[8]; 61 62 63 0a 00 00 00 00
107 short ary[]; 05 00 00 00 0a 00
112 { ip=1.2.3.4 label="abc\n" alen=3 ary=[ 5 2=10 ] }
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 "alen"). 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'.
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).
128 // Super-type info for 'label' field
129 struct ng_parse_fixedstring_info foo_label_info = { 8 };
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
137 #define OFFSETOF(s, e) ((char *)&((s *)0)->e - (char *)((s *)0))
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].
143 foo_ary_getLength(const struct ng_parse_type *type,
144 const u_char *start, const u_char *buf)
148 f = (const struct foo *)(buf - OFFSETOF(struct foo, ary));
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
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
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 },
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
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: { } [ ] = "
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.
191 /************************************************************************
192 METHODS REQUIRED BY A TYPE
193 ************************************************************************/
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.
201 struct ng_parse_type;
204 * Convert ASCII to binary according to the supplied type.
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).
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).
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
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);
230 * Convert binary to ASCII according to the supplied type.
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.
238 * ERANGE Output was longer than buflen bytes
240 typedef int ng_unparse_t(const struct ng_parse_type *type,
241 const u_char *data, int *off, char *buf, int buflen);
244 * Compute the default value according to the supplied type.
246 * Store the result in 'buf', which is at least *buflen bytes long.
247 * Upon return *buflen contains the length of the output.
251 * ERANGE Output was longer than *buflen bytes
252 * EOPNOTSUPP Default value is not specified for this type
254 typedef int ng_getDefault_t(const struct ng_parse_type *type,
255 const u_char *start, u_char *buf, int *buflen);
258 * Return the alignment requirement of this type. Zero is same as one.
260 typedef int ng_getAlign_t(const struct ng_parse_type *type);
262 /************************************************************************
264 ************************************************************************/
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.
272 * The 'private' field is ignored by all of the pre-defined types.
273 * Sub-types may use it as they see fit.
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.
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 */
289 /************************************************************************
291 ************************************************************************/
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.
300 * Default value: Determined on a per-field basis
301 * Additional info: struct ng_parse_struct_field *
303 extern const struct ng_parse_type ng_parse_struct_type;
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 */
316 * FIXED LENGTH ARRAY TYPE
318 * This type supports fixed length arrays, having any element type.
320 * Default value: As returned by getDefault for each index
321 * Additional info: struct ng_parse_fixedarray_info *
323 extern const struct ng_parse_type ng_parse_fixedarray_type;
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.
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);
336 struct ng_parse_fixedarray_info {
337 const struct ng_parse_type *elementType;
339 ng_parse_array_getDefault_t *getDefault;
343 * VARIABLE LENGTH ARRAY TYPE
345 * Same as fixed length arrays, except that the length is determined
346 * by a function instead of a constant value.
348 * Default value: Same as with fixed length arrays
349 * Additional info: struct ng_parse_array_info *
351 extern const struct ng_parse_type ng_parse_array_type;
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.
359 typedef int ng_parse_array_getLength_t(const struct ng_parse_type *type,
360 const u_char *start, const u_char *buf);
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;
369 * ARBITRARY LENGTH STRING TYPE
371 * For arbirary length, NUL-terminated strings.
373 * Default value: Empty string
374 * Additional info: None required
376 extern const struct ng_parse_type ng_parse_string_type;
379 * BOUNDED LENGTH STRING TYPE
381 * These are strings that have a fixed-size buffer, and always include
382 * a terminating NUL character.
384 * Default value: Empty string
385 * Additional info: struct ng_parse_fixedstring_info *
387 extern const struct ng_parse_type ng_parse_fixedstring_type;
389 struct ng_parse_fixedstring_info {
390 int bufSize; /* size of buffer (including NUL) */
394 * EXPLICITLY SIZED STRING TYPE
396 * These are strings that have a two byte length field preceding them.
397 * Parsed strings are NOT NUL-terminated.
399 * Default value: Empty string
400 * Additional info: None
402 extern const struct ng_parse_type ng_parse_sizedstring_type;
405 * COMMONLY USED BOUNDED LENGTH STRING TYPES
407 extern const struct ng_parse_type ng_parse_nodebuf_type; /* NG_NODESIZ */
408 extern const struct ng_parse_type ng_parse_hookbuf_type; /* NG_HOOKSIZ */
409 extern const struct ng_parse_type ng_parse_pathbuf_type; /* NG_PATHSIZ */
410 extern const struct ng_parse_type ng_parse_typebuf_type; /* NG_TYPESIZ */
411 extern const struct ng_parse_type ng_parse_cmdbuf_type; /* NG_CMDSTRSIZ */
417 * Additional info: None required
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;
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;
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;
439 * Default value: 0.0.0.0
440 * Additional info: None required
442 extern const struct ng_parse_type ng_parse_ipaddr_type;
445 * ETHERNET ADDRESS TYPE
447 * Default value: None
448 * Additional info: None required
450 extern const struct ng_parse_type ng_parse_enaddr_type;
453 * VARIABLE LENGTH BYTE ARRAY TYPE
455 * The bytes are displayed in hex. The ASCII form may be either an
456 * array of bytes or a string constant, in which case the array is
457 * zero-filled after the string bytes.
459 * Default value: All bytes are zero
460 * Additional info: ng_parse_array_getLength_t *
462 extern const struct ng_parse_type ng_parse_bytearray_type;
465 * NETGRAPH CONTROL MESSAGE TYPE
467 * This is the parse type for a struct ng_mesg.
469 * Default value: All fields zero
470 * Additional info: None required
472 extern const struct ng_parse_type ng_parse_ng_mesg_type;
474 /************************************************************************
475 CONVERSTION AND PARSING ROUTINES
476 ************************************************************************/
478 /* Tokens for parsing structs and arrays */
479 enum ng_parse_token {
482 T_LBRACKET, /* '[' */
483 T_RBRACKET, /* ']' */
485 T_STRING, /* string in double quotes */
486 T_ERROR, /* error parsing string in double quotes */
487 T_WORD, /* anything else containing no whitespace */
488 T_EOF, /* end of string reached */
492 * See typedef ng_parse_t for definition
494 extern int ng_parse(const struct ng_parse_type *type, const char *string,
495 int *off, u_char *buf, int *buflen);
498 * See typedef ng_unparse_t for definition (*off assumed to be zero).
500 extern int ng_unparse(const struct ng_parse_type *type,
501 const u_char *data, char *buf, int buflen);
504 * See typedef ng_getDefault_t for definition
506 extern int ng_parse_getDefault(const struct ng_parse_type *type,
507 u_char *buf, int *buflen);
510 * Parse a token: '*startp' is the offset to start looking. Upon
511 * successful return, '*startp' equals the beginning of the token
512 * and '*lenp' the length. If error, '*startp' points at the
513 * offending character(s).
515 extern enum ng_parse_token ng_parse_get_token(const char *s,
516 int *startp, int *lenp);
519 * Like above, but specifically for getting a string token and returning
520 * the string value. The string token must be enclosed in double quotes
521 * and the normal C backslash escapes are recognized. The caller must
522 * eventually free() the returned result. Returns NULL if token is
523 * not a string token, or parse or other error. Otherwise, *lenp contains
524 * the number of characters parsed, and *slenp (if not NULL) contains
525 * the actual number of characters in the parsed string.
527 extern char *ng_get_string_token(const char *s, int *startp,
528 int *lenp, int *slenp);
531 * Convert a raw string into a doubly-quoted string including any
532 * necessary backslash escapes. Caller must free the result.
533 * Returns NULL if ENOMEM. Normally "slen" should equal strlen(s)
534 * unless you want to encode NUL bytes.
536 extern char *ng_encode_string(const char *s, int slen);
538 #endif /* _NETGRAPH_NG_PARSE_H_ */