fmt: Formatting Functions

Macros
#define	FMT_ULONG_LEN   40

Functions
unsigned	fmt_pad (char *buffer, unsigned width, char pad)
unsigned	fmt_sign_pad (char *buffer, int sign, unsigned width, char pad)

Variables
const char	fmt_lcase_digits [36]
const char	fmt_ucase_digits [36]

Signed integer conversions
unsigned	fmt_snumw (char *buffer, long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_sdec (char *buffer, long num)
unsigned	fmt_sdecw (char *buffer, long num, unsigned width, char pad)

Signed long long integer conversions
unsigned	fmt_sllnumw (char *buffer, long long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_slldec (char *buffer, long long num)
unsigned	fmt_slldecw (char *buffer, long long num, unsigned width, char pad)

Unsigned integer conversions
unsigned	fmt_unumw (char *buffer, unsigned long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_udec (char *buffer, unsigned long num)
unsigned	fmt_udecw (char *buffer, unsigned long num, unsigned width, char pad)
unsigned	fmt_uhex (char *buffer, unsigned long num)
unsigned	fmt_uhexw (char *buffer, unsigned long num, unsigned width, char pad)
unsigned	fmt_uHex (char *buffer, unsigned long num)
unsigned	fmt_uHexw (char *buffer, unsigned long num, unsigned width, char pad)

Unsigned long long integer conversions
unsigned	fmt_ullnumw (char *buffer, unsigned long long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_ulldec (char *buffer, unsigned long long num)
unsigned	fmt_ulldecw (char *buffer, unsigned long long num, unsigned width, char pad)
unsigned	fmt_ullhex (char *buffer, unsigned long long num)
unsigned	fmt_ullhexw (char *buffer, unsigned long long num, unsigned width, char pad)
unsigned	fmt_ullHex (char *buffer, unsigned long long num)
unsigned	fmt_ullHexw (char *buffer, unsigned long long num, unsigned width, char pad)

Miscelaneous formatting
unsigned	fmt_char (char *buffer, int ch, unsigned width, char pad)
unsigned	fmt_mem (char *buffer, const char *s, unsigned length, unsigned width, char pad)
unsigned	fmt_chars (char *buffer, const char *s, unsigned width, char pad)
unsigned	fmt_str (char *buffer, const struct str *s, unsigned width, char pad)

Multiple item formatting
typedef unsigned(*	fmt_function) (char *buffer, const void *data, unsigned width, char pad)
unsigned	fmt_multi (char *buffer, const char *format,...)
unsigned	fmt_multiv (char *buffer, const char *format, va_list ap)

Detailed Description

Function Naming

1. Prefix
   • fmt_ : Always present
2. Data type
   • s : Signed integer (long)
   • u : Unsigned integer (long)
   • sll : Signed long long integer
   • ull : Unsigned long long integer
3. Conversion type
   • num : Generic number
   • dec : Decimal
   • hex : Hexadecimal (lower case)
   • Hex : Hexadecimal (upper case)
4. Width / Padding
   • w : (optional) Pad out the result to a minimum width

For example, fmt_sdecw formats a signed integer using decimal with width padding.

Calling Convention

Parameters to the fmt functions are passed in the following order. The presence of all parameters, except for buffer, is dependant on which function is being used.

1. buffer : The character string into which to put the data result. If this is NULL, no data is written, and only the length is calculated. This is useful for determining how long a formatted string might be.
2. number or data : The input data item to convert.
3. width : The minimum output width.
4. pad : The character with which to pad the output.
5. base : The numerical base to use.
6. digits : The array of digits to use.

Return Value

All fmt functions return the number of bytes written to the buffer space.

Macro Definition Documentation

FMT_ULONG_LEN

#define FMT_ULONG_LEN   40

The maximum space used by a formatted number. This value is long enough for 2^128 plus a trailing NUL byte.

Referenced by fmt_sllnumw(), fmt_snumw(), fmt_ullnumw(), and fmt_unumw().

Typedef Documentation

fmt_function

typedef unsigned(* fmt_function) (char *buffer, const void *data, unsigned width, char pad)

Format function prototype, used by the "@" conversion in fmt_multi()

Function Documentation

fmt_char()

unsigned fmt_char	(	char *	buffer,
		int	ch,
		unsigned	width,
		char	pad
	)

Format a single character

References fmt_char(), obuf_endl(), obuf_putu(), obuf_write(), and outbuf.

Referenced by fmt_char(), and fmt_multiv().

fmt_multi()

unsigned fmt_multi	(	char *	buffer,
		const char *	format,
			...
	)

Format multiple items.

The format string used to describe the multiple items is related to what is used with printf and related functions, but has one critical difference: instead of formatted items being escaped, literal text must be escaped. This solves the largest security issue with using printf-style format strings, which is the possibility of accidentally treating untrusted text as the format string.

The format string is composed of zero or more format items. Each item is composed of the following parts:

Zero or more flag characters:

#

Use an "alternate form" to convert the value. For octal conversion, the result is prefixed with a 0 . For hexadecimal conversion, the result is prefixed with either 0x or 0X depending on the conversion type.

-

(not implemented) Pad on the right (left justified) instead of on the left (default right justified).

0

Pad the result with zeros instead of spaces.

Field width.

The option field width is a decimal digit string specifying the minimum field width. If the converted value has fewer characters than the field width, it will be padded out to the field width.

Length modifier:

l

The following integer conversion uses a long type.

ll

The following integer conversion uses a long long type.

Conversion specifier.

d

i

The int argument is converted to a signed decimal string.

o

u

x

X

The unsigned int argument is converted to a unsigned octal, unsigned decimal, lowercase unsigned hexadecimal, or uppercase unsigned hexadecimal string respectively.

c

The int argument is converted to an unsigned char.

s

The const char* argument is converted.

S

The const str* argument is converted.

p

The void* argument is converted to a hexadecimal string.

m

The result of strerror(errno) is formatted.

\

The next character literal from the format string is converted as with c conversion.

{string}

The literal string enclosed by the parenthesis is converted as with s conversion.

@

Formats an arbitrary object using two arguments: The first fmt_function argument is used to format the following void* argument. The fmt_function is passed the output buffer, the data pointer, width, and pad character, and is expected to return the number of bytes formatted.

References fmt_multiv(), fmt_ullnumw(), and fmt_unumw().

fmt_multiv()

unsigned fmt_multiv	(	char *	buffer,
		const char *	format,
		va_list	ap
	)

Format multiple items, using a va_list.

This is the core function used to format multiple items.

References fmt_char(), fmt_lcase_digits, fmt_sllnumw(), fmt_snumw(), fmt_ucase_digits, fmt_ullnumw(), and fmt_unumw().

Referenced by fmt_multi(), obuf_putfv(), str_catfv(), and str_copyfv().

fmt_pad()

unsigned fmt_pad	(	char *	buffer,
		unsigned	width,
		char	pad
	)

Format a pad character.

fmt_sdec()

unsigned fmt_sdec	(	char *	buffer,
		long	num
	)

Format a signed integer as decimal.

References fmt_lcase_digits, and fmt_snumw().

fmt_sdecw()

unsigned fmt_sdecw	(	char *	buffer,
		long	num,
		unsigned	width,
		char	pad
	)

Format a signed integer as decimal with padding.

References fmt_lcase_digits, and fmt_snumw().

Referenced by fmt_sllnumw(), and fmt_snumw().

fmt_sign_pad()

unsigned fmt_sign_pad	(	char *	buffer,
		int	sign,
		unsigned	width,
		char	pad
	)

Format padding for a signed number.

References fmt_sign_pad(), obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_sign_pad(), fmt_sllnumw(), and fmt_snumw().

fmt_slldec()

unsigned fmt_slldec	(	char *	buffer,
		long long	num
	)

Format a signed long long integer as decimal.

References fmt_lcase_digits, and fmt_sllnumw().

fmt_slldecw()

unsigned fmt_slldecw	(	char *	buffer,
		long long	num,
		unsigned	width,
		char	pad
	)

Format a signed long long integer as decimal with padding.

References fmt_lcase_digits, and fmt_sllnumw().

Referenced by fmt_sllnumw().

fmt_sllnumw()

unsigned fmt_sllnumw	(	char *	buffer,
		long long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format a signed long long integer of arbitrary base with optional padding.

References fmt_sdecw(), fmt_sign_pad(), fmt_slldecw(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_multiv(), fmt_slldec(), fmt_slldecw(), obuf_putsllnumw(), and str_catsllnumw().

fmt_snumw()

unsigned fmt_snumw	(	char *	buffer,
		long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format a signed integer of arbitrary base with optional padding.

References fmt_sdecw(), fmt_sign_pad(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_multiv(), fmt_sdec(), fmt_sdecw(), obuf_putsnumw(), and str_catsnumw().

fmt_udec()

unsigned fmt_udec	(	char *	buffer,
		unsigned long	num
	)

Format an unsigned integer as decimal.

References fmt_lcase_digits, and fmt_unumw().

Referenced by dns_name4_domain().

fmt_udecw()

unsigned fmt_udecw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned integer as decimal with padding.

References fmt_lcase_digits, and fmt_unumw().

Referenced by fmt_unumw().

fmt_uhex()

unsigned fmt_uhex	(	char *	buffer,
		unsigned long	num
	)

Format an unsigned integer as (lower-case) hexadecimal.

References fmt_lcase_digits, and fmt_unumw().

fmt_uHex()

unsigned fmt_uHex	(	char *	buffer,
		unsigned long	num
	)

Format an unsigned integer as (upper-case) hexadecimal.

References fmt_ucase_digits, and fmt_unumw().

fmt_uhexw()

unsigned fmt_uhexw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned integer as (lower-case) hexadecimal with padding.

References fmt_lcase_digits, and fmt_unumw().

Referenced by fmt_unumw().

fmt_uHexw()

unsigned fmt_uHexw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned integer as (upper-case) hexadecimal with padding.

References fmt_ucase_digits, and fmt_unumw().

Referenced by fmt_unumw().

fmt_ulldec()

unsigned fmt_ulldec	(	char *	buffer,
		unsigned long long	num
	)

Format an unsigned long long integer as decimal.

References fmt_lcase_digits, and fmt_ullnumw().

fmt_ulldecw()

unsigned fmt_ulldecw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned long long integer as decimal with padding.

References fmt_lcase_digits, and fmt_ullnumw().

Referenced by fmt_ullnumw().

fmt_ullhex()

unsigned fmt_ullhex	(	char *	buffer,
		unsigned long long	num
	)

Format an unsigned long long integer as hexadecimal.

References fmt_lcase_digits, and fmt_ullnumw().

fmt_ullHex()

unsigned fmt_ullHex	(	char *	buffer,
		unsigned long long	num
	)

Format an unsigned long long integer as (upper-case) hexadecimal.

References fmt_ucase_digits, and fmt_ullnumw().

fmt_ullhexw()

unsigned fmt_ullhexw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned long long integer as hexadecimal with padding.

References fmt_lcase_digits, and fmt_ullnumw().

Referenced by fmt_ullnumw().

fmt_ullHexw()

unsigned fmt_ullHexw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned long long integer as (upper-case) hexadecimal with padding.

References fmt_ucase_digits, and fmt_ullnumw().

Referenced by fmt_ullnumw().

fmt_ullnumw()

unsigned fmt_ullnumw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format an unsigned long long integer of arbitrary base with optional padding.

References fmt_ulldecw(), fmt_ullhexw(), fmt_ullHexw(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_multi(), fmt_multiv(), fmt_ulldec(), fmt_ulldecw(), fmt_ullhex(), fmt_ullHex(), fmt_ullhexw(), fmt_ullHexw(), obuf_putullnumw(), and str_catullnumw().

fmt_unumw()

unsigned fmt_unumw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format an unsigned integer of arbitrary base with optional padding.

References fmt_udecw(), fmt_uHexw(), fmt_uhexw(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_multi(), fmt_multiv(), fmt_udec(), fmt_udecw(), fmt_uhex(), fmt_uHex(), fmt_uhexw(), fmt_uHexw(), obuf_putunumw(), and str_catunumw().

Variable Documentation

fmt_lcase_digits

const char fmt_lcase_digits[36]

Array of digits for lower-case conversions

Referenced by dns_name6_domain(), fmt_multiv(), fmt_sdec(), fmt_sdecw(), fmt_slldec(), fmt_slldecw(), fmt_udec(), fmt_udecw(), fmt_uhex(), fmt_uhexw(), fmt_ulldec(), fmt_ulldecw(), fmt_ullhex(), fmt_ullhexw(), obuf_puti(), obuf_putill(), obuf_putiw(), obuf_putiwll(), obuf_putu(), obuf_putull(), obuf_putuw(), obuf_putuwll(), obuf_putx(), obuf_putxll(), obuf_putxw(), obuf_putxwll(), str_cati(), str_catill(), str_catiw(), str_catiwll(), str_catu(), str_catull(), str_catuw(), str_catuwll(), str_catx(), str_catxll(), str_catxw(), and str_catxwll().

fmt_ucase_digits

const char fmt_ucase_digits[36]

Array of digits for upper-case conversions

Referenced by fmt_multiv(), fmt_uHex(), fmt_uHexw(), fmt_ullHex(), fmt_ullHexw(), obuf_putX(), obuf_putXll(), obuf_putXw(), and obuf_putXwll().