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:

Zero or more flags (in any order), which modify the meaning of the conversion specification.
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.
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.
An optional length modifier that specified the size of the argument.
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).