5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2008 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/Buffer Format Interface
24 * SILC Buffer Format API provides functions for formatting different data
25 * types into a buffer and retrieving different data types from a buffer
26 * into specified data types. It is especially useful to encode packets,
27 * protocol payloads and such.
29 * It also provides many advanced features like calling user specified
30 * encoder and decoder functions that are free to do anything to the buffer.
31 * The API also provides powerful regular expression matching capabilities
32 * within the buffer, enabling caller to not only match regular expressions
33 * but to make the API behave like Stream Editor (Sed) and Awk. The buffer
34 * can be matched against regular expression and then edited. Caller can
35 * do anything they want to the buffer after a match. The SILC_STR_REGEX
36 * macro provides many different flags that can change the behavior of the
37 * matching, with capabilities to also mimic Sed behavior.
39 * As the SilcBuffer context is not thread-safe these routines may not be used
40 * in multithreaded environment with a same SilcBuffer context without
41 * concurrency control.
45 * SilcBufferStruct buffer;
48 * memset(&buffer, 0, sizeof(buffer));
49 * ret = silc_buffer_format(&buffer,
50 * SILC_STR_UINT32(intval),
51 * SILC_STR_UINT8(charval),
52 * SILC_STR_UINT64(longintval),
53 * SILC_STR_UINT16(str_len),
54 * SILC_STR_DATA(str, str_len),
59 * // sed 's/foo/bar/', replace first foo with bar
60 * silc_buffer_format(buffer,
61 * SILC_STR_REGEX("foo", 0),
62 * SILC_STR_STRING("bar"),
63 * SILC_STR_END, SILC_STR_END);
70 /****f* silcutil/SilcBufferFormatFunc
74 * typedef int (*SilcBuffeSFormatFunc)(SilcStack stack,
81 * Formatting function callback given with SILC_STR_FUNC type. The
82 * `buffer' is the buffer being formatted at the location where the
83 * SILC_STR_FUNC was placed in formatting. The function should call
84 * silc_buffer_senlarge before it adds the data to the buffer to make
85 * sure that it has enough space. The buffer->head points to the
86 * start of the buffer and silc_buffer_headlen() gives the length
87 * of the currently formatted data area. It is also possible to use
88 * silc_buffer_sformat with `buffer' which will enlarge the buffer if
91 * The `value' is the value given to SILC_STR_FUNC that is to be formatted
92 * into the buffer. It may be NULL if the function is not formatting
93 * new data into the buffer. The `context' is caller specific context.
94 * Returns -1 on error and length of the formatted value otherwise, and
95 * 0 if nothing was formatted.
98 typedef int (*SilcBufferFormatFunc)(SilcStack stack, SilcBuffer buffer,
99 void *value, void *context);
101 /****f* silcutil/SilcBufferUnformatFunc
105 * typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer,
111 * Unformatting function callback given with SILC_STR_FUNC type. The
112 * `buffer' is the buffer being unformatted and is at the location where
113 * the SILC_STR_FUNC was placed in unformatting. The function should
114 * check there is enough data in the `buffer' before trying to decode
117 * If this function unformats anything from the buffer its value is to
118 * be returned to the `value' pointer. The implementation should itself
119 * decide whether the unformatted value is allocated or not. If this
120 * function does not unformat anything, nothing is returned to `value'
122 * The `context' is caller specific context. Returns -1 on error, and
123 * length of the unformatted value otherwise, and 0 if nothing was
127 typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer,
128 void **value, void *context);
132 /****f* silcutil/silc_buffer_format
136 * int silc_buffer_format(SilcBuffer dst, ...);
140 * Formats a buffer from a variable argument list. Returns -1 if the
141 * system is out of memory and the length of the formatted buffer otherwise.
142 * The buffer is enlarged automatically during formatting, if it doesn't
143 * already have enough space. Sets silc_errno in case of error.
147 * Three basic ways of using silc_buffer_format:
149 * // Statically allocated zero size buffer
150 * SilcBufferStruct buffer;
152 * memset(&buffer, 0, sizeof(buffer));
153 * ret = silc_buffer_format(&buffer,
154 * SILC_STR_UINT32(intval),
155 * SILC_STR_UINT8(charval),
156 * SILC_STR_UINT32(intval),
157 * SILC_STR_UINT16(str_len),
158 * SILC_STR_DATA(str, str_len),
163 * // Free the allocated data
164 * silc_buffer_purge(&buffer);
166 * // Dynamically allocated zero size buffer
168 * buf = silc_buffer_alloc(0);
169 * ret = silc_buffer_format(buf,
170 * SILC_STR_UINT32(intval),
171 * SILC_STR_UINT8(charval),
176 * // Free the allocated buffer
177 * silc_buffer_free(buf);
179 * // Dynamically allocated buffer with enough space
181 * buf = silc_buffer_alloc(2 + str_len);
182 * ret = silc_buffer_format(buf,
183 * SILC_STR_UINT16(str_len),
184 * SILC_STR_DATA(str, str_len),
190 int silc_buffer_format(SilcBuffer dst, ...);
192 /****f* silcutil/silc_buffer_sformat
196 * int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
200 * Same as silc_buffer_format but uses `stack' to allocate the memory.
201 * if `stack' is NULL reverts back to silc_buffer_format call. Returns
202 * -1 if system is out of memory. Sets silc_errno in case of error.
204 * Note that this call consumes the `stack'. The caller should push the
205 * stack before calling the function and pop it later.
208 int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
210 /****f* silcutil/silc_buffer_format_vp
214 * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
218 * Formats a buffer from a variable argument list indicated by the `ap'.
219 * Returns -1 if system is out of memory and the length of the formatted
223 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
225 /****f* silcutil/silc_buffer_sformat_vp
229 * int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list vp);
233 * Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
234 * if `stack' is NULL reverts back to silc_buffer_format_vp call. Returns
235 * -1 if system is out of memory. Sets silc_errno in case of error.
237 * Note that this call consumes the `stack'. The caller should push the
238 * stack before calling the function and pop it later.
241 int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
243 /****f* silcutil/silc_buffer_unformat
247 * int silc_buffer_unformat(SilcBuffer src, ...);
251 * Unformats a buffer from a variable argument list. Returns -1 on error
252 * and the length of the unformatted buffer otherwise. Sets silc_errno
257 * ret = silc_buffer_unformat(buffer,
258 * SILC_STR_UINT32(&intval),
259 * SILC_STR_UINT8(&charval),
260 * SILC_STR_OFFSET(4),
261 * SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
267 int silc_buffer_unformat(SilcBuffer src, ...);
269 /****f* silcutil/silc_buffer_sunformat
273 * int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
277 * Same as silc_buffer_unformat but uses `stack' to allocate the memory.
278 * if `stack' is NULL reverts back to silc_buffer_format call.
280 * Note that this call consumes the `stack'. The caller should push the
281 * stack before calling the function and pop it later.
284 int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
286 /****f* silcutil/silc_buffer_unformat_vp
290 * int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
294 * Unformats a buffer from a variable argument list indicated by the `ap'.
295 * Returns -1 on error and the length of the unformatted buffer otherwise.
298 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
300 /****f* silcutil/silc_buffer_sunformat_vp
304 * int silc_buffer_sunformat_vp(SilcBuffer src, va_list vp);
308 * Same as silc_buffer_unformat_vp but uses `stack' to allocate the
309 * memory. if `stack' is NULL reverts back to silc_buffer_format_vp call.
311 * Note that this call consumes the `stack'. The caller should push the
312 * stack before calling the function and pop it later.
315 int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
317 /****f* silcutil/silc_buffer_strformat
321 * int silc_buffer_strformat(SilcBuffer dst, ...);
325 * Formats a buffer from variable argument list of strings. Each
326 * string must be NULL-terminated and the variable argument list must
327 * be end with SILC_STRFMT_END argument. This allows that a string in
328 * the list can be NULL, in which case it is skipped. This automatically
329 * allocates the space for the buffer data but `dst' must be already
330 * allocated by the caller. Returns -1 if system is out of memory and
335 * ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STRFMT_END);
340 int silc_buffer_strformat(SilcBuffer dst, ...);
342 /****f* silcutil/silc_buffer_sstrformat
346 * int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
350 * Formats a buffer from variable argument list of strings. Each
351 * string must be NULL-terminated and the variable argument list must
352 * be end with SILC_STRFMT_END argument. This allows that a string in
353 * the list can be NULL, in which case it is skipped. This automatically
354 * allocates the space for the buffer data but `dst' must be already
355 * allocated by the caller. This function is equivalent to
356 * silc_buffer_strformat but allocates memory from `stack'. Returns -1
357 * if system is out of memory and sets silc_errno.
359 * Note that this call consumes the `stack'. The caller should push the
360 * stack before calling the function and pop it later.
363 int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
365 /****d* silcutil/SILC_STR_SINT8
369 * #define SILC_STR_SINT8() ...
373 * One 8-bit signed integer.
375 * Formatting: SILC_STR_SINT8(SilcInt8)
376 * Unformatting: SILC_STR_SINT8(SilcInt8 *)
379 #define SILC_STR_SINT8(x) SILC_PARAM_SINT8, (x)
381 /****d* silcutil/SILC_STR_UINT8
385 * #define SILC_STR_UINT8() ...
389 * One 8-bit unsigned integer.
391 * Formatting: SILC_STR_UINT8(SilcUInt8)
392 * Unformatting: SILC_STR_UINT8(SilcUInt8 *)
395 #define SILC_STR_UINT8(x) SILC_PARAM_UINT8, (x)
398 #define SILC_STR_SI_CHAR(x) SILC_PARAM_SINT8, (x)
399 #define SILC_STR_UI_CHAR(x) SILC_PARAM_UINT8, (x)
401 /****d* silcutil/SILC_STR_SINT16
405 * #define SILC_STR_SINT16() ...
411 * Formatting: SILC_STR_SINT16(SilcInt16)
412 * Unformatting: SILC_STR_SINT16(SilcInt16 *)
415 #define SILC_STR_SINT16(x) SILC_PARAM_SINT16, (x)
417 /****d* silcutil/SILC_STR_UINT16
421 * #define SILC_STR_UINT16() ...
427 * Formatting: SILC_STR_UINT16(SilcUInt16)
428 * Unformatting: SILC_STR_UINT16(SilcUInt16 *)
431 #define SILC_STR_UINT16(x) SILC_PARAM_UINT16, (x)
434 #define SILC_STR_SI_SHORT(x) SILC_PARAM_SINT16, (x)
435 #define SILC_STR_UI_SHORT(x) SILC_PARAM_UINT16, (x)
437 /****d* silcutil/SILC_STR_SINT32
441 * #define SILC_STR_SINT32() ...
447 * Formatting: SILC_STR_SINT32(SilcInt32)
448 * Unformatting: SILC_STR_SINT32(SilcInt32 *)
451 #define SILC_STR_SINT32(x) SILC_PARAM_SINT32, (x)
453 /****d* silcutil/SILC_STR_UINT32
457 * #define SILC_STR_UINT32() ...
463 * Formatting: SILC_STR_UINT32(SilcUInt32)
464 * Unformatting: SILC_STR_UINT32(SilcUInt32 *)
467 #define SILC_STR_UINT32(x) SILC_PARAM_UINT32, (x)
470 #define SILC_STR_SI_INT(x) SILC_PARAM_SINT32, (x)
471 #define SILC_STR_UI_INT(x) SILC_PARAM_UINT32, (x)
473 /****d* silcutil/SILC_STR_SINT64
477 * #define SILC_STR_SINT64() ...
483 * Formatting: SILC_STR_SINT64(SilcInt64)
484 * Unformatting: SILC_STR_SINT64(SilcInt64 *)
487 #define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
489 /****d* silcutil/SILC_STR_UINT64
493 * #define SILC_STR_UINT64() ...
499 * Formatting: SILC_STR_UINT64(SilcUInt64)
500 * Unformatting: SILC_STR_UINT64(SilcUInt64 *)
503 #define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
506 #define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
507 #define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
509 /****d* silcutil/SILC_STR_STRING
513 * #define SILC_STR_STRING() ...
517 * Encode NULL terminated string. Use this only for formatting.
519 * Formatting: SILC_STR_STRING(char *)
521 * For unformatting use one of the SILC_STR_*_STRING macros, which
522 * automatically gets the length of the string from the buffer. Note
523 * SILC_STR_STRING does not save the length of the string into the buffer.
524 * The caller must do that in order for the unformatting macros to work.
528 * Formatting: ..., SILC_STR_UINT32(strlen(string)),
529 * SILC_STR_STRING(string), ...
530 * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
533 #define SILC_STR_STRING(x) SILC_PARAM_UI8_STRING, (x)
535 /****d* silcutil/SILC_STR_*_STRING
539 * #define SILC_STR_UI8_STRING() ...
540 * #define SILC_STR_UI8_STRING_ALLOC() ...
541 * #define SILC_STR_UI16_STRING() ...
542 * #define SILC_STR_UI16_STRING_ALLOC() ...
543 * #define SILC_STR_UI32_STRING() ...
544 * #define SILC_STR_UI32_STRING_ALLOC() ...
548 * Unsigned NULL terminated string. Note that the string must be
549 * NULL terminated because strlen() will be used to get the length of
552 * Formatting: SILC_STR_UI32_STRING(unsigned char *)
553 * Unformatting: SILC_STR_UI32_STRING(unsigned char **)
555 * Unformatting procedure will check for length of the string from the
556 * buffer before trying to get the string out. Thus, one *must* format the
557 * length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
558 * the actual string to the buffer, and, in unformatting one ignores the
559 * length of the string because unformatting procedure will take it
564 * Formatting: ..., SILC_STR_UINT32(strlen(string)),
565 * SILC_STR_UI32_STRING(string), ...
566 * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
568 * I.e., you can ignore the formatted length field in unformatting.
570 * UI8, UI16 and UI32 means that the length is considered to be
571 * either UINT8, UINT16 or UINT32 in unformatting.
573 * _ALLOC routines automatically allocates memory for the variable sent
574 * as argument in unformatting.
577 #define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
578 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING | SILC_PARAM_ALLOC, (x)
579 #define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
580 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING | SILC_PARAM_ALLOC, (x)
581 #define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
582 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING | SILC_PARAM_ALLOC, (x)
584 /****d* silcutil/SILC_STR_*_NSTRING
588 * #define SILC_STR_UI8_NSTRING() ...
589 * #define SILC_STR_UI8_NSTRING_ALLOC() ...
590 * #define SILC_STR_UI16_NSTRING() ...
591 * #define SILC_STR_UI16_NSTRING_ALLOC() ...
592 * #define SILC_STR_UI32_NSTRING() ...
593 * #define SILC_STR_UI32_NSTRING_ALLOC() ...
597 * Unsigned string. Second argument is the length of the string.
599 * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
600 * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
602 * Unformatting procedure will check for length of the string from the
603 * buffer before trying to get the string out. Thus, one *must* format the
604 * length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
605 * the actual string to the buffer, and, in unformatting one ignores the
606 * length of the string because unformatting procedure will take it
611 * Formatting: ..., SILC_STR_UINT32(strlen(string)),
612 * SILC_STR_UI32_NSTRING(string, strlen(string)), ...
613 * Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ...
615 * I.e., you can ignore the formatted length field in unformatting. The
616 * length taken from the buffer is returned to the pointer sent as
617 * argument (&len in above example).
619 * UI8, UI16 and UI32 means that the length is considered to be
620 * either UINT8, UINT16 or UINT32 in unformatting.
622 * _ALLOC routines automatically allocates memory for the variable sent
623 * as argument in unformatting.
626 #define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
627 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
628 SILC_PARAM_UI8_NSTRING | SILC_PARAM_ALLOC, (x), (l)
629 #define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)
630 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
631 SILC_PARAM_UI16_NSTRING | SILC_PARAM_ALLOC, (x), (l)
632 #define SILC_STR_UI32_NSTRING(x, l) SILC_PARAM_UI32_NSTRING, (x), (l)
633 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
634 SILC_PARAM_UI32_NSTRING | SILC_PARAM_ALLOC, (x), (l)
636 /****d* silcutil/SILC_STR_DATA
640 * #define SILC_STR_DATA() ...
641 * #define SILC_STR_DATA_ALLOC() ...
645 * Binary data formatting. Second argument is the length of the data.
647 * Formatting: SILC_STR_DATA(unsigned char *, SilcUInt32)
648 * Unformatting: SILC_STR_DATA(unsigned char **, SilcUInt32)
650 * This type can be used to take arbitrary size data block from the buffer
651 * by sending the requested amount of bytes as argument.
653 * _ALLOC routines automatically allocates memory for the variable sent
654 * as argument in unformatting.
657 #define SILC_STR_DATA(x, l) SILC_PARAM_UICHAR, (x), (l)
658 #define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
661 #define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UICHAR, (x), (l)
662 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
664 /****d* silcutil/SILC_STR_BUFFER
668 * #define SILC_STR_BUFFER() ...
669 * #define SILC_STR_BUFFER_ALLOC() ...
673 * SilcBuffer formatting.
675 * Formatting: SILC_STR_BUFFER(SilcBuffer)
676 * Unformatting: SILC_STR_BUFFER(SilcBuffer)
678 * This type can be used to format and unformat SilcBuffer. Note that, the
679 * length of the buffer will be automatically encoded into the buffer as
680 * a 32-bit integer. In unformatting the SilcBuffer context must be
683 * _ALLOC routines automatically allocates memory inside SilcBuffer in
687 #define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
688 #define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER | SILC_PARAM_ALLOC, (x)
690 /****d* silcutil/SILC_STR_REPLACE
694 * #define SILC_STR_REPLACE(unsigned char *data, SilcUInt32 len) ...
698 * Encode the `data' of length of `len' bytes into the buffer, replacing
701 * If the length of the current data area is equal to `len' the data area
702 * is replaced with `data'.
704 * If `len' is longer than the data area, it will be enlarged to fit the
705 * `data'. If there is data in the tail area, it will not be replaced,
706 * but the buffer is enlarged and the old tail area will be copied to the
707 * new tail area, thus preserving any data in the buffer (the data is
708 * in effect appended to the current data area).
710 * If `len' is shorter than than the data area, only the bytes in `data'
711 * are replaced, and rest are deleted from the data area. The buffer size
712 * is also reduced but no other data is lost in the process.
714 * If `len' is 0 but `data' is non-NULL, this will delete all bytes from
715 * the current data area. If `data' is NULL this macro has no effect to
718 * Use this only for formatting.
720 * Formatting: SILC_STR_REPLACE(unsigned char *, SilcUInt32)
725 * -------------------------
726 * | head | 12345 | 67890 |
727 * -------------------------
729 * After replacing with 12345XXX (appends)
730 * ----------------------------
731 * | head | 12345XXX | 67890 |
732 * ----------------------------
734 * After replacing with YYY (deletes)
735 * -----------------------
736 * | head | YYY | 67890 |
737 * -----------------------
740 #define SILC_STR_REPLACE(x, l) SILC_PARAM_UICHAR | SILC_PARAM_REPLACE, (x), (l)
742 /****d* silcutil/SILC_STR_FUNC
746 * #define SILC_STR_FUNC() ...
750 * Formatting and unformatting of arbitrary data.
752 * Formatting: SILC_STR_FUNC(function, void *value, void *context)
753 * Unformatting: SILC_STR_FUNC(function, void **value, void *context)
755 * This type can be used to call the `function' of the type
756 * SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
757 * the `value'. In encoding the `value' will be passed to the `function'
758 * and can be encoded into the buffer. The buffer will be passed as
759 * well to the `function' at the location where SILC_STR_FUNC is placed
760 * in formatting. The `context' delivers caller specific context to
763 * In unformatting the `function' will decode the encoded type and
764 * return it to `value' pointer. The decoding function should decide
765 * itself whether to allocate or not the decoded value.
767 * The `function' does not have to encode anything and passing `value'
768 * as NULL is allowed. The `function' could for example modify the
773 * // Encode payload, encrypt and compute MAC.
774 * silc_buffer_format(buf,
775 * SILC_STR_FUNC(foo_encode_id, id, ctx),
776 * SILC_STR_UINT16(len),
777 * SILC_STR_DATA(data, len),
778 * SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
779 * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
780 * SILC_STR_DATA(iv, iv_len);
783 * // Check MAC, decrypt and decode payload
784 * silc_buffer_unformat(buf,
785 * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
786 * SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
787 * SILC_STR_FUNC(foo_decode_id, &id, ctx),
788 * SILC_STR_UINT16(&len),
792 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
793 func, (val), (context)
795 /****d* silcutil/SilcBufferRegexFlags
799 * typedef enum { ... } SilcBufferRegexFlags;
803 * Regular expression flags for SILC_STR_REGEX macro. The flags can be
804 * used to manipulate the behavior of the SILC_STR_REGEX. All flags
805 * may be combined unless otherwise stated.
810 SILC_STR_REGEX_NONE = 0x00000000,
812 /* By default mismatch will be skipped. Skipping means that none of the
813 operations inside the SILC_STR_REGEX are executed. Set this flag if
814 mismatch should cause error and stopping of the formatting/unformatting. */
815 SILC_STR_REGEX_MISMATCH = 0x00000001,
817 /* By default only the first match is found. Set this flag to find
819 SILC_STR_REGEX_ALL = 0x00000002,
821 /* By default the buffer position is advanced to the position of the
822 first match. Set this flag if the buffer should not be advanced to
824 SILC_STR_REGEX_NO_ADVANCE = 0x00000004,
826 /* By default SILC_STR_REGEX performs the match on the whole buffer. Set
827 this flag to make it behave like sed and match line by line. Each line
828 must end with '\n'. If buffer doesn't have '\n' it is considered to be
829 one line. Note that, any formatting done immediately after SILC_STR_REGEX
830 block with this flag will be formatted to the end of the buffer (after
831 last line). Use SILC_STR_OFFSET* macros to change the position if
832 needed. Also note that, any encoding macro inside the SILC_STR_REGEX
833 block will see only the matched line (including '\n'), instead of whole
834 buffer after the match. */
835 SILC_STR_REGEX_NL = 0x00000008,
837 /* Set this flag to not match the regular expression, but to match everything
838 else. When combined with SILC_STR_REGEX_NL this flag matches all other
839 lines except the ones with matching regular expression. */
840 SILC_STR_REGEX_NOT = 0x00000010,
842 /* By default the buffer is advanced to the first match and the rest of the
843 buffer remains as is. Set this flag to pass the exact match to the
844 SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
845 the match and the end of the match, but not rest of the buffer (ie. with
846 match 'foo' the size of the buffer is 3 bytes). */
847 SILC_STR_REGEX_INCLUSIVE = 0x00000020,
848 } SilcBufferRegexFlags;
851 /****d* silcutil/SILC_STR_REGEX
855 * #define SILC_STR_REGEX() ...
859 * Regular expression matching within the buffer.
861 * Formatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
862 * Unformatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
864 * SILC_STR_REGEX can be used to do regular expression matching within
865 * the SilcBuffer. When the string in the buffer matches the regular
866 * expression the position of the buffer is advanced to the position of
867 * the first match (rest of the buffer remains intact). If the regular
868 * expression does not match it is skipped, unless the flags specify
869 * otherwise. If flags are not needed they can be set to 0.
871 * In addition of matching regular expressions it can be used in a
872 * Stream Editor (sed) and Awk like fashion. The regular expression can be
873 * matched and then edited by any of the SILC_STR_* macros. The flags
874 * can be used to perform complex operations on the data. Some sed
875 * features that cannot be directly done with the flags can be done with
876 * SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
879 * The SILC_STR_REGEX itself is used as an opening of a block of encoding
880 * macros and must be closed with SILC_STR_END. This means that for
881 * each SILC_STR_REGEX there must be one SILC_STR_END. See examples for
884 * The SILC_STR_REGEX can be used in buffer unformatting also to do
885 * string matching and parsing, but not editing, except with SILC_STR_FUNC
886 * macro, which can do anything caller wants.
888 * Typically the following encoding macros are used with SILC_STR_REGEX:
889 * SILC_STR_REPLACE, SILC_STR_STRING and SILC_STR_FUNC. If you use
890 * SILC_STR_REPLACE always set SILC_STR_REGEX_INCLUSIVE.
894 * // sed 's/foo/bar/', replace first foo with bar
895 * silc_buffer_format(buffer,
896 * SILC_STR_REGEX("foo", 0),
897 * SILC_STR_STRING("bar"),
898 * SILC_STR_END, SILC_STR_END);
900 * // sed 's/foo/barbar/g', replace all foo's with barbar, without
901 * // overwriting any data in the buffer, but appending it. The match
902 * // must be inclusive to make appending work.
903 * silc_buffer_format(buffer,
904 * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
905 * SILC_STR_REGEX_INCLUSIVE),
906 * SILC_STR_REPLACE("barbar", 5),
907 * SILC_STR_END, SILC_STR_END);
909 * // sed 's/foo/B/', replace foo with B, deleting rest of the match from
910 * // the buffer. The match must be inclusive to make deleting work.
911 * silc_buffer_format(buffer,
912 * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
913 * SILC_STR_REGEX_INCLUSIVE),
914 * SILC_STR_REPLACE("B", 1),
915 * SILC_STR_END, SILC_STR_END);
917 * // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
918 * silc_buffer_format(buffer,
919 * SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
920 * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
921 * SILC_STR_STRING("bar"),
923 * SILC_STR_END, SILC_STR_END);
925 * // Print all lines that start with 'R'
926 * int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
928 * return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
931 * silc_buffer_unformat(buffer,
932 * SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
933 * SILC_STR_FUNC(print, NULL, NULL),
934 * SILC_STR_END, SILC_STR_END);
937 #define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)
939 /****d* silcutil/SILC_STR_DELETE
943 * #define SILC_STR_DELETE(n) ...
947 * Deletes bytes from the buffer by moving data in order to delete it.
948 * The size of the buffer is also reduced, but no data is lost in the
951 * The `n' specifies the number of bytes to delete from the current
952 * data area. If `n' is -1 this deletes all bytes from the data area.
953 * This effectively moves the data from the tail area into the current
954 * data area. The length of the data area after this is 0.
956 * Use this only for formatting.
958 * Formatting: SILC_STR_DELETE(int bytes)
961 #define SILC_STR_DELETE(x) SILC_PARAM_DELETE, (x)
963 /****d* silcutil/SILC_STR_OFFSET
967 * #define SILC_STR_OFFSET() ...
971 * Offset in buffer. This can be used in formatting and unformatting to
972 * move the data pointer of the buffer either forwards (positive offset)
973 * or backwards (negative offset). It can be used to for example skip
974 * some types during unformatting.
978 * ..., SILC_STR_OFFSET(5), ...
979 * ..., SILC_STR_OFFSET(-3), ...
981 * Moves the data pointer at the point of the offset either forward
982 * or backward and then moves to the next type. Multiple SILC_STR_OFFSETs
983 * can be used in formatting and unformatting at the same time.
986 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
988 /****d* silcutil/SILC_STR_OFFSET_START
992 * #define SILC_STR_OFFSET_START ...
996 * Moves the buffer position to the start of the data area.
1000 * ..., SILC_STR_OFFSET_START, ...
1003 #define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
1005 /****d* silcutil/SILC_STR_OFFSET_END
1009 * #define SILC_STR_OFFSET_END ...
1013 * Moves the buffer position to the end of the data area.
1017 * ..., SILC_STR_OFFSET_END, ...
1020 #define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
1022 /****d* silcutil/SILC_STR_ADVANCE
1026 * #define SILC_STR_ADVANCE ...
1030 * Advance the buffer to the end of the data after the formatting is
1031 * done. In normal operation when the formatted data is written the
1032 * buffer is positioned at the start of the data. With SILC_STR_ADVANCE
1033 * the buffer will be positioned at the end of the data. This makes it
1034 * easy to add new data immediately after the previously added data.
1035 * The SILC_STR_ADVANCE may also be used in unformatting.
1040 * len = read(fd, buf, sizeof(buf));
1042 * // Add read data to the buffer
1043 * silc_buffer_format(buffer,
1045 * SILC_STR_DATA(buf, len),
1047 * } while (len > 0);
1049 * // Move to beginning of buffer
1050 * silc_buffer_start(buffer);
1053 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
1055 /****d* silcutil/SILC_STR_END
1059 * #define SILC_STR_END ...
1063 * Marks end of the argument list. This must be at the end of the
1064 * argument list or error will occur.
1067 #define SILC_STR_END SILC_PARAM_END
1069 /****d* silcutil/SILC_STRFMT_END
1073 * #define SILC_STRFMT_END ...
1077 * Marks end of the argument list in silc_buffer_strformat function.
1078 * This must be at the end of the argument list or error will occur.
1081 #define SILC_STRFMT_END (void *)SILC_STR_END
1083 #endif /* !SILCBUFFMT_H */