Format String Functions

Functions
ssize_t	M_vfprintf (FILE *stream, const char *fmt, va_list ap)
ssize_t	M_fprintf (FILE *stream, const char *fmt,...)
ssize_t	M_vmdprintf (M_fs_file_t *fd, const char *fmt, va_list ap)
ssize_t	M_mdprintf (M_fs_file_t *fd, const char *fmt,...)
ssize_t	M_vdprintf (int fd, const char *fmt, va_list ap)
ssize_t	M_dprintf (int fd, const char *fmt,...)
ssize_t	M_vprintf (const char *fmt, va_list ap)
ssize_t	M_printf (const char *fmt,...)
size_t	M_vsnprintf (char *str, size_t size, const char *fmt, va_list ap)
size_t	M_snprintf (char *buf, size_t size, const char *fmt,...)
size_t	M_vasprintf (char **ret, const char *fmt, va_list ap)
size_t	M_asprintf (char **ret, const char *fmt,...)
size_t	M_vbprintf (M_buf_t *buf, const char *fmt, va_list ap)
size_t	M_bprintf (M_buf_t *buf, const char *fmt,...)

Detailed Description

Formatted String output.

%<character> is used to denote the data type of the function arguments. Arguments are passed after the format string. flags and other modifiers are specified between the % and conversion characters. E.g. %<behavior><character>

Supported features

Flags

Flag	Description
'-'	Left justify output. Default is to right justify. Overrides the '0' flag if both are set.
'+'	Always add the sign (+-) for numeric output. Default is only to add sign for negative. Overrides the ' ' flag if both are set.
'#'	Add the appropriate prefix to the output of numerics. 0x or 0X for Hex. 0 for Octal.
' '	Use a space as if it were the sign for positive numbers.
'0'	Pad numerics with 0. Default padding is space (' ').

Width and precision

A decimal (.) separated value can be specified to control the width and precision of the argument. <width>.<precision>.

The width is the minimum output size. Padding will be added if the output would be smaller than the width. If the output size exceeds the width, the width is ignored and the full input will be output.

Precision for strings controls the length that should be output. If the value is larger than the length of the string, the string length will be used. E.g. ("%.2s", "abc") will result in "ab" for the output.

Precision for floating point determines the number of decimal places to output. The default is 6. It's recommended the maximum precision specified be no large than 14 digits. Digits over 14 can have platform specific rounding differences.

Width and precision are both optional. You can specify one, the other, or both. E.g. "%.2s", "%8.s".

A '*' can be used instead of a decmail value and will read the size from an argument. The argument is an int. The arguments are read right to left. E.g. ("%*.*s", 4, 2, "abc") will result in " ab".

Size modifiers

Specify the data size of a given argument.

Modifier	Description
hh	Size of char. 8 bit.
h	Size of short. 16 bit.
l	Size of long. 8 or 16 bit (system dependant).
ll	Size of long long. 64 bit.
I, z	size of size_t. Based on system size. 32 or 64 bit.
I64	64 bit.
I32	32 bit.

Conversion

Specifies the data type of the argument.

Type	Description
d, i	Signed integer.
o, O	Unsigned integer. Output as octal.
u	Unsigned integer.
x, X	Unsigned integer. Output as hex. 'x' outputs lowercase, 'X' outputs uppercase.
p, P	Unsigned pointer. Output as hex. 'p' outputs lowercase, 'P' outputs uppercase.
e, E, f, F, g, G	Double. All will output in the form [-]ddd.ddd. Default 6 decimal digits unless otherwise precision is otherwise specified.
c	Signed character.
s	String (const char *).

Function Documentation

M_vfprintf()

ssize_t M_vfprintf	(	FILE *	stream,
		const char *	fmt,
		va_list	ap
	)

Output format string to FILE.

Parameters

[in]	stream	FILE stream.
[in]	fmt	Format string.
[in]	ap	arguments.

Returns

Number of characters output. -1 on fatal error.

M_fprintf()

ssize_t M_fprintf	(	FILE *	stream,
		const char *	fmt,
			...
	)

Output format string to FILE (varargs).

See also

M_vfprintf

M_vmdprintf()

ssize_t M_vmdprintf	(	M_fs_file_t *	fd,
		const char *	fmt,
		va_list	ap
	)

Output format string to mstdlib file descriptor.

Parameters

[in]	fd	mstdlib file descriptor.
[in]	fmt	Format string.
[in]	ap	arguments.

Returns

Number of characters output. -1 on fatal error.

M_mdprintf()

ssize_t M_mdprintf	(	M_fs_file_t *	fd,
		const char *	fmt,
			...
	)

Output format string to mstdlib file descriptor (varargs).

See also

M_vmdprintf

M_vdprintf()

ssize_t M_vdprintf	(	int	fd,
		const char *	fmt,
		va_list	ap
	)

Output format string to OS file descriptor.

Parameters

[in]	fd	OS file descriptor.
[in]	fmt	Format string.
[in]	ap	arguments.

Returns

Number of characters output. -1 on fatal error.

M_dprintf()

ssize_t M_dprintf	(	int	fd,
		const char *	fmt,
			...
	)

Output format string to OS file descriptor (varargs).

See also

M_vdprintf

M_vprintf()

ssize_t M_vprintf	(	const char *	fmt,
		va_list	ap
	)

Output format string to stdout.

Parameters

[in]	fmt	Format string.
[in]	ap	arguments.

Returns

Number of characters output. -1 on fatal error.

M_printf()

ssize_t M_printf	(	const char *	fmt,
			...
	)

Output format string to stdout (varargs).

See also

M_vprintf

M_vsnprintf()

size_t M_vsnprintf	(	char *	str,
		size_t	size,
		const char *	fmt,
		va_list	ap
	)

Output format string to pre-allocated string buffer.

Output is NULL terminated.

The output will not exceed size of buffer - 1. 1 byte is reserved for the NULL terminator.

Parameters

[in]	str	Storage location for string.
[in]	size	Size of location.
[in]	fmt	Format string.
[in]	ap	arguments.

Returns

The length of the fully formatted string. If the size of the buffer is smaller than the length the string is truncated but the returned length is not. To determine truncation check is this return against the str buffer.

M_snprintf()

size_t M_snprintf	(	char *	buf,
		size_t	size,
		const char *	fmt,
			...
	)

Output format string to pre-allocated string buffer.

See also

M_vsnprintf

M_vasprintf()

size_t M_vasprintf	(	char **	ret,
		const char *	fmt,
		va_list	ap
	)

Output format string to a newly allocated string buffer.

Output is NULL terminated.

Parameters

[out]	ret	Allocated string.
[in]	fmt	Format string.
[in]	ap	arguments.

Returns

Number of characters output.

M_asprintf()

size_t M_asprintf	(	char **	ret,
		const char *	fmt,
			...
	)

Output format string to a newly allocated string buffer (varargs).

See also

M_vasprintf

M_vbprintf()

size_t M_vbprintf	(	M_buf_t *	buf,
		const char *	fmt,
		va_list	ap
	)

Output format string to an M_buf buffer.

Output is NULL terminated.

Parameters

[in]	buf	Buffer
[in]	fmt	Format string.
[in]	ap	arguments.

Returns

Number of characters output.

M_bprintf()

size_t M_bprintf	(	M_buf_t *	buf,
		const char *	fmt,
			...
	)

Output format string to an M_buf buffer.

See also

M_vbprintf