lib/silcutil/silcsnprintf.h

   1 /*
   2
   3   silcsnprintf.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcutil/Snprintf
  21  *
  22  * DESCRIPTION
  23  *
  24  * Platform independent version of snprintf and other similar string
  25  * formatting routines.
  26  *
  27  ***/
  28
  29 #ifndef SILCSNPRINTF_H
  30 #define SILCSNPRINTF_H
  31
  32 /****f* silcutil/SilcSnprintf/SilcSnprintfRender
  33  *
  34  * SYNOPSIS
  35  *
  36  *    typedef char *(*SilcSnprintfRender)(void *data);
  37  *
  38  * DESCRIPTION
  39  *
  40  *    Snprintf rendering function.  This function can be used with '%@'
  41  *    formatting character.  The `data' is rendered into a string and
  42  *    allocated string is returned.  If NULL is returned the rendering
  43  *    is skipped and ignored.  If the returned string does not fit to
  44  *    the destination buffer it may be truncated.
  45  *
  46  * EXAMPLE
  47  *
  48  *    char *id_render(void *data)
  49  *    {
  50  *      ...render...
  51  *      return id_string;
  52  *    }
  53  *
  54  *    // Call id_render function to render the 'client_id'.
  55  *    silc_snprintf(buf, sizeof(buf), "Client ID %@", id_render, client_id);
  56  *
  57  ***/
  58 typedef char *(*SilcSnprintfRender)(void *data);
  59
  60 /****f* silcutil/SilcSnprintf/silc_snprintf
  61  *
  62  * SYNOPSIS
  63  *
  64  *    int silc_snprintf(char *str, size_t count, const char *fmt, ...);
  65  *
  66  * DESCRIPTION
  67  *
  68  *    Outputs string into `str' of maximum of size `count' including the
  69  *    trailing '\0' according to the `fmt'.  The `fmt' is equivalent to
  70  *    snprintf(3) and printf(3) formatting.  Returns the number of character
  71  *    in `str' or negative value on error.
  72  *
  73  *    This also supports '%@' formatting to render data and structures
  74  *    using SilcSnprintfRender.
  75  *
  76  ***/
  77 int silc_snprintf(char *str, size_t count, const char *fmt, ...);
  78
  79 /****f* silcutil/SilcSnprintf/silc_vsnprintf
  80  *
  81  * SYNOPSIS
  82  *
  83  *    int silc_vsnprintf(char *str, size_t count, const char *fmt,
  84  *                       va_list args)
  85  *
  86  * DESCRIPTION
  87  *
  88  *    Same as silc_snprintf but takes the argument for the formatting from
  89  *    the `args' variable argument list.
  90  *
  91  ***/
  92 int silc_vsnprintf(char *str, size_t count, const char *fmt, va_list args);
  93
  94 /****f* silcutil/SilcSnprintf/silc_asprintf
  95  *
  96  * SYNOPSIS
  97  *
  98  *    int silc_asprintf(char **ptr, const char *format, ...)
  99  *
 100  * DESCRIPTION
 101  *
 102  *    Same as silc_snprintf but allocates a string large enough to hold the
 103  *    output including the trailing '\0'.  The caller must free the `ptr'.
 104  *
 105  ***/
 106 int silc_asprintf(char **ptr, const char *format, ...);
 107
 108 /****f* silcutil/SilcSnprintf/silc_vasprintf
 109  *
 110  * SYNOPSIS
 111  *
 112  *    int silc_vasprintf(char **ptr, const char *format, va_list ap)
 113  *
 114  * DESCRIPTION
 115  *
 116  *    Same as silc_asprintf but takes the argument from the `ap' variable
 117  *    argument list.
 118  *
 119  ***/
 120 int silc_vasprintf(char **ptr, const char *format, va_list ap);
 121
 122 #endif /* SILCSNPRINTF_H */