--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/snprintf_2.2/README.html	Sat Jan 19 19:14:36 2002 +0100
@@ -0,0 +1,382 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rev="made" href="mailto:mark.martinec@ijs.si">
+<title>
+snprintf.c - a portable implementation of snprintf
+(including vsnprintf.c, asnprintf, vasnprintf, asprintf, vasprintf)
+</title>
+<meta http-equiv="Content-Language" content="en">
+<meta name="author"    content="Mark Martinec">
+<meta name="copyright" content="Copyright 2000 Mark Martinec, All Rights Reserved">
+<meta name="date"      content="2000-10-18">
+<meta name="keywords" lang="en"
+ content="snprintf,portable,vsnprintf,asnprintf,vasnprintf,asprintf,vasprintf
+          ISO/IEC 9899:1999,ISO C99,ISO C9x,POSIX">
+<style type="text/css">
+<!--
+  body { background: white; color: black }
+ -->
+</style>
+</head>
+<body>
+<h1><b>snprintf.c</b>
+<br> - a portable implementation of snprintf,
+<br><font size="+1">including
+vsnprintf.c, asnprintf, vasnprintf, asprintf, vasprintf</font>
+</h1>
+
+<p><b>snprintf</b> 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 <b>snprintf</b> 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.
+
+<h2>Author</h2>
+
+<p><a href="http://www.ijs.si/people/mark/">Mark Martinec</a>
+&lt;<a href="mailto:mark.martinec@ijs.si">mark.martinec@ijs.si</a>&gt;,
+April 1999, June 2000
+<br>Copyright &copy; 1999, Mark Martinec
+
+<h2>Terms and conditions ...</h2>
+
+<p>This program is free software; you can redistribute it
+and/or modify it under the terms of the
+<i><a href="./LICENSE.txt">Frontier Artistic License</a></i>
+which comes with this Kit.
+
+<h2>Features</h2>
+
+<ul>
+<li>careful adherence to specs regarding flags, field width and precision;
+<li>good performance for large string handling (large format, large argument
+or large paddings). Performance is similar to system's <b>sprintf</b>
+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);
+<li>return value semantics per ISO/IEC 9899:1999 ("ISO C99");
+<li>written in standard ISO/ANSI C - requires an ANSI C compiler.
+</ul>
+
+<h2>Supported conversion specifiers and data types</h2>
+
+<p>This <b>snprintf</b> only supports the following conversion specifiers:
+s, c, d, o, u, x, X, p  (and synonyms: i, D, U, O - see below)
+with flags: '-', '+', '&nbsp;', '0' and '#'.
+An asterisk is supported for field width as well as precision.
+
+<p>Length modifiers 'h' (<i>short int</i>), 'l' (<i>long int</i>),
+and 'll' (<i>long long int</i>) are supported.
+
+<p>NOTE:
+<blockquote>
+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
+<b>sprintf</b> also handles length modifier 'll'.
+<i>long long int</i> is a language extension which may not be portable.
+</blockquote>
+
+<p>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 <b>sprintf</b>, 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.
+
+<p>Length modifiers h, l and ll are ignored for c and s conversions
+(data types <i>wint_t</i> and <i>wchar_t</i> are not supported).
+
+<p>The following common synonyms for conversion characters are supported:
+<ul>
+<li>i is a synonym for d
+<li>D is a synonym for ld, explicit length modifiers are ignored
+<li>U is a synonym for lu, explicit length modifiers are ignored
+<li>O is a synonym for lo, explicit length modifiers are ignored
+</ul>
+The D, O and U conversion characters are nonstandard, they are supported
+for backward compatibility only, and should not be used for new code.
+
+<p>The following is specifically <b>not</b> supported:
+<ul>
+<li>flag ' (thousands' grouping character) is recognized but ignored
+<li>numeric conversion specifiers: f, e, E, g, G and synonym F,
+as well as the new a and A conversion specifiers
+<li>length modifier 'L' (<i>long double</i>)
+and 'q' (<i>quad</i> - use 'll' instead)
+<li>wide character/string conversions: lc, ls, and nonstandard
+synonyms C and S
+<li>writeback of converted string length: conversion character n
+<li>the n$ specification for direct reference to n-th argument
+<li>locales
+</ul>
+
+<p>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).
+
+<p>The return value is the number of characters which would be generated
+for the given input, <i>excluding</i> 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.
+
+<p>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.
+
+<p>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).
+
+<p>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.
+
+<h2>Availability</h2>
+
+<p><a href="http://www.ijs.si/software/snprintf/"
+>http://www.ijs.si/software/snprintf/</a>
+
+<ul>
+<li>
+<a href="./snprintf_1.3.tar.gz">snprintf_1.3.tar.gz</a> (1999-06-30),
+md5 sum: <a href="./snprintf_1.3.tar.gz.md5">snprintf_1.3.tar.gz.md5</a>
+
+<li>
+<a href="./snprintf_2.1.tar.gz">snprintf_2.1.tar.gz</a> (2000-07-14),
+md5 sum: <a href="./snprintf_2.1.tar.gz.md5">snprintf_2.1.tar.gz.md5</a>
+
+<li>
+<a href="./snprintf_2.2.tar.gz">snprintf_2.2.tar.gz</a> (2000-10-18),
+md5 sum: <a href="./snprintf_2.2.tar.gz.md5">snprintf_2.2.tar.gz.md5</a>
+</ul>
+
+
+<h2>Mailing list</h2>
+
+<p>There is a very low-traffic mailing list <i>snprintf-announce@ijs.si</i>
+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).
+
+<p>To subscribe to (or unsubscribe from) the mailing list
+please visit the list server's web page
+<a href="http://mailman.ijs.si/listinfo/snprintf-announce"
+>http://mailman.ijs.si/listinfo/snprintf-announce</a>
+
+<p>You can also subscribe to the list by mailing
+the command SUBSCRIBE either in the subject or in the message body
+to the address <a href="mailto:snprintf-announce-request@ijs.si"
+>snprintf-announce-request@ijs.si</a> . You will be asked for
+confirmation before subscription will be effective.
+
+<p>The list of members is only accessible to the list administrator,
+so there is no need for concern about automatic e-mail address gatherers.
+
+<p>Questions about the mailing list and concerns for the attention
+of a person should be sent to <a href="mailto:snprintf-announce-admin@ijs.si"
+>snprintf-announce-admin@ijs.si</a>
+
+<p>There is no <i>general</i> discussion list about portable snprintf
+at the moment. Please send comments and suggestion to the author.
+
+
+<h2>Revision history</h2>
+
+<p><b>Version 1.3 fixes a runaway loop problem from 1.2. Please upgrade.</b>
+
+<dl>
+<dt>1999-06-30	V1.3  Mark Martinec &lt;mark.martinec@ijs.si&gt;
+<dd><ul>
+<li>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 &lt;edwiny@autonomy.com&gt; for spotting the problem);
+<li>added macros PORTABLE_SNPRINTF_VERSION_(MAJOR|MINOR) to snprintf.h
+</ul>
+
+<dt>2000-02-14	V2.0 (never released) Mark Martinec &lt;mark.martinec@ijs.si&gt;
+<dd><ul>
+<li>relaxed license terms:
+  <a href="./LICENSE.txt">The Artistic License</a> now applies.
+  You may still apply the GNU GENERAL PUBLIC LICENSE
+  as was distributed with previous versions, if you prefer;
+<li>changed REVISION HISTORY dates to use
+  <a href="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">ISO 8601
+  date format</a>;
+<li>added vsnprintf (patch also independently proposed by
+  Caol&aacute;n McNamara 2000-05-04, and Keith M Willenson 2000-06-01)
+</ul>
+
+<dt>2000-06-27	V2.1  Mark Martinec &lt;mark.martinec@ijs.si&gt;
+<dd><ul>
+<li>removed POSIX check for str_m &lt; 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&aacute;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;
+<li>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;
+<li>autoconf contributed by Caol&aacute;n McNamara
+</ul>
+
+<dt>2000-10-06	V2.2  Mark Martinec &lt;mark.martinec@ijs.si&gt;
+<dd><ul>
+<li><b>BUG FIX</b>: the %c conversion used a temporary variable
+  that was no longer in scope when referenced,
+  possibly causing incorrect resulting character;
+<li>BUG FIX: make precision and minimal field width unsigned
+  to handle huge values (2^31 &lt;= n &lt; 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;
+<li>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;
+<li>some fiddling with zero padding and "0x" to make it
+  Linux compatible;
+<li>systematically use macros fast_memcpy and fast_memset
+  instead of case-by-case hand optimization; determine some
+  breakeven string lengths for different architectures;
+<li>terminology change: <i>format</i> -&gt; <i>conversion specifier</i>,
+  <i>C9x</i> -&gt; <i>ISO/IEC 9899:1999 ("ISO C99")</i>,
+  <i>alternative form</i> -&gt; <i>alternate form</i>,
+  <i>data type modifier</i> -&gt; <i>length modifier</i>;
+<li>several comments rephrased and new ones added;
+<li>make compiler not complain about 'credits' defined but
+  not used;
+</ul>
+</dl>
+
+<h2>Other implementations of snprintf</h2>
+
+<p>I am aware of some other (more or less) portable implementations
+of <b>snprintf</b>. 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
+<a href="http://www.ijs.si/people/mark/">me</a> know.
+
+<ul>
+<li>a very thorough implementation (src/util_snprintf.c)
+by the Apache Group distributed with the
+<a href="http://www.apache.org/">Apache web server
+- http://www.apache.org/</a> .
+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.
+
+<br>This is from the code:
+<blockquote>
+This software [...] was originally based
+on public domain software written at the
+<a href="http://www.ncsa.uiuc.edu/ncsa.html">National Center
+for Supercomputing Applications</a>, University of Illinois,
+Urbana-Champaign.<br>
+[...] This code is based on, and used with the permission of,
+the SIO stdio-replacement strx_* functions by Panos Tsirigotis
+&lt;<a href="mailto:panos@alumni.cs.colorado.edu">panos@alumni.cs.colorado.edu</a>&gt; for xinetd.
+</blockquote>
+
+<li><a href="http://www.qlue.com/downloads/c_utils_README.html">QCI
+Utilities</a> use a modified version of snprintf from the Apache group.
+
+<li>implementations as distributed with
+<a href="http://www.openbsd.org/cgi-bin/cvsweb/src/lib/libc/stdio/">OpenBSD</a>,
+<a href="http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libc/stdio/">FreeBSD</a>, and
+<a href="http://cvsweb.netbsd.org/cgi-bin/cvsweb.cgi/basesrc/lib/libc/stdio/">NetBSD</a>
+are all wrappers to vfprintf.c, which is derived from software
+contributed to Berkeley by Chris Torek.
+
+<li>implementation from Prof. Patrick Powell
+&lt;<a href="mailto:papowell@sdsu.edu">papowell@sdsu.edu</a>&gt;,
+Dept. Electrical and Computer Engineering, San Diego State University,
+San Diego, CA 92182-1309, published in
+<a href="http://www.geek-girl.com/bugtraq/1995_3/0217.html">Bugtraq
+archives for 3rd quarter (Jul-Aug) 1995</a>.
+No floating point conversions.
+
+<li>Brandon Long's
+&lt;<a href="mailto:blong@fiction.net">blong@fiction.net</a>&gt;
+<a href="http://www.fiction.net/~blong/programs/">modified version</a>
+of Prof. Patrick Powell's snprintf with contributions from others.
+With minimal floating point support.
+
+<li>implementation (src/snprintf.c) as distributed with
+<a href="http://www.sendmail.org/">sendmail - http://www.sendmail.org/</a>
+is a cleaned up Prof. Patrick Powell's version
+to compile properly and to support .precision and %lx.
+
+<li>implementation from <a href="http://www.csn.ul.ie/~caolan/"
+>Caol&aacute;n McNamara</a> available at
+<a href="http://www.csn.ul.ie/~caolan/publink/snprintf-1.1.tar.gz"
+>http://www.csn.ul.ie/~caolan/publink/snprintf-1.1.tar.gz</a>,
+handles floating point.
+
+<li>implementation used by
+<a href="ftp://ftp.soscorp.com/pub/sos/lib">newlog</a>
+(a replacement for syslog(3)) made available by
+the <a href="http://www.soscorp.com">SOS Corporation</a>.
+Enabling floating point support is a compile-time option.
+
+<li>implementation by Michael Richardson
+&lt;<a href="mailto:mcr@metis.milkyway.com">mcr@metis.milkyway.com</a>&gt;
+is available at
+<a href="http://sandelman.ottawa.on.ca/SSW/snp/snp.html"
+>http://sandelman.ottawa.on.ca/SSW/snp/snp.html</a>.
+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. 
+
+<li>implementation from Tomi Salo
+&lt;<a href="mailto:ttsalo@ssh.fi">ttsalo@ssh.fi</a>&gt;
+distributed with
+<a href="http://www.Europe.DataFellows.com/f-secure/ssh/">SSH 2.0
+Unix Server</a>. Not in public domain.
+Floating point conversions done by system's sprintf.
+
+<li>and for completeness: <a href="http://www.ijs.si/people/mark/">my</a>
+portable version described in this very document available at
+<a href="http://www.ijs.si/software/snprintf/"
+>http://www.ijs.si/software/snprintf/</a> .
+</ul>
+
+In retrospect, it appears that a lot of effort was wasted by many
+people for not being aware of what others are doing. Sigh.
+
+<p>Also of interest:
+<a href="http://www.opengroup.org/platform/resolutions/bwg98-006.html"
+>The Approved Base Working Group Resolution for XSH5,
+Ref: bwg98-006, Topic: snprintf</a>.
+
+<p><hr> 
+<i><a href="http://www.ijs.si/people/mark/">mm</a></i>
+<br>Last updated: 2000-10-18
+
+<p><a href="http://validator.w3.org/check/referer"
+><img src="/images/vh40.gif" alt="Valid HTML 4.0!"
+  border="0" width="88" height="31"></a>
+</body>
+</html>