Extended C functions

_clib_version (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:

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.
• The <date> is a standard RISC OS date string ("DD MMM YYYY") giving the date of this version of the component.
• The <qualifiers> are formed in a similar manner to the overall features but the qualifiers should be interpreted on a component-specific basis. No qualifiers have been defined for any of the components.

The current component names which may be used to construct the C library are:

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.

_swi (entry number 183) and _swix (entry number 184)

int _swi(int swi_number, unsigned int flags, ...);

_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
• _swix which sets the X bit before calling the SWI.

swi_number is the number of the SWI to be called. This should never have the X bit set.

mask (the flags argument of _swi) is a word containing an input and output register mask, a return register, and a block parameter register.

The arrangement of the mask is as follows:

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 register (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):

• The word value of each input register in order from 0 to 9 as specified by bits 0 to 9 of the mask.
• The address of a word to be written for each output register in order from 0 to 9 as specified by bits 31 downto 22 of the mask.
• The address of a word to be written with the PC value on exit from the SWI if bit 21 of the register mask is set.

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:

The values of the macros should be ORed together to produce the value for the mask.

The following constants are defined: