Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2007 Pekka Riikonen
+ Copyright (C) 2007 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*/
+/****h* silcutil/Snprintf Interface
+ *
+ * DESCRIPTION
+ *
+ * Platform independent version of snprintf and other similar string
+ * formatting routines.
+ *
+ ***/
+
#ifndef SILCSNPRINTF_H
#define SILCSNPRINTF_H
-/****f* silcutil/SilcSnprintf/silc_snprintf
+/****f* silcutil/SilcSnprintfRender
+ *
+ * SYNOPSIS
+ *
+ * typedef char *(*SilcSnprintfRender)(void *data);
+ *
+ * DESCRIPTION
+ *
+ * Snprintf rendering function. This function can be used with '%@'
+ * formatting character. The `data' is rendered into a string and
+ * allocated string is returned. If NULL is returned the rendering
+ * is skipped and ignored. If the returned string does not fit to
+ * the destination buffer it may be truncated.
+ *
+ * EXAMPLE
+ *
+ * char *id_render(void *data)
+ * {
+ * ...render...
+ * return id_string;
+ * }
+ *
+ * // Call id_render function to render the 'client_id'.
+ * silc_snprintf(buf, sizeof(buf), "Client ID %@", id_render, client_id);
+ *
+ ***/
+typedef char *(*SilcSnprintfRender)(void *data);
+
+/****f* silcutil/silc_snprintf
*
* SYNOPSIS
*
* snprintf(3) and printf(3) formatting. Returns the number of character
* in `str' or negative value on error.
*
+ * This also supports '%@' formatting to render data and structures
+ * using SilcSnprintfRender.
+ *
***/
int silc_snprintf(char *str, size_t count, const char *fmt, ...);
-/****f* silcutil/SilcSnprintf/silc_vsnprintf
+/****f* silcutil/silc_vsnprintf
*
* SYNOPSIS
*
***/
int silc_vsnprintf(char *str, size_t count, const char *fmt, va_list args);
-/****f* silcutil/SilcSnprintf/silc_asprintf
+/****f* silcutil/silc_asprintf
*
* SYNOPSIS
*
***/
int silc_asprintf(char **ptr, const char *format, ...);
-/****f* silcutil/SilcSnprintf/silc_vasprintf
+/****f* silcutil/silc_vasprintf
*
* SYNOPSIS
*