libtu/snprintf_2.2/README.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3 <head>
   4 <link rev="made" href="mailto:mark.martinec@ijs.si">
   5 <title>
   6 snprintf.c - a portable implementation of snprintf
   7 (including vsnprintf.c, asnprintf, vasnprintf, asprintf, vasprintf)
   8 </title>
   9 <meta http-equiv="Content-Language" content="en">
  10 <meta name="author"    content="Mark Martinec">
  11 <meta name="copyright" content="Copyright 2000 Mark Martinec, All Rights Reserved">
  12 <meta name="date"      content="2000-10-18">
  13 <meta name="keywords" lang="en"
  14  content="snprintf,portable,vsnprintf,asnprintf,vasnprintf,asprintf,vasprintf
  15           ISO/IEC 9899:1999,ISO C99,ISO C9x,POSIX">
  16 <style type="text/css">
  17 <!--
  18   body { background: white; color: black }
  19  -->
  20 </style>
  21 </head>
  22 <body>
  23 <h1><b>snprintf.c</b>
  24 <br> - a portable implementation of snprintf,
  25 <br><font size="+1">including
  26 vsnprintf.c, asnprintf, vasnprintf, asprintf, vasprintf</font>
  27 </h1>
  28
  29 <p><b>snprintf</b> is a routine to convert numeric and string arguments
  30 to formatted strings. It is similar to sprintf(3) provided in a
  31 system's C library, yet it requires an additional argument - the buffer
  32 size - and it guarantees never to store anything beyond the given buffer,
  33 regardless of the format or arguments to be formatted. Some newer
  34 operating systems do provide <b>snprintf</b> in their C library,
  35 but many do not or do provide an inadequate (slow or idiosyncratic)
  36 version, which calls for a portable implementation of this routine.
  37
  38 <h2>Author</h2>
  39
  40 <p><a href="http://www.ijs.si/people/mark/">Mark Martinec</a>
  41 &lt;<a href="mailto:mark.martinec@ijs.si">mark.martinec@ijs.si</a>&gt;,
  42 April 1999, June 2000
  43 <br>Copyright &copy; 1999, Mark Martinec
  44
  45 <h2>Terms and conditions ...</h2>
  46
  47 <p>This program is free software; you can redistribute it
  48 and/or modify it under the terms of the
  49 <i><a href="./LICENSE.txt">Frontier Artistic License</a></i>
  50 which comes with this Kit.
  51
  52 <h2>Features</h2>
  53
  54 <ul>
  55 <li>careful adherence to specs regarding flags, field width and precision;
  56 <li>good performance for large string handling (large format, large argument
  57 or large paddings). Performance is similar to system's <b>sprintf</b>
  58 and in several cases significantly better (make sure you compile with
  59 optimizations turned on, tell the compiler the code is strict ANSI
  60 if necessary to give it more freedom for optimizations);
  61 <li>return value semantics per ISO/IEC 9899:1999 ("ISO C99");
  62 <li>written in standard ISO/ANSI C - requires an ANSI C compiler.
  63 </ul>
  64
  65 <h2>Supported conversion specifiers and data types</h2>
  66
  67 <p>This <b>snprintf</b> only supports the following conversion specifiers:
  68 s, c, d, o, u, x, X, p  (and synonyms: i, D, U, O - see below)
  69 with flags: '-', '+', '&nbsp;', '0' and '#'.
  70 An asterisk is supported for field width as well as precision.
  71
  72 <p>Length modifiers 'h' (<i>short int</i>), 'l' (<i>long int</i>),
  73 and 'll' (<i>long long int</i>) are supported.
  74
  75 <p>NOTE:
  76 <blockquote>
  77 If macro SNPRINTF_LONGLONG_SUPPORT is not defined (default)
  78 the length modifier 'll' is recognized but treated the same as 'l',
  79 which may cause argument value truncation!
  80 Defining SNPRINTF_LONGLONG_SUPPORT requires that your system's
  81 <b>sprintf</b> also handles length modifier 'll'.
  82 <i>long long int</i> is a language extension which may not be portable.
  83 </blockquote>
  84
  85 <p>Conversion of numeric data (conversion specifiers d, o, u, x, X, p)
  86 with length modifiers (none or h, l, ll) is left to the system
  87 routine <b>sprintf</b>, but all handling of flags, field width and precision
  88 as well as c and s conversions is done very carefully by this portable routine.
  89 If a string precision (truncation) is specified (e.g. %.8s) it is
  90 guaranteed the string beyond the specified precision will not be referenced.
  91
  92 <p>Length modifiers h, l and ll are ignored for c and s conversions
  93 (data types <i>wint_t</i> and <i>wchar_t</i> are not supported).
  94
  95 <p>The following common synonyms for conversion characters are supported:
  96 <ul>
  97 <li>i is a synonym for d
  98 <li>D is a synonym for ld, explicit length modifiers are ignored
  99 <li>U is a synonym for lu, explicit length modifiers are ignored
 100 <li>O is a synonym for lo, explicit length modifiers are ignored
 101 </ul>
 102 The D, O and U conversion characters are nonstandard, they are supported
 103 for backward compatibility only, and should not be used for new code.
 104
 105 <p>The following is specifically <b>not</b> supported:
 106 <ul>
 107 <li>flag ' (thousands' grouping character) is recognized but ignored
 108 <li>numeric conversion specifiers: f, e, E, g, G and synonym F,
 109 as well as the new a and A conversion specifiers
 110 <li>length modifier 'L' (<i>long double</i>)
 111 and 'q' (<i>quad</i> - use 'll' instead)
 112 <li>wide character/string conversions: lc, ls, and nonstandard
 113 synonyms C and S
 114 <li>writeback of converted string length: conversion character n
 115 <li>the n$ specification for direct reference to n-th argument
 116 <li>locales
 117 </ul>
 118
 119 <p>It is permitted for str_m to be zero, and it is permitted to specify NULL
 120 pointer for resulting string argument if str_m is zero (as per ISO C99).
 121
 122 <p>The return value is the number of characters which would be generated
 123 for the given input, <i>excluding</i> the trailing null. If this value
 124 is greater or equal to str_m, not all characters from the result
 125 have been stored in str, output bytes beyond the (str_m-1) -th character
 126 are discarded. If str_m is greater than zero it is guaranteed
 127 the resulting string will be null-terminated.
 128
 129 <p>NOTE that this matches the ISO C99, OpenBSD, and GNU C library 2.1,
 130 but is different from some older and vendor implementations,
 131 and is also different from XPG, XSH5, SUSv2 specifications.
 132 For historical discussion on changes in the semantics and standards
 133 of snprintf see printf(3) man page in the Linux programmers manual.
 134
 135 <p>Routines asprintf and vasprintf return a pointer (in the ptr argument)
 136 to a buffer sufficiently large to hold the resulting string. This pointer
 137 should be passed to free(3) to release the allocated storage when it is
 138 no longer needed. If sufficient space cannot be allocated, these functions
 139 will return -1 and set ptr to be a NULL pointer. These two routines are a
 140 GNU C library extensions (glibc).
 141
 142 <p>Routines asnprintf and vasnprintf are similar to asprintf and vasprintf,
 143 yet, like snprintf and vsnprintf counterparts, will write at most str_m-1
 144 characters into the allocated output string, the last character in the
 145 allocated buffer then gets the terminating null. If the formatted string
 146 length (the return value) is greater than or equal to the str_m argument,
 147 the resulting string was truncated and some of the formatted characters
 148 were discarded. These routines present a handy way to limit the amount
 149 of allocated memory to some sane value.
 150
 151 <h2>Availability</h2>
 152
 153 <p><a href="http://www.ijs.si/software/snprintf/"
 154 >http://www.ijs.si/software/snprintf/</a>
 155
 156 <ul>
 157 <li>
 158 <a href="./snprintf_1.3.tar.gz">snprintf_1.3.tar.gz</a> (1999-06-30),
 159 md5 sum: <a href="./snprintf_1.3.tar.gz.md5">snprintf_1.3.tar.gz.md5</a>
 160
 161 <li>
 162 <a href="./snprintf_2.1.tar.gz">snprintf_2.1.tar.gz</a> (2000-07-14),
 163 md5 sum: <a href="./snprintf_2.1.tar.gz.md5">snprintf_2.1.tar.gz.md5</a>
 164
 165 <li>
 166 <a href="./snprintf_2.2.tar.gz">snprintf_2.2.tar.gz</a> (2000-10-18),
 167 md5 sum: <a href="./snprintf_2.2.tar.gz.md5">snprintf_2.2.tar.gz.md5</a>
 168 </ul>
 169
 170
 171 <h2>Mailing list</h2>
 172
 173 <p>There is a very low-traffic mailing list <i>snprintf-announce@ijs.si</i>
 174 where announcements about new versions will be posted
 175 as well as warnings about threatening bugs if discovered.
 176 The posting is restricted to snprintf developer(s).
 177
 178 <p>To subscribe to (or unsubscribe from) the mailing list
 179 please visit the list server's web page
 180 <a href="http://mailman.ijs.si/listinfo/snprintf-announce"
 181 >http://mailman.ijs.si/listinfo/snprintf-announce</a>
 182
 183 <p>You can also subscribe to the list by mailing
 184 the command SUBSCRIBE either in the subject or in the message body
 185 to the address <a href="mailto:snprintf-announce-request@ijs.si"
 186 >snprintf-announce-request@ijs.si</a> . You will be asked for
 187 confirmation before subscription will be effective.
 188
 189 <p>The list of members is only accessible to the list administrator,
 190 so there is no need for concern about automatic e-mail address gatherers.
 191
 192 <p>Questions about the mailing list and concerns for the attention
 193 of a person should be sent to <a href="mailto:snprintf-announce-admin@ijs.si"
 194 >snprintf-announce-admin@ijs.si</a>
 195
 196 <p>There is no <i>general</i> discussion list about portable snprintf
 197 at the moment. Please send comments and suggestion to the author.
 198
 199
 200 <h2>Revision history</h2>
 201
 202 <p><b>Version 1.3 fixes a runaway loop problem from 1.2. Please upgrade.</b>
 203
 204 <dl>
 205 <dt>1999-06-30  V1.3  Mark Martinec &lt;mark.martinec@ijs.si&gt;
 206 <dd><ul>
 207 <li>fixed runaway loop (eventually crashing when str_l wraps
 208   beyond 2^31) while copying format string without
 209   conversion specifiers to a buffer that is too short
 210   (thanks to Edwin Young &lt;edwiny@autonomy.com&gt; for spotting the problem);
 211 <li>added macros PORTABLE_SNPRINTF_VERSION_(MAJOR|MINOR) to snprintf.h
 212 </ul>
 213
 214 <dt>2000-02-14  V2.0 (never released) Mark Martinec &lt;mark.martinec@ijs.si&gt;
 215 <dd><ul>
 216 <li>relaxed license terms:
 217   <a href="./LICENSE.txt">The Artistic License</a> now applies.
 218   You may still apply the GNU GENERAL PUBLIC LICENSE
 219   as was distributed with previous versions, if you prefer;
 220 <li>changed REVISION HISTORY dates to use
 221   <a href="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">ISO 8601
 222   date format</a>;
 223 <li>added vsnprintf (patch also independently proposed by
 224   Caol&aacute;n McNamara 2000-05-04, and Keith M Willenson 2000-06-01)
 225 </ul>
 226
 227 <dt>2000-06-27  V2.1  Mark Martinec &lt;mark.martinec@ijs.si&gt;
 228 <dd><ul>
 229 <li>removed POSIX check for str_m &lt; 1; value 0 for str_m is
 230   allowed by ISO C99 (and GNU C library 2.1) (pointed out
 231   on 2000-05-04 by Caol&aacute;n McNamara, caolan@ csn dot ul dot ie).
 232   Besides relaxed license this change in standards adherence
 233   is the main reason to bump up the major version number;
 234 <li>added nonstandard routines asnprintf, vasnprintf, asprintf,
 235   vasprintf that dynamically allocate storage for the
 236   resulting string; these routines are not compiled by default,
 237   see comments where NEED_V?ASN?PRINTF macros are defined;
 238 <li>autoconf contributed by Caol&aacute;n McNamara
 239 </ul>
 240
 241 <dt>2000-10-06  V2.2  Mark Martinec &lt;mark.martinec@ijs.si&gt;
 242 <dd><ul>
 243 <li><b>BUG FIX</b>: the %c conversion used a temporary variable
 244   that was no longer in scope when referenced,
 245   possibly causing incorrect resulting character;
 246 <li>BUG FIX: make precision and minimal field width unsigned
 247   to handle huge values (2^31 &lt;= n &lt; 2^32) correctly;
 248   also be more careful in the use of signed/unsigned/size_t
 249   internal variables -- probably more careful than many
 250   vendor implementations, but there may still be a case
 251   where huge values of str_m, precision or minimal field
 252   could cause incorrect behaviour;
 253 <li>use separate variables for signed/unsigned arguments,
 254   and for short/int, long, and long long argument lengths
 255   to avoid possible incompatibilities on certain
 256   computer architectures. Also use separate variable
 257   arg_sign to hold sign of a numeric argument,
 258   to make code more transparent;
 259 <li>some fiddling with zero padding and "0x" to make it
 260   Linux compatible;
 261 <li>systematically use macros fast_memcpy and fast_memset
 262   instead of case-by-case hand optimization; determine some
 263   breakeven string lengths for different architectures;
 264 <li>terminology change: <i>format</i> -&gt; <i>conversion specifier</i>,
 265   <i>C9x</i> -&gt; <i>ISO/IEC 9899:1999 ("ISO C99")</i>,
 266   <i>alternative form</i> -&gt; <i>alternate form</i>,
 267   <i>data type modifier</i> -&gt; <i>length modifier</i>;
 268 <li>several comments rephrased and new ones added;
 269 <li>make compiler not complain about 'credits' defined but
 270   not used;
 271 </ul>
 272 </dl>
 273
 274 <h2>Other implementations of snprintf</h2>
 275
 276 <p>I am aware of some other (more or less) portable implementations
 277 of <b>snprintf</b>. I do not claim they are free software - please refer
 278 to their respective copyright and licensing terms.
 279 If you know of other versions please let
 280 <a href="http://www.ijs.si/people/mark/">me</a> know.
 281
 282 <ul>
 283 <li>a very thorough implementation (src/util_snprintf.c)
 284 by the Apache Group distributed with the
 285 <a href="http://www.apache.org/">Apache web server
 286 - http://www.apache.org/</a> .
 287 Does its own floating point conversions using routines
 288 ecvt(3), fcvt(3) and gcvt(3) from the standard C library
 289 or from the GNU libc.
 290
 291 <br>This is from the code:
 292 <blockquote>
 293 This software [...] was originally based
 294 on public domain software written at the
 295 <a href="http://www.ncsa.uiuc.edu/ncsa.html">National Center
 296 for Supercomputing Applications</a>, University of Illinois,
 297 Urbana-Champaign.<br>
 298 [...] This code is based on, and used with the permission of,
 299 the SIO stdio-replacement strx_* functions by Panos Tsirigotis
 300 &lt;<a href="mailto:panos@alumni.cs.colorado.edu">panos@alumni.cs.colorado.edu</a>&gt; for xinetd.
 301 </blockquote>
 302
 303 <li><a href="http://www.qlue.com/downloads/c_utils_README.html">QCI
 304 Utilities</a> use a modified version of snprintf from the Apache group.
 305
 306 <li>implementations as distributed with
 307 <a href="http://www.openbsd.org/cgi-bin/cvsweb/src/lib/libc/stdio/">OpenBSD</a>,
 308 <a href="http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libc/stdio/">FreeBSD</a>, and
 309 <a href="http://cvsweb.netbsd.org/cgi-bin/cvsweb.cgi/basesrc/lib/libc/stdio/">NetBSD</a>
 310 are all wrappers to vfprintf.c, which is derived from software
 311 contributed to Berkeley by Chris Torek.
 312
 313 <li>implementation from Prof. Patrick Powell
 314 &lt;<a href="mailto:papowell@sdsu.edu">papowell@sdsu.edu</a>&gt;,
 315 Dept. Electrical and Computer Engineering, San Diego State University,
 316 San Diego, CA 92182-1309, published in
 317 <a href="http://www.geek-girl.com/bugtraq/1995_3/0217.html">Bugtraq
 318 archives for 3rd quarter (Jul-Aug) 1995</a>.
 319 No floating point conversions.
 320
 321 <li>Brandon Long's
 322 &lt;<a href="mailto:blong@fiction.net">blong@fiction.net</a>&gt;
 323 <a href="http://www.fiction.net/~blong/programs/">modified version</a>
 324 of Prof. Patrick Powell's snprintf with contributions from others.
 325 With minimal floating point support.
 326
 327 <li>implementation (src/snprintf.c) as distributed with
 328 <a href="http://www.sendmail.org/">sendmail - http://www.sendmail.org/</a>
 329 is a cleaned up Prof. Patrick Powell's version
 330 to compile properly and to support .precision and %lx.
 331
 332 <li>implementation from <a href="http://www.csn.ul.ie/~caolan/"
 333 >Caol&aacute;n McNamara</a> available at
 334 <a href="http://www.csn.ul.ie/~caolan/publink/snprintf-1.1.tar.gz"
 335 >http://www.csn.ul.ie/~caolan/publink/snprintf-1.1.tar.gz</a>,
 336 handles floating point.
 337
 338 <li>implementation used by
 339 <a href="ftp://ftp.soscorp.com/pub/sos/lib">newlog</a>
 340 (a replacement for syslog(3)) made available by
 341 the <a href="http://www.soscorp.com">SOS Corporation</a>.
 342 Enabling floating point support is a compile-time option.
 343
 344 <li>implementation by Michael Richardson
 345 &lt;<a href="mailto:mcr@metis.milkyway.com">mcr@metis.milkyway.com</a>&gt;
 346 is available at
 347 <a href="http://sandelman.ottawa.on.ca/SSW/snp/snp.html"
 348 >http://sandelman.ottawa.on.ca/SSW/snp/snp.html</a>.
 349 It is based on BSD44-lite's vfprintf() call, modified to function
 350 on SunOS. Needs internal routines from the 4.4 strtod (included),
 351 requires GCC to compile the long long (aka quad_t) portions.
 352
 353 <li>implementation from Tomi Salo
 354 &lt;<a href="mailto:ttsalo@ssh.fi">ttsalo@ssh.fi</a>&gt;
 355 distributed with
 356 <a href="http://www.Europe.DataFellows.com/f-secure/ssh/">SSH 2.0
 357 Unix Server</a>. Not in public domain.
 358 Floating point conversions done by system's sprintf.
 359
 360 <li>and for completeness: <a href="http://www.ijs.si/people/mark/">my</a>
 361 portable version described in this very document available at
 362 <a href="http://www.ijs.si/software/snprintf/"
 363 >http://www.ijs.si/software/snprintf/</a> .
 364 </ul>
 365
 366 In retrospect, it appears that a lot of effort was wasted by many
 367 people for not being aware of what others are doing. Sigh.
 368
 369 <p>Also of interest:
 370 <a href="http://www.opengroup.org/platform/resolutions/bwg98-006.html"
 371 >The Approved Base Working Group Resolution for XSH5,
 372 Ref: bwg98-006, Topic: snprintf</a>.
 373
 374 <p><hr>
 375 <i><a href="http://www.ijs.si/people/mark/">mm</a></i>
 376 <br>Last updated: 2000-10-18
 377
 378 <p><a href="http://validator.w3.org/check/referer"
 379 ><img src="/images/vh40.gif" alt="Valid HTML 4.0!"
 380   border="0" width="88" height="31"></a>
 381 </body>
 382 </html>