NAME udi_snprintf(3udi)

udi_snprintf(3udi)
Format printable string

SYNOPSIS
#include <udi.h>
udi_size_t udi_snprintf (

	char *s,

	udi_size_t max_bytes,

	const char *format,

	... );
 
ARGUMENTS s is a pointer to the target buffer for the formatted output, which is a null-terminated printable string.

max_bytes is the maximum number of bytes to be written to s, including the null terminator.

format is the format string, which controls the formatting of the output string.

... are the remaining arguments, which provide the values used for the formatting codes.

DESCRIPTION The udi_snprintf routine is used to generate a formatted string from a set of input arguments and values. The operation of this utility is comparable to the ISO snprintf function with the exceptions noted and supporting only the format codes and modifiers documented below.

All format specifications are of the form %mf where m is an optional modifier of the form [[ 0, - ] nn] and f is one or more format codes.

The following format modifiers are defined

Format Modifier Output Control

nn minimum field width as an unsigned decimal number. (e.g. %4x prints a hexadecimal number taking up 4 or more digits). By default, the output is preceded by spaces to meet the minimum field width unless changed by other format modifiers. This modifier applies to the %c format code as well; in this case the single character is preceded by the necessary number of spaces (or otherwise adjusted according to any other modifiers present).

0 leading characters needed for minimum field width compliance will be padded with zeros instead of spaces when used with numeric formats (e.g. %04x for a value of 12 will output "000c").

- left-justify within field width (e.g. %-4x for a value of 12 will output `c' followed by 3 spaces. It is not valid to use the `-' and `0' modifiers together.

:

The udi_snprintf function supports the following format codes chosen to provide fast execution and common utility:

Format Code Output generated

%x, %X unsigned hexadecimal udi_ubit32_t. The alphanumeric characters output as a result of this format will be shown in either lower or upper case as specified by the case of the format code.

%d, %u signed and unsigned decimal udi_sbit32_t and udi_ubit32_t

%hx, %hX unsigned hexadecimal udi_ubit16_t

%hd, %hu signed and unsigned decimal udi_sbit16_t and udi_ubit16_t

%bx, %bX unsigned hexadecimal udi_ubit8_t

%bd, %bu signed and unsigned decimal udi_sbit8_t and udi_ubit8_t

%p, %P hexadecimal pointer value, size as appropriate for the host machine

%a, %A 64-bit bus address value (DMA address type udi_busaddr64_t; see the description of the udi_scgth_t structure in the UDI Physical I/O Specification) printed as a hexadecimal value in lower or upper case, respectively. Not supported in environments that do not support the Physical I/O Services.

%c single printable character

%s null-terminated string

%<istring> Value bitmask formatter. This format code outputs a formatted string interpretation of a bitmask. The argument for this format code is a udi_ubit32_t value; the bitmask interpretation of that value is based on the istring information as described here, where bit number 0 is the least-significant bit in the value:
istring := [,] bitspec {, bitspec} [,]
bitspec := [~] bitnum = <string> |                         bitnum - bitnum = <string> [fieldspec ...] bitnum := <decimal number 0-31> fieldspec := : <unsigned decimal number> = <string>
The output is delimited by `<` and `>' characters. If bitspec is specified as a single bitnum (the first form) then the associated string is printed if the specified bit is set (or printed if the bit is not set if ~ is specified); otherwise nothing is printed.
If bitspec is specified as a range of bits (the second form) then the associated string will be output followed by `=' and then the hexadecimal value of the specified range of bits; if the value also matches any of the optional fieldspec values, the fieldspec string is printed instead of the value.

Once formatting has reached the specified max_bytes output length for s, this function returns without processing the remainder of the format or other arguments. A null terminator character will always be placed at the end of the generated string in s.

RETURN VALUES The number of bytes in s, not including the null terminator.

EXAMPLES The following code segment:

udi_snprintf(s, 256, "%s %-2c %d: 0x%08x " "%<15=Active,14=DMA Ready,13=XMIT,"
"~13=RCV,0-2=Mode:0=HDX:1=FDX"
":2=Sync HDX:3=Sync FDX:4=Coded,"
"3-6=TX Threshold,7-10=RX Threshold>",
"Register", `#', 0, 0xc093, 0xc093);

would result in the following contents of string s (without line breaks):

"Register #  0: 0x0000c093 <Active, DMA Ready, RCV, Mode=Sync FDX, TX Threshold=2, RX Threshold=1>"

The following code segment will produce different output based on the architecture on which it is run:

udi_snprintf(s, 256, "Stored at 0x%p", &var);

will produce one of the following output strings, depending on pointer size:

16-bit (e.g. 8086):    "Stored at 0x801c"
32-bit (e.g. PA-RISC): "Stored at 0x505d806f"
64-bit (e.g. Alpha):       "Stored at 0x300040cc6069f0c0"

Format Modifier	Output Control
nn	minimum field width as an unsigned decimal number. (e.g. %4x prints a hexadecimal number taking up 4 or more digits). By default, the output is preceded by spaces to meet the minimum field width unless changed by other format modifiers. This modifier applies to the %c format code as well; in this case the single character is preceded by the necessary number of spaces (or otherwise adjusted according to any other modifiers present).
0	leading characters needed for minimum field width compliance will be padded with zeros instead of spaces when used with numeric formats (e.g. %04x for a value of 12 will output "000c").
-	left-justify within field width (e.g. %-4x for a value of 12 will output `c' followed by 3 spaces. It is not valid to use the `-' and `0' modifiers together.

Format Code	Output generated
%x, %X	unsigned hexadecimal udi_ubit32_t. The alphanumeric characters output as a result of this format will be shown in either lower or upper case as specified by the case of the format code.
%d, %u	signed and unsigned decimal udi_sbit32_t and udi_ubit32_t
%hx, %hX	unsigned hexadecimal udi_ubit16_t
%hd, %hu	signed and unsigned decimal udi_sbit16_t and udi_ubit16_t
%bx, %bX	unsigned hexadecimal udi_ubit8_t
%bd, %bu	signed and unsigned decimal udi_sbit8_t and udi_ubit8_t
%p, %P	hexadecimal pointer value, size as appropriate for the host machine
%a, %A	64-bit bus address value (DMA address type udi_busaddr64_t; see the description of the udi_scgth_t structure in the UDI Physical I/O Specification) printed as a hexadecimal value in lower or upper case, respectively. Not supported in environments that do not support the Physical I/O Services.
%c	single printable character
%s	null-terminated string
%<istring>	Value bitmask formatter. This format code outputs a formatted string interpretation of a bitmask. The argument for this format code is a udi_ubit32_t value; the bitmask interpretation of that value is based on the istring information as described here, where bit number 0 is the least-significant bit in the value: istring := [,] bitspec {, bitspec} [,] bitspec := [~] bitnum = <string> \| bitnum - bitnum = <string> [fieldspec ...] bitnum := <decimal number 0-31> fieldspec := : <unsigned decimal number> = <string> The output is delimited by `<` and `>' characters. If bitspec is specified as a single bitnum (the first form) then the associated string is printed if the specified bit is set (or printed if the bit is not set if ~ is specified); otherwise nothing is printed. If bitspec is specified as a range of bits (the second form) then the associated string will be output followed by `=' and then the hexadecimal value of the specified range of bits; if the value also matches any of the optional fieldspec values, the fieldspec string is printed instead of the value.

UDI Core Specification Contents