Data Structures
struct	output_stream_to_buffer
	Concrete struct for a buffer output stream. More...

Macros
#define	ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
	Size of array. More...

#define	ASSIGN_CONST_STRUCT_POINTER_FROM_MEMBER_POINTER(sp, st, m, mp)
	Const structure pointer from member pointer. More...

#define	ASSIGN_STRUCT_POINTER_FROM_MEMBER_POINTER(sp, st, m, mp)
	Structure pointer from member pointer. More...

#define	INTEGERIFY(v) INTEGERIFY_DO_NOT_CALL_DIRECTLY(v)
	Unsigned long from defined number. More...

#define	MAXIMUM(a, b) ((a) < (b) ? (b) : (a))
	Larger of two numbers. More...

#define	MEMBER_OFFSET(st, m) ((size_t)(&(((st *)0)->m)))
	Offset of member in struct. More...

#define	MINIMUM(a, b) ((a) < (b) ? (a) : (b))
	Smaller of two numbers. More...

#define	STACK_SIZE_GREEN_FROM_MAX_OBSERVED_STACK_USED(used) ((used + 3) * 100 / 80)
	Compute stack size based on observation. More...

#define	STRINGIFY(v) STRINGIFY_DO_NOT_CALL_DIRECTLY(v)
	String from defined number. More...

Enumerations
enum	output_stream_to_buffer_mode { OUTPUT_STREAM_TO_BUFFER_MODE__BINARY, OUTPUT_STREAM_TO_BUFFER_MODE__ZERO_TERMINATE }
	Mode of a buffer output stream. More...

Functions
bool	ltrx_output_stream_init_to_count (struct output_stream_to_count *outStream)
	Set up an output stream to only count characters out. More...

int	snprintf (char str, size_t size, const char format,...)
	String print. More...

int	sscanf (const char str, const char format,...)
	String scan. More...

bool	ltrx_output_stream_init_to_buffer (struct output_stream_to_buffer outStream, void buffer, size_t bufferLength, enum output_stream_to_buffer_mode mode)
	Set up an output stream to a RAM buffer. More...

Detailed Description

Utilities comprise a collection of generally useful definitions.

Macro Definition Documentation

#define ARRAY_SIZE ( a ) (sizeof(a) / sizeof((a)[0]))

Size of array.

Parameters

[in] a Name of the array.

Returns: The dimension of the array.

#define ASSIGN_CONST_STRUCT_POINTER_FROM_MEMBER_POINTER	(	sp,
		st,
		m,
		mp
	)

Value:

_Pragma("GCC diagnostic push"); \
    _Pragma("GCC diagnostic ignored \"-Wcast-align\""); \
    (sp) = ((const st *)((mp) ? ((const char *)(mp) - MEMBER_OFFSET(st, m)) : NULL)); \
    _Pragma("GCC diagnostic pop");

Const structure pointer from member pointer.

You must first declare your const struct pointer sp to receive the result. This macro will fill it in with the address of the structure that contains the designated member. If mp is NULL, then sp will be set to NULL.

Parameters

[out]	sp	The const struct pointer name.
[in]	st	The struct declaration.
[in]	m	The member name in the struct.
[in]	mp	The member pointer.

#define ASSIGN_STRUCT_POINTER_FROM_MEMBER_POINTER	(	sp,
		st,
		m,
		mp
	)

Value:

_Pragma("GCC diagnostic push"); \
    _Pragma("GCC diagnostic ignored \"-Wcast-align\""); \
    (sp) = ((st *)((mp) ? ((char *)(mp) - MEMBER_OFFSET(st, m)) : NULL)); \
    _Pragma("GCC diagnostic pop");

Structure pointer from member pointer.

You must first declare your struct pointer sp to receive the result. This macro will fill it in with the address of the structure that contains the designated member. If mp is NULL, then sp will be set to NULL. Note that if m is const, this will fail; use ASSIGN_CONST_STRUCT_POINTER_FROM_MEMBER_POINTER() instead.

Parameters

[out]	sp	The struct pointer name.
[in]	st	The struct declaration.
[in]	m	The member name in the struct.
[in]	mp	The member pointer.

#define INTEGERIFY ( v ) INTEGERIFY_DO_NOT_CALL_DIRECTLY(v)

Unsigned long from defined number.

Turns a defined number into an unsigned long constant. Allows the same define to be used numerically and in a string message. See also STRINGIFY().

Parameters

[in] v The defined number.

#define MAXIMUM	(	a,
		b
	)	((a) < (b) ? (b) : (a))

Larger of two numbers.

Parameters

[in]	a	First number.
[in]	b	Second number.

Returns: The larger value.

#define MEMBER_OFFSET	(	st,
		m
	)	((size_t)(&(((st *)0)->m)))

Offset of member in struct.

Parameters

[in]	st	The struct declaration.
[in]	m	The member name in the struct.

Returns: The offset in bytes from the beginning of the struct.

#define MINIMUM	(	a,
		b
	)	((a) < (b) ? (a) : (b))

Smaller of two numbers.

Parameters

[in]	a	First number.
[in]	b	Second number.

Returns: The smaller value.

#define STACK_SIZE_GREEN_FROM_MAX_OBSERVED_STACK_USED ( used ) ((used + 3) * 100 / 80)

Compute stack size based on observation.

This macro takes the maximum observed "Stack size" from the Diagnostics Threads status, and pads it so the status will read "green". "Green" status is up to 80% stack utilization.

Parameters

[in] used Observed stack usage in bytes.

Returns: Padded size.

#define STRINGIFY ( v ) STRINGIFY_DO_NOT_CALL_DIRECTLY(v)

String from defined number.

Turns a defined number into a string constant. Allows the same define to be used numerically and in a string message. See also INTEGERIFY().

Parameters

[in] v The defined number.

Enumeration Type Documentation

enum output_stream_to_buffer_mode

Mode of a buffer output stream.

Enumerator
OUTPUT_STREAM_TO_BUFFER_MODE__BINARY	Binary mode allows any data values.
OUTPUT_STREAM_TO_BUFFER_MODE__ZERO_TERMINATE	Zero-terminate mode allows only non-zero data and terminates with a zero byte.

Function Documentation

bool ltrx_output_stream_init_to_buffer	(	struct output_stream_to_buffer *	outStream,
		void *	buffer,
		size_t	bufferLength,
		enum output_stream_to_buffer_mode	mode
	)

Set up an output stream to a RAM buffer.

Return values

true	Success.
false	Failed.

Parameters

[out]	outStream	Your buffer output stream struct to initialize.
[in]	buffer	Pointer to your buffer that will be written by the stream.
[in]	bufferLength	Length of your buffer.
[in]	mode	Selected output mode.

bool ltrx_output_stream_init_to_count ( struct output_stream_to_count * outStream )

Set up an output stream to only count characters out.

Return values

true	Success.
false	Failed.

Parameters

[out] outStream Your counting output stream struct to initialize.

int snprintf	(	char *	str,
		size_t	size,
		const char *	format,
			...
	)

String print.

Writes at most size bytes (including the terminating null byte ('\0')) to str under the control of a format string that specifies how subsequent arguments are converted for output.

Returns: Number of characters printed (excluding the null byte used to end output to strings).

Return values

-1	Print failed.

Format of the format string

The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, an optional precision and an optional length modifier.

The arguments must correspond properly (after type promotion) with the conversion specifier. The arguments are used in the order given, where each '*' and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given).

The flag characters

The character % is followed by zero or more of the following flags:

#

The value should be converted to an "alternate form". For o conversions, the first character of the output string is made zero (by prefixing a 0 if it was not zero already). For x and X conversions, a nonzero result has the string "0x" (or "0X" for X conversions) prepended to it. For other conversions, the result is undefined.

0

The value should be zero padded. For d,i,o,u,x, and X conversions, the converted value is padded on the left with zeros rather than blanks. If the 0 and - flags both appear, the 0 flag is ignored. If a precision is given with a numeric conversion (d,i,o,u,x, and X), the 0 flag is ignored. For other conversions, the behavior is undefined.

-

The converted value is to be left adjusted on the field boundary. (The default is right justification.) Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.

' '

(a space) A blank should be left before a positive number (or empty string) produced by a signed conversion.

+

A sign (+ or -) should always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers. A + overrides a space if both are used.

The field width

An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write "*" to specify that the field width is given in the next argument, which must be of type int. A negative field width is taken as a '-' flag followed by a positive field width. In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

The precision

An optional precision, in the form of a period ('.') followed by an optional decimal digit string. Instead of a decimal digit string one may write "*" to specify that the precision is given in the next argument, which must be of type int. If the precision is given as just '.', or the precision is negative, the precision is taken to be zero. This gives the minimum number of digits to appear for d,i,o,u,x, and X conversions or the maximum number of characters to be printed from a string for s and S conversions.

The length modifier

Here, "integer conversion" stands for d,i,o,u,x, or X conversion.

hh

A following integer conversion corresponds to a signed char or unsigned char argument, or a following n conversion corresponds to a pointer to a signed char argument.

h

A following integer conversion corresponds to a short int or unsigned short int argument, or a following n conversion corresponds to a pointer to a short int argument.

l

(ell) A following integer conversion corresponds to a long int or unsigned long int argument, or a following n conversion corresponds to a pointer to a long int argument.

The conversion specifier

A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are:

d,i

The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty.

o,u,x,X

The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and X) notation. The letters abcdef are used for x conversions; the letters ABCDEF are used for X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty.

c

The int argument is converted to an unsigned char, and the resulting character is written.

s

The const char * argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating null byte ('\0'); if a precision is specified, no more than the number specified are written. If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte.

p

The void * pointer argument is printed in hexadecimal (as if by 0x%x or 0x%lx).

I

The unsigned long argument is converted to network byte order then printed in dotted IPv4 address notation.

n

The number of characters written so far is stored into the integer indicated by the int * (or variant) pointer argument. No argument is converted.

%

A '%' is written. No argument is converted. The complete conversion specification is '%%'.

Parameters

[out]	str	String output.
[in]	size	Size of string output.
[in]	format	Format specification.

int sscanf	(	const char *	str,
		const char *	format,
			...
	)

String scan.

Scans input according to format as described below. This format may contain conversion specifications; any conversion results are stored in the locations pointed to by the pointer arguments that follow format. Each pointer argument must be type compatible with the value returned by the corresponding conversion specification.

The format string consists of a sequence of directives which describe how to process the sequence of input characters. If processing of a directive fails, no further input is read, and sscanf() returns. A "failure" can be either of the following: input failure, meaning that input characters were unavailable, or matching failure, meaning that the input was inappropriate.

A directive is one of the following:

A sequence of white-space characters (space, tab, newline, etc.). This directive matches any amount of white space, or none, in the input.

An ordinary character (other than white space or '%'). This character must exactly match the next character of input.

A conversion specification, which commences with a '%' (percent) character. A sequence of characters from the input is converted according to this specification, and the result is placed in the corresponding pointer argument. If the next item of input does not match the conversion specification, the conversion fails-this is a matching failure.

Each conversion specification in format begins with the character '%' followed by:

An optional '*' assignment-suppression character: sscanf() reads input as directed by the conversion specification, but discards the input. No corresponding pointer argument is required, and this specification is not included in the count of successful assignments returned by sscanf().

An optional decimal integer which specifies the maximum field width. Reading of characters stops either when this maximum is reached or when a nonmatching character is found, whichever happens first. Most conversions discard initial white space characters (the exceptions are noted below), and these discarded characters don't count toward the maximum field width. String input conversions store a terminating null byte ('\0') to mark the end of the input; the maximum field width does not include this terminator.

An optional type modifier character. For example, the l type modifier is used with integer conversions such as %d to specify that the corresponding pointer argument refers to a long int rather than a pointer to an int.

A conversion specifier that specifies the type of input conversion to be performed.

The conversion specifications in format begin with '%'. Each corresponds in order with successive pointer arguments.

Conversions

The following type modifier characters can appear in a conversion specification:

h

Indicates that the conversion will be one of d, i, o, u, x, X, or n and the next pointer is a pointer to a short int or unsigned short int (rather than int).

hh

As for h, but the next pointer is a pointer to a signed char or unsigned char.

l

Indicates either that the conversion will be one of d, i, o, u, x, X, or n and the next pointer is a pointer to a long int or unsigned long int (rather than int).

The following conversion specifiers are available:

%

Matches a literal '%'. That is, % in the format string matches a single input '%' character. No conversion is done (but initial white space characters are discarded), and assignment does not occur.

d

Matches an optionally signed decimal integer; the next pointer must be a pointer to int.

i

Matches an optionally signed integer; the next pointer must be a pointer to int. The integer is read in base 16 if it begins with 0x or 0X, in base 8 if it begins with 0, and in base 10 otherwise. Only characters that correspond to the base are used.

o

Matches an unsigned octal integer; the next pointer must be a pointer to unsigned int.

u

Matches an unsigned decimal integer; the next pointer must be a pointer to unsigned int.

x

Matches an unsigned hexadecimal integer; the next pointer must be a pointer to unsigned int.

X

Equivalent to x.

s

Matches a sequence of non-white-space characters; the next pointer must be a pointer to character array that is long enough to hold the input sequence and the terminating null byte ('\0'), which is added automatically. The input string stops at white space or at the maximum field width, whichever occurs first.

c

Matches a sequence of characters whose length is specified by the maximum field width (default 1); the next pointer must be a pointer to char, and there must be enough room for all the characters (no terminating null byte is added). The usual skip of leading white space is suppressed. To skip white space first, use an explicit space in the format.

[

Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to char, and there must be enough room for all the characters in the string, plus a terminating null byte. The usual skip of leading white space is suppressed. The string is to be made up of characters in (or not in) a particular set; the set is defined by the characters between the open bracket [ character and a close bracket ] character. The set excludes those characters if the first character after the open bracket is a circumflex (^). To include a close bracket in the set, make it the first character after the open bracket or the circumflex; any other position will end the set. The hyphen character - is also special; when placed between two other characters, it adds all intervening characters to the set. To include a hyphen, make it the last character before the final close bracket. For instance, [^]0-9-] means the set "everything except close bracket, zero through nine, and hyphen". The string ends with the appearance of a character not in the (or, with a circumflex, in) set or when the field width runs out.

p

Matches a pointer value (as printed by %p in snprintf); the next pointer must be a pointer to a pointer to void.

n

Nothing is expected; instead, the number of characters consumed thus far from the input is stored through the next pointer, which must be a pointer to int. This is not a conversion, although it can be suppressed with the * assignment-suppression character.

Returns: Number of items successfully matched and assigned.

Return values

-1	Scan failed.

Parameters

[in]	str	String to scan.
[in]	format	Format specification.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation