--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/snprintf_2.2/README Sat Jan 19 19:14:36 2002 +0100
@@ -0,0 +1,283 @@
+
+ snprintf.c
+ - a portable implementation of snprintf,
+ including vsnprintf.c, asnprintf, vasnprintf, asprintf, vasprintf
+
+ snprintf is a routine to convert numeric and string arguments to
+ formatted strings. It is similar to sprintf(3) provided in a system's
+ C library, yet it requires an additional argument - the buffer size -
+ and it guarantees never to store anything beyond the given buffer,
+ regardless of the format or arguments to be formatted. Some newer
+ operating systems do provide snprintf in their C library, but many do
+ not or do provide an inadequate (slow or idiosyncratic) version, which
+ calls for a portable implementation of this routine.
+
+Author
+
+ Mark Martinec <mark.martinec@ijs.si>, April 1999, June 2000
+ Copyright © 1999, Mark Martinec
+
+Terms and conditions ...
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the Frontier Artistic License which comes with
+ this Kit.
+
+Features
+
+ * careful adherence to specs regarding flags, field width and
+ precision;
+ * good performance for large string handling (large format, large
+ argument or large paddings). Performance is similar to system's
+ sprintf and in several cases significantly better (make sure you
+ compile with optimizations turned on, tell the compiler the code
+ is strict ANSI if necessary to give it more freedom for
+ optimizations);
+ * return value semantics per ISO/IEC 9899:1999 ("ISO C99");
+ * written in standard ISO/ANSI C - requires an ANSI C compiler.
+
+Supported conversion specifiers and data types
+
+ This snprintf only supports the following conversion specifiers: s, c,
+ d, o, u, x, X, p (and synonyms: i, D, U, O - see below) with flags:
+ '-', '+', ' ', '0' and '#'. An asterisk is supported for field width
+ as well as precision.
+
+ Length modifiers 'h' (short int), 'l' (long int), and 'll' (long long
+ int) are supported.
+
+ NOTE:
+
+ If macro SNPRINTF_LONGLONG_SUPPORT is not defined (default) the
+ length modifier 'll' is recognized but treated the same as 'l',
+ which may cause argument value truncation! Defining
+ SNPRINTF_LONGLONG_SUPPORT requires that your system's sprintf also
+ handles length modifier 'll'. long long int is a language extension
+ which may not be portable.
+
+ Conversion of numeric data (conversion specifiers d, o, u, x, X, p)
+ with length modifiers (none or h, l, ll) is left to the system routine
+ sprintf, but all handling of flags, field width and precision as well
+ as c and s conversions is done very carefully by this portable
+ routine. If a string precision (truncation) is specified (e.g. %.8s)
+ it is guaranteed the string beyond the specified precision will not be
+ referenced.
+
+ Length modifiers h, l and ll are ignored for c and s conversions (data
+ types wint_t and wchar_t are not supported).
+
+ The following common synonyms for conversion characters are supported:
+ * i is a synonym for d
+ * D is a synonym for ld, explicit length modifiers are ignored
+ * U is a synonym for lu, explicit length modifiers are ignored
+ * O is a synonym for lo, explicit length modifiers are ignored
+
+ The D, O and U conversion characters are nonstandard, they are
+ supported for backward compatibility only, and should not be used for
+ new code.
+
+ The following is specifically not supported:
+ * flag ' (thousands' grouping character) is recognized but ignored
+ * numeric conversion specifiers: f, e, E, g, G and synonym F, as
+ well as the new a and A conversion specifiers
+ * length modifier 'L' (long double) and 'q' (quad - use 'll'
+ instead)
+ * wide character/string conversions: lc, ls, and nonstandard
+ synonyms C and S
+ * writeback of converted string length: conversion character n
+ * the n$ specification for direct reference to n-th argument
+ * locales
+
+ It is permitted for str_m to be zero, and it is permitted to specify
+ NULL pointer for resulting string argument if str_m is zero (as per
+ ISO C99).
+
+ The return value is the number of characters which would be generated
+ for the given input, excluding the trailing null. If this value is
+ greater or equal to str_m, not all characters from the result have
+ been stored in str, output bytes beyond the (str_m-1) -th character
+ are discarded. If str_m is greater than zero it is guaranteed the
+ resulting string will be null-terminated.
+
+ NOTE that this matches the ISO C99, OpenBSD, and GNU C library 2.1,
+ but is different from some older and vendor implementations, and is
+ also different from XPG, XSH5, SUSv2 specifications. For historical
+ discussion on changes in the semantics and standards of snprintf see
+ printf(3) man page in the Linux programmers manual.
+
+ Routines asprintf and vasprintf return a pointer (in the ptr argument)
+ to a buffer sufficiently large to hold the resulting string. This
+ pointer should be passed to free(3) to release the allocated storage
+ when it is no longer needed. If sufficient space cannot be allocated,
+ these functions will return -1 and set ptr to be a NULL pointer. These
+ two routines are a GNU C library extensions (glibc).
+
+ Routines asnprintf and vasnprintf are similar to asprintf and
+ vasprintf, yet, like snprintf and vsnprintf counterparts, will write
+ at most str_m-1 characters into the allocated output string, the last
+ character in the allocated buffer then gets the terminating null. If
+ the formatted string length (the return value) is greater than or
+ equal to the str_m argument, the resulting string was truncated and
+ some of the formatted characters were discarded. These routines
+ present a handy way to limit the amount of allocated memory to some
+ sane value.
+
+Availability
+
+ http://www.ijs.si/software/snprintf/
+ * snprintf_1.3.tar.gz (1999-06-30), md5 sum: snprintf_1.3.tar.gz.md5
+ * snprintf_2.1.tar.gz (2000-07-14), md5 sum: snprintf_2.1.tar.gz.md5
+ * snprintf_2.2.tar.gz (2000-10-18), md5 sum: snprintf_2.2.tar.gz.md5
+
+Mailing list
+
+ There is a very low-traffic mailing list snprintf-announce@ijs.si
+ where announcements about new versions will be posted as well as
+ warnings about threatening bugs if discovered. The posting is
+ restricted to snprintf developer(s).
+
+ To subscribe to (or unsubscribe from) the mailing list please visit
+ the list server's web page
+ http://mailman.ijs.si/listinfo/snprintf-announce
+
+ You can also subscribe to the list by mailing the command SUBSCRIBE
+ either in the subject or in the message body to the address
+ snprintf-announce-request@ijs.si . You will be asked for confirmation
+ before subscription will be effective.
+
+ The list of members is only accessible to the list administrator, so
+ there is no need for concern about automatic e-mail address gatherers.
+
+ Questions about the mailing list and concerns for the attention of a
+ person should be sent to snprintf-announce-admin@ijs.si
+
+ There is no general discussion list about portable snprintf at the
+ moment. Please send comments and suggestion to the author.
+
+Revision history
+
+ Version 1.3 fixes a runaway loop problem from 1.2. Please upgrade.
+
+ 1999-06-30 V1.3 Mark Martinec <mark.martinec@ijs.si>
+
+ + fixed runaway loop (eventually crashing when str_l wraps
+ beyond 2^31) while copying format string without conversion
+ specifiers to a buffer that is too short (thanks to Edwin
+ Young <edwiny@autonomy.com> for spotting the problem);
+ + added macros PORTABLE_SNPRINTF_VERSION_(MAJOR|MINOR) to
+ snprintf.h
+
+ 2000-02-14 V2.0 (never released) Mark Martinec <mark.martinec@ijs.si>
+
+ + relaxed license terms: The Artistic License now applies. You
+ may still apply the GNU GENERAL PUBLIC LICENSE as was
+ distributed with previous versions, if you prefer;
+ + changed REVISION HISTORY dates to use ISO 8601 date format;
+ + added vsnprintf (patch also independently proposed by Caolán
+ McNamara 2000-05-04, and Keith M Willenson 2000-06-01)
+
+ 2000-06-27 V2.1 Mark Martinec <mark.martinec@ijs.si>
+
+ + removed POSIX check for str_m < 1; value 0 for str_m is
+ allowed by ISO C99 (and GNU C library 2.1) (pointed out on
+ 2000-05-04 by Caolán McNamara, caolan@ csn dot ul dot ie).
+ Besides relaxed license this change in standards adherence is
+ the main reason to bump up the major version number;
+ + added nonstandard routines asnprintf, vasnprintf, asprintf,
+ vasprintf that dynamically allocate storage for the resulting
+ string; these routines are not compiled by default, see
+ comments where NEED_V?ASN?PRINTF macros are defined;
+ + autoconf contributed by Caolán McNamara
+
+ 2000-10-06 V2.2 Mark Martinec <mark.martinec@ijs.si>
+
+ + BUG FIX: the %c conversion used a temporary variable that was
+ no longer in scope when referenced, possibly causing
+ incorrect resulting character;
+ + BUG FIX: make precision and minimal field width unsigned to
+ handle huge values (2^31 <= n < 2^32) correctly; also be more
+ careful in the use of signed/unsigned/size_t internal
+ variables -- probably more careful than many vendor
+ implementations, but there may still be a case where huge
+ values of str_m, precision or minimal field could cause
+ incorrect behaviour;
+ + use separate variables for signed/unsigned arguments, and for
+ short/int, long, and long long argument lengths to avoid
+ possible incompatibilities on certain computer architectures.
+ Also use separate variable arg_sign to hold sign of a numeric
+ argument, to make code more transparent;
+ + some fiddling with zero padding and "0x" to make it Linux
+ compatible;
+ + systematically use macros fast_memcpy and fast_memset instead
+ of case-by-case hand optimization; determine some breakeven
+ string lengths for different architectures;
+ + terminology change: format -> conversion specifier, C9x ->
+ ISO/IEC 9899:1999 ("ISO C99"), alternative form -> alternate
+ form, data type modifier -> length modifier;
+ + several comments rephrased and new ones added;
+ + make compiler not complain about 'credits' defined but not
+ used;
+
+Other implementations of snprintf
+
+ I am aware of some other (more or less) portable implementations of
+ snprintf. I do not claim they are free software - please refer to
+ their respective copyright and licensing terms. If you know of other
+ versions please let me know.
+ * a very thorough implementation (src/util_snprintf.c) by the Apache
+ Group distributed with the Apache web server -
+ http://www.apache.org/ . Does its own floating point conversions
+ using routines ecvt(3), fcvt(3) and gcvt(3) from the standard C
+ library or from the GNU libc.
+ This is from the code:
+
+ This software [...] was originally based on public domain software
+ written at the National Center for Supercomputing Applications,
+ University of Illinois, Urbana-Champaign.
+ [...] This code is based on, and used with the permission of, the
+ SIO stdio-replacement strx_* functions by Panos Tsirigotis
+ <panos@alumni.cs.colorado.edu> for xinetd.
+ * QCI Utilities use a modified version of snprintf from the Apache
+ group.
+ * implementations as distributed with OpenBSD, FreeBSD, and NetBSD
+ are all wrappers to vfprintf.c, which is derived from software
+ contributed to Berkeley by Chris Torek.
+ * implementation from Prof. Patrick Powell <papowell@sdsu.edu>,
+ Dept. Electrical and Computer Engineering, San Diego State
+ University, San Diego, CA 92182-1309, published in Bugtraq
+ archives for 3rd quarter (Jul-Aug) 1995. No floating point
+ conversions.
+ * Brandon Long's <blong@fiction.net> modified version of Prof.
+ Patrick Powell's snprintf with contributions from others. With
+ minimal floating point support.
+ * implementation (src/snprintf.c) as distributed with sendmail -
+ http://www.sendmail.org/ is a cleaned up Prof. Patrick Powell's
+ version to compile properly and to support .precision and %lx.
+ * implementation from Caolán McNamara available at
+ http://www.csn.ul.ie/~caolan/publink/snprintf-1.1.tar.gz, handles
+ floating point.
+ * implementation used by newlog (a replacement for syslog(3)) made
+ available by the SOS Corporation. Enabling floating point support
+ is a compile-time option.
+ * implementation by Michael Richardson <mcr@metis.milkyway.com> is
+ available at http://sandelman.ottawa.on.ca/SSW/snp/snp.html. It is
+ based on BSD44-lite's vfprintf() call, modified to function on
+ SunOS. Needs internal routines from the 4.4 strtod (included),
+ requires GCC to compile the long long (aka quad_t) portions.
+ * implementation from Tomi Salo <ttsalo@ssh.fi> distributed with SSH
+ 2.0 Unix Server. Not in public domain. Floating point conversions
+ done by system's sprintf.
+ * and for completeness: my portable version described in this very
+ document available at http://www.ijs.si/software/snprintf/ .
+
+ In retrospect, it appears that a lot of effort was wasted by many
+ people for not being aware of what others are doing. Sigh.
+
+ Also of interest: The Approved Base Working Group Resolution for XSH5,
+ Ref: bwg98-006, Topic: snprintf.
+ _________________________________________________________________
+
+ mm
+ Last updated: 2000-10-18
+
+ Valid HTML 4.0! 