PLP_SNPRINTF(3)

NAME
plp_snprintf, plp_vsnprintf - formatted output conversion

SYNOPSIS
#include <stdarg.h>
void plp_snprintf(char *str, int size, const char *format, ...);
void plp_vsnprintf(char *str, int size, const char *format, va_list ap);
extern int visible_control;

HISTORY, TERMS AND CONDITIONS

This version of plp_snprintf was developed originally for printing on a motley collection of specialized hardware that had NO IO library. Due to contractual restrictions, a clean room implementation of the printf() code had to be developed.

The implementation of plp_snprintf tends to be overly paranoid, as these platforms had NO memory protection, and very small address spaces. This made it possible to try to print very long strings, i.e. - all of memory, very easily. To guard against this, all printing was done via a fixed size buffer, generous enough to hold reasonable strings, but small enough to protect against overruns, etc.

Strangely enough, this proves to be of immense importance when SPRINTFing to a buffer on a stack. The rest, of course, is well known, as buffer overruns in the stack are a common way to do horrible things to operating systems, security, etc etc.

This version of the plp_snprintf documentation is based on the snprintf() manual page from BSDI Inc, the POSIX printf() documentation, and the 4.4 BSD Release printf() manual page.

The plp_snprintf() source code is freely distributible under the following license terms:

You may use, copy, distribute, or otherwise incorporate this software and documentation into any product or other item, provided that the copyright in the documentation and source code as well as the source code generated constant strings in the object, executable or other code remain in place and are present in executable modules or objects.

You may modify this code as appropriate to your usage; however the modified version must be identified by changing the various source and object code identification strings as is appropriately noted in the source code.

DESCRIPTION

The plp_snprintf() and plp_vsnprintf() procedures write to a string under the control of a format string that specifies how subsequent arguments output.

The plp_snprintf() and plp_vsnprintf() will write at most size-1 characters floowed by a ` '. If str is 0 (NULL) or size is 0, then no characters are written.

The visible_control variable (default value 1) is used when printing character or string values. If the character C to be printed is a control character or and not a space as determined by the ctype.h library iscntrl() and isspace() functions, then it will be printed as the form ^X, where X = (C & 0x1f) | '@' in C language notation.

The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %. The arguments must correspond properly (after type promotion) with the conversion specifier. After the %, the following appear in sequence:

o   Zero or more of the following flags:

-   A zero `0' character specifying zero padding. For all conversions except n, the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion (d, i, o, u, i, x, and X), the `0' flag is ignored.

-   A negative field width flag `-' indicates the converted value is to be left adjusted on the field boundary.

-   A `+' character specifying that a sign always be placed before a number produced by a signed conversion.

o   An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width. Note that e, f, and g formats are restricted to a maximum of 64 characters.

o   An optional precision, in the form of a period `.' followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point. For e, f, and g conversions, the meaning depends on the local system sprintf() support.

o   The optional character l (ell) specifying that a following d, i, o, u, x, or X conversion applies to a long int or unsigned long int argument.

o   The optional character q, specifying that a following d, i, o, u, x, or X conversion corresponds to a quad or long long.

o   A character that specifies the type of conversion to be applied.

A field width or precision, or both, may be indicated by an asterisk `*' instead of a digit string. In this case, an int argument supplies the field width or precision. A negative or zero field width is ignored.

The conversion specifiers and their meanings are:

diouxX
    The int (or appropriate variant) argument is converted to signed decimal (d and i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and X) notation. The letters abcdef are used for x conversions; the letters ABCDEF are used for X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with blanks unless zero padding has been requested.

efg The double argument is rounded and converted in the style of the underlying systems sprintf() support. Lengths and other critical values have been check, and the maximum length of converted value is 64 bytes.

c   The int argument is converted to an unsigned char, and the resulting character is written, as modified by the visible_control variable value.

s   The ``char *'' argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified are written. Characters are written to the string as modified by the visible_control variable value.

%   A `%' is written. No argument is converted. The complete conversion specification is `%%'.

In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

SH BUGS The typedef names quad_t and u_quad_t are ugly, ugly, ugly. Your system may use different quad type names.

COPYRIGHT

The source code and documentation is Copyright 1988-1999 by Patrick Powell <papowell@astart.com>.