Tribblix: manual page: sprintf.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 space, or '\0') give the name of the bit. As the
bit number 32 encoded as a control character is the same as a
space character, the names of the bits cannot contain a space.
The strings corresponding to the bits set in the integer
argument are printed after the numerical value, enclosed in
angle brackets and separated by commata.

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 encountered. 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).