org.simantics.fmil.core/native/FMILibrary/ThirdParty/c99_snprintf/c99-snprintf_1.1/README

   1 $Id: README,v 1.1.1.1 2008/01/06 03:24:00 holger Exp $
   2
   3 README file for C99-snprintf
   4 ============================
   5
   6
   7 OVERVIEW
   8 --------
   9
  10 C99-snprintf provides a portable implementation of snprintf(3),
  11 vsnprintf(3), asprintf(3), and vasprintf(3).  It should be fully C99
  12 compliant, with the exceptions that it doesn't provide wide character
  13 support and that "%a" and "%A" conversions aren't supported.
  14 C99-snprintf should be buildable with any ANSI C compiler, it doesn't
  15 require libc functionality other than malloc(3) (for vasprintf(3)) and
  16 the stdarg(3) or varargs(3) macros, and it has no other prerequisites.
  17
  18 The snprintf(3) and vsnprintf(3) functions are part of the C99 standard
  19 library.  However, snprintf(3) and vsnprintf(3) weren't included in the
  20 C89/C90 standards and some systems don't provide C99 compliant
  21 implementations of these functions.  For example, if the ouput buffer
  22 isn't big enough to hold the full conversion result, IRIX up to the
  23 current release 6.5.30 and glibc up to 2.0.x don't return the same value
  24 as with a sufficiently sized buffer (which makes it impossible to
  25 precompute the required buffer size), and some older systems (such as
  26 64-bit Solaris 7) ignore the specified buffer size and overrun the
  27 buffer if it's too small.  The asprintf(3) and vasprintf(3) functions
  28 aren't standardized at all.  They're included with recent releases of
  29 glibc and BSD's libc, but they aren't available on other systems, such
  30 as System V (e.g., Solaris).
  31
  32 So, if any of these functions are used, portable software should include
  33 replacement code which is used in case the functions aren't available or
  34 don't work correctly on the target system.  C99-snprintf can be included
  35 with software packages in order to provide such replacement functions.
  36
  37
  38 USAGE
  39 -----
  40
  41 1) Add snprintf.c to your project files.  If you're using GNU Automake,
  42    you could use a line such as "foo_LDADD = $(LIBOBJS)" (where "foo" is
  43    the name of your program) in your Makefile.am.
  44
  45 2) Add snprintf.m4 to your m4 include directory or to your acinclude.m4
  46    file.  If you're using neither, you can simply include the contents
  47    of snprintf.m4 in your configure.ac file.
  48
  49 3) For each replacement function which might be needed in your project,
  50    call the according Autoconf macro in your configure.ac file.  That
  51    is, in order to have all four replacement functions available if
  52    needed:
  53
  54         HW_FUNC_VSNPRINTF
  55         HW_FUNC_SNPRINTF
  56         HW_FUNC_VASPRINTF
  57         HW_FUNC_ASPRINTF
  58
  59 4) The required replacement functions should be declared in some header
  60    file included throughout your project files:
  61
  62         #if HAVE_CONFIG_H
  63         #include <config.h>
  64         #endif
  65         #if HAVE_STDARG_H
  66         #include <stdarg.h>
  67         #if !HAVE_VSNPRINTF
  68         int rpl_vsnprintf(char *, size_t, const char *, va_list);
  69         #endif
  70         #if !HAVE_SNPRINTF
  71         int rpl_snprintf(char *, size_t, const char *, ...);
  72         #endif
  73         #if !HAVE_VASPRINTF
  74         int rpl_vasprintf(char **, const char *, va_list);
  75         #endif
  76         #if !HAVE_ASPRINTF
  77         int rpl_asprintf(char **, const char *, ...);
  78         #endif
  79         #endif  /* HAVE_STDARG_H */
  80
  81
  82 USAGE WITHOUT GNU AUTOCONF
  83 --------------------------
  84
  85 If you're not using GNU Autoconf, omit the steps 2 and 3 from the above
  86 instructions.  Instead:
  87
  88 1) The following preprocessor macros should be defined to 1 if the
  89    feature or file in question is available on the target system (though
  90    basic functionality should be available as long as HAVE_STDARG_H is
  91    defined correctly):
  92
  93         HAVE_VSNPRINTF
  94         HAVE_SNPRINTF
  95         HAVE_VASPRINTF
  96         HAVE_ASPRINTF
  97         HAVE_STDARG_H
  98         HAVE_STDDEF_H
  99         HAVE_STDINT_H
 100         HAVE_STDLIB_H
 101         HAVE_INTTYPES_H
 102         HAVE_LOCALE_H
 103         HAVE_LOCALECONV
 104         HAVE_LCONV_DECIMAL_POINT
 105         HAVE_LCONV_THOUSANDS_SEP
 106         HAVE_LONG_DOUBLE
 107         HAVE_LONG_LONG_INT
 108         HAVE_UNSIGNED_LONG_LONG_INT
 109         HAVE_INTMAX_T
 110         HAVE_UINTMAX_T
 111         HAVE_UINTPTR_T
 112         HAVE_PTRDIFF_T
 113         HAVE_VA_COPY
 114         HAVE___VA_COPY
 115
 116 2) The calls to the functions which should be replaced must be redefined
 117    throughout the project files:
 118
 119         #define vsnprintf rpl_vsnprintf
 120         #define snprintf rpl_snprintf
 121         #define vasprintf rpl_vasprintf
 122         #define asprintf rpl_asprintf
 123
 124
 125 BUGS AND CAVEATS
 126 ----------------
 127
 128 Depending on the size of the largest integer type available on the
 129 target platform, floating point precisions larger than 9, 19, or 38 are
 130 not supported.  If a larger precision is specified, it will silently be
 131 reduced to the largest possible precision on the target system.
 132
 133 If the integral part of a floating point value doesn't fit into the
 134 largest integer type available on the target platform, the conversion
 135 will fail.  In this case, C99-snprintf will return -1 and set the global
 136 variable errno to indicate the error.  The same is done if the specified
 137 field width or precision are (or if the return value would be) larger
 138 than INT_MAX.
 139
 140 C99-snprintf makes a few assumptions regarding integer (and pointer
 141 value) conversions which aren't backed by the C standard, but which
 142 should be safe in practice.
 143
 144
 145 FEEDBACK
 146 --------
 147
 148 Please let me know if you have any comments or bug reports regarding
 149 C99-snprintf:
 150
 151         Holger Weiss <holger@jhweiss.de>
 152
 153 # vim: set joinspaces textwidth=72 filetype=none: