1 $Id: README,v 1.1.1.1 2008/01/06 03:24:00 holger Exp $
3 README file for C99-snprintf
4 ============================
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.
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).
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.
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.
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.
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
59 4) The required replacement functions should be declared in some header
60 file included throughout your project files:
68 int rpl_vsnprintf(char *, size_t, const char *, va_list);
71 int rpl_snprintf(char *, size_t, const char *, ...);
74 int rpl_vasprintf(char **, const char *, va_list);
77 int rpl_asprintf(char **, const char *, ...);
79 #endif /* HAVE_STDARG_H */
82 USAGE WITHOUT GNU AUTOCONF
83 --------------------------
85 If you're not using GNU Autoconf, omit the steps 2 and 3 from the above
86 instructions. Instead:
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
104 HAVE_LCONV_DECIMAL_POINT
105 HAVE_LCONV_THOUSANDS_SEP
108 HAVE_UNSIGNED_LONG_LONG_INT
116 2) The calls to the functions which should be replaced must be redefined
117 throughout the project files:
119 #define vsnprintf rpl_vsnprintf
120 #define snprintf rpl_snprintf
121 #define vasprintf rpl_vasprintf
122 #define asprintf rpl_asprintf
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.
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
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.
148 Please let me know if you have any comments or bug reports regarding
151 Holger Weiss <holger@jhweiss.de>
153 # vim: set joinspaces textwidth=72 filetype=none: