Added.

[silc.git] / lib / silcutil / silcbuffmt.h

diff --git a/lib/silcutil/silcbuffmt.h b/lib/silcutil/silcbuffmt.h
index cd654de55ee6a36151a5e39d58a435070d12c925..d1745d1a8b85428111d01a858b68ba1d89094f7f 100644 (file)
--- a/lib/silcutil/silcbuffmt.h
+++ b/lib/silcutil/silcbuffmt.h
@@ -30,6 +30,21 @@
  * in multithreaded environment with a same SilcBuffer context without
  * concurrency control.
  *
+ * EXAMPLE
+ *
+ * SilcBufferStruct buffer;
+ *
+ * memset(&buffer, 0, sizeof(buffer));
+ * ret = silc_buffer_format(&buffer,
+ *                          SILC_STR_UI_INT(intval),
+ *                          SILC_STR_CHAR(charval),
+ *                          SILC_STR_UI_INT(intval),
+ *                          SILC_STR_SHORT(str_len),
+ *                          SILC_STR_DATA(str, str_len),
+ *                          SILC_STR_END);
+ * if (ret < 0)
+ *   error;
+ *
  ***/
 
 #ifndef SILCBUFFMT_H
@@ -105,10 +120,10 @@ typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer,
  *
  * DESCRIPTION
  *
- *    Formats a buffer from a variable argument list.  Returns -1 on error
- *    and the length of the formatted buffer otherwise.  The buffer is
- *    enlarged automatically during formatting, if it doesn't already have
- *    enough space.
+ *    Formats a buffer from a variable argument list.  Returns -1 if the
+ *    system is out of memory and the length of the formatted buffer otherwise.
+ *    The buffer is enlarged automatically during formatting, if it doesn't
+ *    already have enough space.
  *
  * EXAMPLE
  *
@@ -166,7 +181,8 @@ int silc_buffer_format(SilcBuffer dst, ...);
  * DESCRIPTION
  *
  *    Same as silc_buffer_format but uses `stack' to allocate the memory.
- *    if `stack' is NULL reverts back to silc_buffer_format call.
+ *    if `stack' is NULL reverts back to silc_buffer_format call.  Returns
+ *    -1 if system is out of memory.
  *
  *    Note that this call consumes the `stack'.  The caller should push the
  *    stack before calling the function and pop it later.
@@ -183,7 +199,8 @@ int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
  * DESCRIPTION
  *
  *    Formats a buffer from a variable argument list indicated by the `ap'.
- *    Returns -1 on error and the length of the formatted buffer otherwise.
+ *    Returns -1 if system is out of memory and the length of the formatted
+ *    buffer otherwise.
  *
  ***/
 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
@@ -197,7 +214,8 @@ int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
  * DESCRIPTION
  *
  *    Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
- *    if `stack' is NULL reverts back to silc_buffer_format_vp call.
+ *    if `stack' is NULL reverts back to silc_buffer_format_vp call.  Returns
+ *    -1 if system is out of memory.
  *
  *    Note that this call consumes the `stack'.  The caller should push the
  *    stack before calling the function and pop it later.
@@ -291,7 +309,7 @@ int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
  *    be end with SILC_STRFMT_END argument.  This allows that a string in
  *    the list can be NULL, in which case it is skipped.  This automatically
  *    allocates the space for the buffer data but `dst' must be already
- *    allocated by the caller.
+ *    allocated by the caller.  Returns -1 if system is out of memory.
  *
  * EXAMPLE
  *
@@ -316,7 +334,8 @@ int silc_buffer_strformat(SilcBuffer dst, ...);
  *    the list can be NULL, in which case it is skipped.  This automatically
  *    allocates the space for the buffer data but `dst' must be already
  *    allocated by the caller.  This function is equivalent to
- *    silc_buffer_strformat but allocates memory from `stack'.
+ *    silc_buffer_strformat but allocates memory from `stack'.  Returns -1
+ *    if system is out of memory.
  *
  *    Note that this call consumes the `stack'.  The caller should push the
  *    stack before calling the function and pop it later.