System.h File Reference

Detailed Description

Basic system services.

This module provides basic low-level "system" services; e.g., character output, printf-like output, and exit handling.

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for System.h:

Go to the source code of this file.

Macros
#define	System_A_cannotFitIntoArg   "sizeof(float) > sizeof(intptr_t)"
	Assert that the target's float type fits in an intptr_t More...

Typedefs
typedef void(*	System_AtexitHandler) (int arg1)
	System's atexit function prototype. More...
typedef void(*	System_AbortFxn) (void)
	System abort function prototype. More...
typedef void(*	System_ExitFxn) (int arg1)
	System exit function prototype. More...

Functions
void	System_abort (const char *str)
	Print a message and abort currently running executable. More...
void	System_abortStd (void)
	ANSI C Standard implementation of abortFxn function. More...
void	System_abortSpin (void)
	Lightweight implementation of abortFxn function. More...
bool	System_atexit (System_AtexitHandler handler)
	Add an exit handler. More...
void	System_exit (int stat)
	Exit currently running executable. More...
void	System_exitStd (int stat)
	Implements an exitFxn function. More...
void	System_exitSpin (int stat)
	Implements an exitFxn function. More...
void	System_putch (char ch)
	Output a single character. More...
void	System_flush (void)
	Flush standard System I/O. More...
int	System_printf (const char *fmt,...)
	A smaller faster printf. More...
int	System_sprintf (char buf[], const char *fmt,...)
	Write formated output to a character buffer. More...
int	System_vprintf (const char *fmt, va_list va)
	A va_list printf. More...
int	System_vsprintf (char buf[], const char *fmt, va_list va)
	A va_list sprintf. More...
int	System_snprintf (char buf[], size_t n, const char *fmt,...)
	Write formated output to a character buffer. More...
int	System_vsnprintf (char buf[], size_t n, const char *fmt, va_list va)
	A va_list snprintf. More...

Variables
const int	System_maxAtexitHandlers
	Maximum number of dynamic atexit handlers allowed in the system. More...
const System_AbortFxn	System_abortFxn
	Abort handler function. More...
const System_ExitFxn	System_exitFxn
	Exit handler function. More...

Macro Definition Documentation

System_A_cannotFitIntoArg

#define System_A_cannotFitIntoArg   "sizeof(float) > sizeof(intptr_t)"

Assert that the target's float type fits in an intptr_t

This assertion is triggered when the f format specifier is used, the argument treated as an intptr_t, but for the current target sizeof(Float) > sizeof(intptr_t).

Typedef Documentation

System_AtexitHandler

typedef void(* System_AtexitHandler) (int arg1)

System's atexit function prototype.

Functions of this type can be added to the list of functions that are executed during application termination.

System_AbortFxn

typedef void(* System_AbortFxn) (void)

System abort function prototype.

Functions of this type can be plugged into System's abort function that will be executed during abnormal application termination.

System_ExitFxn

typedef void(* System_ExitFxn) (int arg1)

System exit function prototype.

Functions of this type can be plugged into System's exit function that will be executed during normal application termination.

Function Documentation

System_abort()

void System_abort

(

const char *

str

)

Print a message and abort currently running executable.

This is called when an executable abnormally terminates. No exit functions bound via System_atexit() or the ANSI C Standard Library atexit() functions are executed.

Parameters

str	abort message (not a format string)

System_abortStd()

void System_abortStd

(

void

)

ANSI C Standard implementation of abortFxn function.

This function calls ANSI C Standard abort() to terminate currently running executable. This function is used by default in System_abortFxn.

System_abortSpin()

void System_abortSpin

(

void

)

Lightweight implementation of abortFxn function.

This functions loops indefinitely. This can used as an alternative System_abortFxn when a lightweight implementation is required instead of the ANSI C Standard abort().

System_atexit()

bool System_atexit

(

System_AtexitHandler

handler

)

Add an exit handler.

System_atexit pushes handler onto an internal stack of functions to be executed when system is exiting (e.g. System_exit is called). Up to System_maxAtexitHandlers functions can be specified in this manner. During the exit processing, the functions are popped off the internal stack and called until the stack is empty.

The System gate is entered before the System_atexit functions are called.

Returns true on success. If false is returned, the exit handler was not added and it will not be called during an exit.

Parameters

handler

the AtexitHandler to invoke during system

Return values

true	if handler was registered successfully, false otherwise

System_exit()

void System_exit

(

int

stat

)

Exit currently running executable.

This function is called when an executable needs to terminate normally. This function processes all functions bound via System_atexit and then calls System_exitFxn.

Parameters

stat	exit status to return to calling environment.

System_exitStd()

void System_exitStd

(

int

stat

)

Implements an exitFxn function.

This function calls ANSI C Standard exit() to terminate currently running executable normally. This function is used by default in System_exitFxn.

Parameters

stat	exit status to return to calling environment.

System_exitSpin()

void System_exitSpin

(

int

stat

)

Implements an exitFxn function.

This functions loops indefinitely. This can used as an alternative System_exitFxn when a light weight implementation is required instead of the ANSI C Standard exit().

Parameters

stat	exit status to return to calling environment.

System_putch()

void System_putch

(

char

ch

)

Output a single character.

The SystemSupport module's putch function is called by this function.

Parameters

ch	character to be output.

System_flush()

void System_flush

(

void

)

Flush standard System I/O.

This function causes any buffered output characters are "written" to the output device.

The SystemSupport module's flush function is called by this function.

System_printf()

int System_printf	(	const char *	fmt,
			...
	)

A smaller faster printf.

This function behaves much like the ANSI C Standard printf but does not support the full range of format strings specified by the C Standard. In addition, several non-standard format specifiers are recognized.

Format Strings

The format string is a character string 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.

Flags

The following flags are supported:

• - The converted value is to be left adjusted on the field boundary (the default is right justification.) - 0 The value should be zero padded. For d, i, o, u, and x conversions, the converted value is padded on the left with zeros rather than blanks.

Field Width

The optional field width specifier is a 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. A negative field width is taken as a '-' flag followed by a positive field width.

Precision

The optional precision specifier is 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, and x conversions, or the maximum number of characters to be printed from a string for s conversions.

Length Modifiers

The optional length modifier is a single character from the following list.

• l A following integer conversion corresponds to a long int or unsigned long int argument

Conversion Specifiers

The following conversion specifiers are supported.

• d, i signed integer - u unsigned decimal - x unsigned hex - o unsigned octal - p pointer (@ + hex num) - c character - s string

Extended Conversion Specifiers

The following conversion specifiers are optionally supported. See the System_extendedFormats configuration parameter for more information about how to enable these conversion specifiers.

Parameters

fmt	a 'printf-style' format string

Return values

number

of characters written

System_sprintf()

int System_sprintf	(	char	buf[],
		const char *	fmt,
			...
	)

Write formated output to a character buffer.

This function is identical to System_printf except that the output is copied to the specified character buffer buf followed by a terminating '\0' character.

System_sprintf returns the number of characters output not including the '\0' termination character.

Parameters

buf	a character output buffer
fmt	a 'printf-style' format string

Return values

number

of characters written

System_vprintf()

int System_vprintf	(	const char *	fmt,
		va_list	va
	)

A va_list printf.

This function is identical to System_printf except that its arguments are passed via a va_list (a "varargs list").

by the fmt string

System_vprintf returns the number of characters output.

Parameters

fmt	a standard 'printf-style' format string.
va	an args list that points to the arguments referenced

Return values

number

of characters written

System_vsprintf()

int System_vsprintf	(	char	buf[],
		const char *	fmt,
		va_list	va
	)

A va_list sprintf.

This function is identical to System_sprintf except that its arguments are passed via a va_list (a "varargs list").

by the fmt string

vsprintf returns the number of characters output.

Parameters

buf	a character output buffer
fmt	a standard 'printf-style' format string.
va	an arguments list that points to the arguments referenced

Return values

number

of characters written

System_snprintf()

int System_snprintf	(	char	buf[],
		size_t	n,
		const char *	fmt,
			...
	)

Write formated output to a character buffer.

This function is identical to System_sprintf except that at most n characters are copied to the specified character buffer buf. If n is zero, nothing is written to character buffer. Otherwise, output characters beyond the n - 1 are discarded rather than being written to the character buf, and a null character is written at the end of the characters written into the buffer.

the output buffer buf

snprintf returns the number of characters that would have been written had n been sufficiently large, not counting the terminating '\0' character.

Parameters

buf	a character output buffer
n	the maximum number of characters, including '\0', written to
fmt	a 'printf-style' format string

Return values

number

of characters written

System_vsnprintf()

int System_vsnprintf	(	char	buf[],
		size_t	n,
		const char *	fmt,
		va_list	va
	)

A va_list snprintf.

This function is identical to System_snprintf except that its arguments are passed via a va_list (a "varargs list").

output buffer

by the fmt string

vsnprintf returns the number of characters that would have been written had n been sufficiently large, not counting the terminating '\0' character.

Parameters

buf	a character output buffer
n	at most number of characters including '\0' written to
fmt	a standard 'printf-style' format string.
va	an arguments list that points to the arguments referenced

Return values

number

of characters written

Variable Documentation

System_maxAtexitHandlers

const int System_maxAtexitHandlers

Maximum number of dynamic atexit handlers allowed in the system.

Maximum number of System atexit handlers set during runtime via the System_atexit function.

System_abortFxn

const System_AbortFxn System_abortFxn

Abort handler function.

This configuration parameter allows user to plug in their own abort function. By default System_abortStd which calls ANSI C Standard abort() is plugged in. Alternatively System_abortSpin can be plugged which loops infinitely.

System_exitFxn

const System_ExitFxn System_exitFxn

Exit handler function.

This configuration parameter allows user to plug in their own exit function. By default System_exitStd which calls ANSI C Standard exit() is plugged in. Alternatively System_exitSpin can be plugged which loops infinitely.