illumos: manual page: vsprintf.9f

SPRINTF(9F) Kernel Functions for Drivers SPRINTF(9F)

NAME

sprintf, snprintf, vsprintf, vsnprintf - format characters in memory

SYNOPSIS

#include <sys/cmn_err.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

char *
sprintf(char *s, const char *format, ...);

size_t
snprintf(char *s, size_t n, const char *format, ...);

#include <sys/varargs.h>

char *
vsprintf(char *s, const char *format, va_list ap);

size_t
vsnprintf(char *s, size_t n, const char *format, va_list ap);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

s Pointer to a character string.

n Size of the buffer pointed to by s.

format Pointer to a character string.

ap Pointer to a variable argument list.

DESCRIPTION

The sprintf() function places output, followed by the null byte (\0), in
consecutive bytes starting at s; it is the user's responsibility to ensure
that enough storage is available.

The snprintf() function is identical to sprintf() with the addition of the
argument n, which specifies the size of the buffer referred to by s. If n
is 0, nothing is written and s can be a null pointer. Otherwise, output
bytes beyond the n-1st are discarded instead of being written to the array
and a null byte is written at the end of the bytes actually written into
the array.

The vsprintf() and vsnprintf() functions are the same as sprintf() and
snprintf(), respectively, except that instead of being called with a
variable number of arguments, they are called with an argument list, ap,
used by the conversion specifications in format. ap is a variable argument
list and must be initialized by calling va_start(9F). va_end(9F) is used
to clean up and must be called after each traversal of the list. Multiple
traversals of the argument list, each bracketed by va_start(9F) and
va_end(9F), are possible.

Each of these functions converts, formats, and prints its arguments under
control of the format. The format is composed of zero or more directives:
ordinary characters, which are simply copied to the output stream and
conversion specifications, each of which results in the fetching of zero or
more arguments. The results are undefined if there are insufficient
arguments for the format. If the format is exhausted while arguments
remain, the excess arguments are evaluated but are otherwise ignored.

Conversion Specifications

Each conversion specification is introduced by the "%" character after
which the following appear in sequence:

+o Zero or more flags (in any order), which modify the meaning of the
conversion specification.

+o An optional minimum field width. If the converted value has fewer
bytes than the field width, it will be padded with spaces by default on
the left; it will be padded on the right, if the left-adjustment flag
("-"), described below, is given to the field width. The field width
takes the form of an asterisk ("*"), described below, or a decimal
integer.

+o An optional precision that gives the minimum number of digits to appear
for the d, D, o, O, x, X, or u conversions (the field is padded with
leading zeros); or the maximum number of bytes to be printed from a
string in s conversion. The precision takes the form of a period (".")
followed either by an asterisk ("*"), described below, or an optional
decimal digit string, where a null digit string is treated as 0. If a
precision appears with any other conversion specifier, the behavior is
undefined.

+o An optional length modifier that specified the size of the argument.

+o A conversion specifier that indicates the type of conversion to be
applied.

A field width, or precision, or both can be indicated by an asterisk ("*").
In this case, an argument of type int supplies the field width or
precision. Arguments specifying field width, or precision, or both must
appear in that order before the argument, if any, to be converted. A
negative field width is taken as a "-" flag followed by a positive field
width. A negative precision is taken as if the precision were omitted.

Flag Characters

The flag characters and their meanings are:

- The result of the conversion will be left-justified within the
field. The conversion will be right-justified if this flag is not
specified.

0 For d, D, o, O, x, X, or u conversions, leading zeros (following
any indication of sign or base) are used to pad to the field width;
no space padding is performed. If the 0 and - flags both appear,
the 0 flag will be ignored. If a precision is specified, the 0
flag will be ignored. For other conversions, the behavior is
undefined.

Length Modifiers

The length modifiers and their meanings are:

h Specifies that a following d, D, o, O, x, X, or u conversion
specifier applies to a short or unsigned short argument (the
argument will have been promoted according to the integer
promotions, but its value will be converted to short or unsigned
short before printing).

hh Specifies that a following d, D, o, O, x, X, or u conversion
specifier applies to a signed char or unsigned char argument (the
argument will have been promoted according to the integer
promotions, but its value will be converted to signed char or
unsigned char before printing).

l Specifies that a following d, D, o, O, x, X, or u conversion
specifier applies to a long or unsigned long argument.

ll Specifies that a following d, D, o, O, x, X, or u conversion
specifier applies to a long long or unsigned long long argument.

Conversion Specifiers

Each conversion specifier results in fetching zero or more arguments. The
results are undefined if there are insufficient arguments for the format.
If the format is exhausted while arguments remain, the excess arguments are
ignored.

The conversion specifiers and their meanings are:

d, D, o, O, x, X, u
The integer argument is converted to signed decimal (d, D),
unsigned octal (o, O), unsigned hexadecimal (x, X), or unsigned
decimal (u), respectively. The letters "abcdef" are used for x and
letters "ABCDEF" for X conversions.

c The character value of the argument is printed.

b The %b conversion specification allows bit values to be printed
meaningfully. Each %b takes an integer value and a format string
from the argument list. The first character of the format string
should be the output base encoded as a control character. This
base is used to print the integer argument. The remaining groups
of characters in the format string consist of a bit number (between
1 and 32, also encoded as a control character) and the next
characters (up to the next control character or '\0') give the name
of the bit field. The string corresponding to the bit fields set
in the integer argument is printed after the numerical value.

p The argument is taken to be a pointer; the value of the pointer is
printed in unsigned hexadecimal. The print format is equivalent to
%lx. To avoid lint warnings, cast pointers to type void * when
using the %p format specifier.

s The argument is taken to be a string (character pointer), and
characters from the string are printed until a null character is
ecountered. If the character pointer is NULL, the string "<null
string>" is used in its place.

% Copy a %; no argument is converted.

CONTEXT

These functions can be called from user, kernel, interrupt, or high-level
interrupt context.

RETURN VALUES

sprintf() and vsprintf() return s.

snprintf() and vsnprintf() return the number of bytes that would have been
written to s if n had been sufficiently large (excluding the terminating
null byte).