Extended C functions
For some time the SharedCLibrary core (library chunk ID 2) has provided two additional functions over those documented in the PRMs. The _clib_version function, used to read the C library details, has been expanded to give more detail on the components that make up the library. This document provides a description of these functions.
All these functions use APCS-R or APCS-32 (dependent on linkage) calling conventions.
Language support functions
Entry number 180: const char *_clib_version(void);
This function returns a read-only string giving information on the C library. The string is composed of a number of newline delimited fields. Each field describes a component of the shared library, with the first field describing the overall features of the library.
The initial field will take the form :
"C library[<qualifiers>]" where <qualifiers> is a sequence of strings prefixed by a '/' character to indicate the facilities offered by the core library. The only defined qualifier at present is "/R" : /R Indicates that the format of the jmp_buf array is fixed to the logical APCS-A bindings of registers. That is, the format is : v4-v6, fp, sp, sl, lr, f4-f7
Subsequent fields within the returned string describe the component versions in the form :
"<component> vsn <version> (<date>)[<qualifiers>]"
The <version> is a 3 digit decimal number indicating the version number of that component.
Kernel The Run Time System Kernel which manages the environment used by the C library Core Core C library functions C99Low Low-level C functions (primarily variable length arrays, and 64bit operations) C99 High-level C functions (all other C99-specific features) RISC_OSLib Name allocated, but unused Shared C Library Indicates that the C library is part of the 'SharedCLibrary' module.
The prior definition of this function placed no meaning on the string returned, and did not declare that the returned string was const. This definition improves that description. Under earlier versions of the Shared C Library (and ANSILib), this function would return a string in the form :
"[Shared ]C Library vsn <version>/R \[<cppdate>\]\n"
where <cppdate> is a date as produced by the C pre-processor __DATE__ macro (MMM DD YYY). The new format retains a similar style to this earlier form and so should be machine-parseable by code which previously interpreted the string value. The new format remains printable, so should be usable for diagnostic purposes.
Variadic SWI call
Entry number 183 : int _swi(int swi_number, unsigned int flags, ...);
Entry number 184: _kernel_oserror *_swix(int swi_number, unsigned int mask, ...);
These functions provide a generic method of calling RISC OS SWIs from C or C++.
Two functions are provided:
_swi for calling SWIs without setting the X bit
swi_no is the number of the SWI to be called. This should never have the X bit set.
mask is a word containing an input and output register mask, a return register, and a block parameter register.
The arrangement of mask is as follows:
bits 0-9: Set if R(N) is passed to the SWI. bit 10: Unused. bit 11: Set if a local block parameter is to be passed to the SWI bits 12-15: Register number for local block parameter if bit 11 set. bits 16-19: Register number to be returned from a _swi call. This is only applicable to _swi as _swix always returns either 0 or an error pointer. bit 20: Unused. bit 21: Set if the PC (including the flags) is to be output. bits 22-31: Set if R(31-N) is output from the SWI (ie bit 31 corresponds to R0, bit 22 corresponds to R9).
If a register is specified as a return register (bits 16-19) it must not also be specified as an output register in the output register mask (bits 22-31).
If a register is specified as a local block parameter register it must not also be specified as an input register in the input register mask (bits 0-9).
If the PC is specified as a return register (ie bits 16-19 = 15) or as an output registers (bit 21 = 1) the value returned will contain the flags in bits 28 to 31 (28 = V, 29 = C, 30 = Z, 31 = N).
The remainder of the variadic arguments are as follows (in order):
If bit 11 is set the remainder of the arguments are placed in order in a parameter block and the address of the parameter block is passed to the SWI in the register specified by bits 12-15.
The macros are as follows:
_IN(n) - Specifies that R(n) is used on input _OUT(n) - Specifies that R(n) is output _BLOCK(n) - Specifies that R(n) is a block parameter _RETURN(n) - Specifies that R(n) is returned from _swi.
The values of the macros should be ORed together to produce the value for the mask.
The following constants are defined:
_FLAGS - the register containing the flags (currently 15) _C - mask for the C bit in _FLAGS _Z - mask for the Z bit in _FLAGS _N - mask for the N bit in _FLAGS
This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.
HTML document version 1.03 3rd November 2015