This module provides basic low-level "system" services; e.g.,
character output, printf-like output, and exit handling.
const System_STATUS_UNKNOWN |
|
Unknown exit status value
#define System_STATUS_UNKNOWN (Int)0xCAFE
DETAILS
When the program exits by calling
System_exit() the
System's
atexit functions are passed the status value passed to
System_exit(). However, if the program exits using
the ANSI C Standard Library
exit() function, the
System's
atexit
functions are passed
System_STATUS_UNKNOWN; ANSI C
atexit
functions are not passed the exit status.
typedef System_AbortFxn |
|
System abort function prototype
typedef Void (*System_AbortFxn)();
DETAILS
Functions of this type can be plugged into System's abort function
that will be executed during abnormal application termination.
SEE
typedef System_AtexitHandler |
|
System's atexit function prototype
typedef Void (*System_AtexitHandler)(Int);
DETAILS
Functions of this type can be added to the list of functions that
are executed during application termination.
SEE
typedef System_ExitFxn |
|
System exit function prototype
typedef Void (*System_ExitFxn)(Int);
DETAILS
Functions of this type can be plugged into System's exit function that
will be executed during normal application termination.
SEE
config System_A_cannotFitIntoArg // module-wide |
|
Assert that the target's Float type fits in an IArg
extern const Assert_Id System_A_cannotFitIntoArg;
DETAILS
This assertion is triggered when the %f format specifier is used,
the argument treated as an IArg, but for the current target
sizeof(Float) > sizeof(IArg).
config System_abortFxn // module-wide |
|
Abort handler function
DETAILS
This configuration parameter allows user to plug in their own abort
function. By default
abortStd which calls ANSI C Standard
abort() is plugged in. Alternatively
abortSpin can be
plugged which loops infinitely.
config System_exitFxn // module-wide |
|
Exit handler function
DETAILS
This configuration parameter allows user to plug in their own exit
function. By default
exitStd which calls ANSI C Standard
exit() is plugged in. Alternatively
exitSpin can be
plugged which loops infinitely.
config System_maxAtexitHandlers // module-wide |
|
Maximum number of dynamic atexit handlers allowed in the system
extern const Int System_maxAtexitHandlers;
DETAILS
Maximum number of
System atexit handlers set during runtime via
the
System.atexit function.
System_abort() // module-wide |
|
Print a message and abort currently running executable
Void System_abort(CString str);
ARGUMENTS
str
abort message (not a format string)
DETAILS
This is called when an executable abnormally terminates.
The
System gate is entered, the
SupportProxy's
abort function is called
and then
abortFxn is called.
No exit functions bound via
System_atexit() or the ANSI C Standard
Library
atexit() functions are executed.
System_abortSpin() // module-wide |
|
Lightweight implementation of abortFxn function
DETAILS
This functions loops indefinitely. This can used as an alternative
abortFxn when a lightweight implementation is
required instead of the ANSI C Standard
abort().
System_abortStd() // module-wide |
|
ANSI C Standard implementation of abortFxn function
DETAILS
This function calls ANSI C Standard
abort() to terminate currently
running executable. This function is used by default in
abortFxn.
System_aprintf() // module-wide |
|
printf where all optional arguments are IArgs
Int System_aprintf(CString fmt, ...);
DETAILS
This function will treat each argument as though it was widened to be
of type
IArg prior to being passed to the
printf function
SEE
System_asprintf() // module-wide |
|
sprintf where all optional arguments are IArgs
Int System_asprintf(Char buf[], CString fmt, ...);
DETAILS
This function will treat each argument as though it was widened to be
of type
IArg prior to being passed to the
sprintf
function.
SEE
System_atexit() // module-wide |
|
Add an exit handler
ARGUMENTS
handler
the AtexitHandler to invoke during system
exit processing.
DETAILS
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
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.
The
SupportProxy's
ISystemSupport.exit function is called
after all the atexit functions are called.
RETURNS
If FALSE is returned, the exit handler was not added and it will
not be called during an exit.
System_avprintf() // module-wide |
|
vprintf where all optional arguments are IArgs
Int System_avprintf(CString fmt, VaList va);
DETAILS
This function will treat each argument as though it was widened to be
of type
IArg prior to being passed to the
vprintf
function.
SEE
System_avsprintf() // module-wide |
|
vsprintf where all optional arguments are IArgs
Int System_avsprintf(Char buf[], CString fmt, VaList va);
DETAILS
This function is identical to
sprintf except that
its arguments are passed via a
VaList (a "varargs list").
This function will treat each argument as though it was widened to be
of type IArg prior to being passed to the vsprintf function
SEE
System_exit() // module-wide |
|
Exit currently running executable
Void System_exit(Int stat);
ARGUMENTS
stat
exit status to return to calling environment.
DETAILS
This function is called when an executable needs to terminate
normally. This function processes all functions bound via
System_atexit and then calls
exitFxn. The
SupportProxy's
exit function is called during this time.
System_exitSpin() // module-wide |
|
Implements an exitFxn function
Void System_exitSpin(Int stat);
ARGUMENTS
stat
exit status to return to calling environment.
DETAILS
This functions loops indefinitely. This can used as an alternative
exitFxn when a light weight implementation is
required instead of the ANSI C Standard
exit().
System_exitStd() // module-wide |
|
Implements an exitFxn function
Void System_exitStd(Int stat);
ARGUMENTS
stat
exit status to return to calling environment.
DETAILS
This function calls ANSI C Standard
exit() to terminate currently
running executable normally. This function is used by default in
exitFxn.
System_flush() // module-wide |
|
Flush standard System I/O
DETAILS
This function causes any buffered output characters are "written"
to the output device.
The
SupportProxy's
flush function is called
by this function.
System_printf() // module-wide |
|
A smaller faster printf
Int System_printf(CString fmt, ...);
ARGUMENTS
fmt
a 'printf-style' format string
DETAILS
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
extendedFormats configuration parameter for more
information about how to enable these conversion specifiers.
- f
-
decimal floating point.
- $
-
non-ANSI conversion prefix. This prefix indicates that the
next character identifies a non-ANSI standard conversion. See
the next section for details.
NON ANSI CONVERSION SPECIFIERS
Among the extended conversion specifiers are unique specifiers which
are not part of ANSI printf. These are specified using a $, for
example %$L.
These unique specifiers do not support the minimum field width
attribute. Certain specifiers have additional restrictions; see below.
- '$L'
-
The argument is treated as a pointer to a Types.Label
and is converted to an appropriate string.
- '$F'
-
Displays a file and line number; used for displaying the call
site. This specifier consumes two arguments, the file and line
number, in that order. See an example below.
- '$S'
-
The argument is treated as a format string, and is recursively
formatted using any following arguments. This specifier does
not support the use of the "precision" field for specifying
maximum string length.
The following are example uses of the %$F and %$S format specifiers.
In this call using %$F, the compiler recognizes these symbols and
fills in the file and line number.
System_printf("%$F", __FILE__, __LINE__);
This call outputs, for example,
Here is an example using %$S, passing a recursive format string.
System_printf("Msg: %$S", "My msg, code: %d", 5);
This outputs:
RETURNS
printf returns the number of characters printed.
System_processAtExit() // module-wide |
|
Processes all functions bound via System_atexit
Void System_processAtExit(Int stat);
ARGUMENTS
stat
exit status which will passed to all functions
processed.
DETAILS
This function is called by System_exit to process all functions
bound via System_atexit. User can add this to ANSI C standard
atexit function so that all functions bound via System_atexit are
processed when ANSI C standard exit function is called.
System_putch() // module-wide |
|
Output a single character
Void System_putch(Char ch);
ARGUMENTS
ch
character to be output.
DETAILS
The
SupportProxy's
putch function is called
by this function.
System_snprintf() // module-wide |
|
Write formated output to a character buffer
Int System_snprintf(Char buf[], SizeT n, CString fmt, ...);
ARGUMENTS
buf
a character output buffer
n
the maximum number of characters, including '\0', written to
the output buffer buf
fmt
a 'printf-style' format string
DETAILS
This function is identical to
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.
RETURNS
snprintf returns the number of characters that would have been
written had n been sufficiently large, not counting the terminating
'\0' character.
System_sprintf() // module-wide |
|
Write formated output to a character buffer
Int System_sprintf(Char buf[], CString fmt, ...);
ARGUMENTS
buf
a character output buffer
fmt
a 'printf-style' format string
DETAILS
This function is identical to
printf except that the
output is copied to the specified character buffer
buf followed
by a terminating '\0' character.
RETURNS
sprintf returns the number of characters output not including the
'\0' termination character.
System_vprintf() // module-wide |
|
A VaList printf
Int System_vprintf(CString fmt, VaList va);
ARGUMENTS
fmt
a standard 'printf-style' format string.
va
an args list that points to the arguments referenced
by the fmt string
DETAILS
This function is identical to
printf except that its
arguments are passed via a VaList (a "varargs list").
RETURNS
vprintf returns the number of characters output.
System_vsnprintf() // module-wide |
|
A VaList snprintf
Int System_vsnprintf(Char buf[], SizeT n, CString fmt, VaList va);
ARGUMENTS
buf
a character output buffer
n
at most number of characters including '\0' written to
output buffer
fmt
a standard 'printf-style' format string.
va
an arguments list that points to the arguments referenced
by the fmt string
DETAILS
This function is identical to
snprintf except that
its arguments are passed via a
VaList (a "varargs list").
RETURNS
vsnprintf returns the number of characters that would have been
written had n been sufficiently large, not counting the terminating
'\0' character.
System_vsprintf() // module-wide |
|
A VaList sprintf
Int System_vsprintf(Char buf[], CString fmt, VaList va);
ARGUMENTS
buf
a character output buffer
fmt
a standard 'printf-style' format string.
va
an arguments list that points to the arguments referenced
by the fmt string
DETAILS
This function is identical to
sprintf except that
its arguments are passed via a
VaList (a "varargs list").
RETURNS
vsprintf returns the number of characters output.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool System_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool System_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 System_Module_getMask();
// Returns the diagnostics mask for this module
Void System_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module