Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileTgettimeofday()Tsettimeofday()Ssystem() GEMDOSSyntaxLONG Ssystem( mode, arg1, arg2)
WORD mode;
LONG arg1;
LONG arg2;
Function Ssystem() is a multipurpose call controlling Cookie Jar,
memory access and various system settings.
Opcode 340 (0x0154)
Availability Available when a 'MiNT' cookie with a version of at least
1.15 exists.
Parametres arg1 and arg2 are long parameters specific for a particular
mode. If a mode doesn't use a parameter, it is usually
ignored, but should be set to a zero for future
compatibility. mode specifies a particular action as follows:
S_OSNAME 0x0000
Identifies the operating system type. Returned longword contains a
32-bit positive number, which interpreted as an ASCII string gives a
4-character id. For MiNT the returned value is 0x4d694e54 ('MiNT').
S_OSXNAME 0x0001
Identifies the subtype of the operating system. If this call returns a
zero or a negative value, that means, that no subtype is available.
Otherwise the returned value, when interpreted as an ASCII string
gives a 4-character subtype id. For FreeMiNT, being a derivative of
the MiNT, the returned value is 0x46726565 ('Free').
If a subtype id is less than 4 characters long, it should be padded
with zeros.
S_OSVERSION 0x0002
Identifies the exact operating system version. Returned longword
contains a 32 bit positive version number encoded as follows:
bits meaning
0- 7 some printable character to characterize the current version,
e.g. 0x61 (`a') if alpha release, 0x62 (`b') if beta release
For official releases you will always find a value of 0 here.
8-15 patchlevel (0x55 for pl 88)
16-23 minor version number (0x0e for x.14)
24-31 major version number ($01 for 1.xx)
Definition of an official release: every release for which in bits 0-7
a value of 0 is returned...
S_OSHEADER 0x0003
Allows to access the TOS header in order to get some information from.
Current implementation allows to access the first 256 longwords of the
header. The address of the required longword, relative to the begin
address of the TOS header, has to be specified as arg1. Only even
valuesare allowed (bit 0 of the arg1 is masked out by the kernel).
Always a whole longword is returned.
S_OSBUILDDATE 0x0004
Returns a 32 bit positive value with the build date encoded as follows:
bits meaning
0-15 binary year ($07dd for 1998)
16-23 binary month ($0c for the December)
24-31 binary day of the month
S_OSBUILDTIME 0x0005
Returns a 32 bit positive value with the build time encoded as follows:
bits meaning
0- 7 binary seconds
8-15 binary minutes
16-23 binary hours
24-31 day of week
day of week has 1 for Monday, 2 for Tuesday... 7 for Sunday.
S_OSCOMPILE 0x0006
Returns a 32-bit positive value specifying the primary CPU type the
kernel has been compiled for. Encoding:
bits meaning
0- 7 binary minor CPU ID
8-15 binary major CPU ID
16-31 reserved for future definition.
The major ID identifies a particular series of processors. Currently
only a value of $00 is efined and it is assigned to Motorola 68k
series. Other values of this field are reserved for future definition.
The minor CPU ID interpretation depends on the major ID. For 68k
series, values are as follows:
$00 68000 $0a 68010
$14 68020
$1e 68030 $28 68040
$3c 68060
This is not the same as the _CPUcookie value. The _CPUcookie specifies the CPU physically present in the machine, while the
S_OSCOMPILE indicates the processor type selected at the time when the
system was compiled. In other words, running a 68000 compiled kernel
will return a $00 here, even if the machine is running 68040 or
something.
S_OSFEATURES 0x0007
Returns a 32-bit positive value specifying the state of kernel
features. Encoding:
bits meaning
0 memory protection (1 = turned on)
1 virtual memory (1 = turned on)
2-31 reserved for future usage
This call has an informative purpose only and you cannot toggle
anything with it.
S_GETCOOKIE 0x0008
Fetches required information from the Cookie Jar.
1. If arg1 is a value bigger than 65535 (0xffff), it is interpreted as
a tag id. The Cookie Jar is searched for such a tag, then if the
tag is found, the corresponding slot value is returned or -1
otherwise.
2. If arg1 is a value between 1 and 65535, it is interpreted as a slot
number, not a tag id. Then the corresponding tag id is fetched and
returned or a value of -1 if the specified slot is free or does not
exist at all (a slot number past the end of the Cookie Jar was
specified). The first slot in the Cookie Jar is considered number 1.
3. If arg1 is equal to a zero, then the Cookie Jar is searched for the
NULL cookie, then the corresponding slot value is returned.
The place where the value fetched from the Cookie Jar will be returned
is defined by the arg2. If this is a zero, the call returns its values
in the GEMDOS return value (d0). If the arg2 is not a zero, it is
interpreted as a pointer to a memory location, where the slot tag or
its value should be written to. The return value is 0 (E_OK) then, if
everything went OK, or -1 otherwise.
This behaviour (where arg2 != NULL) is not implemented in MiNTversions below 1.14.8.
S_SETCOOKIE 0x0009
Places a tag id specified by the arg1 with the value of the arg2 in
the Cookie Jar. If a slot with the specified tag id already exists, it
will be replaced with the new value. NULL cookie is reallocated
automatically and its value is adjusted. If there are no more free
slots, no action is performed and ENSMEM is returned instead.
S_SETCOOKIE requires root euid, EACCDN is returned otherwise and no
action is performed.
The call refuses to place a cookie (a value of -1 is returned) whose
tag id contains a zero-byte.
S_GETLVAL 0x000a
Fetches and returns a longword from the address of supervisor area
specified as a 16-bit, even, unsigned integer value passed as arg1.
Bit 0 and bits 16-31 are masked out (ignored). The call returns a zero
if the value at the specified address has to be "hidden" from reading.
Currently the hidden values are the initial PC value and the initial
stack pointer value stored at $00000000 and $00000004 respectively.
Reading a hidden value may require root euid.
If the desired address is long word aligned, longwords can be also
retrieved from the supervisor area using Setexc().
S_GETWVAL 0x000b
Fetches and returns a word from the address of supervisor area
specified as a 16-bit, even, unsigned integer value passed as arg1.
Bit 0 and bits 16-31 are masked out (ignored). The call returns a zero
if the value at the specified address has to be "hidden" from reading.
Currently the hidden values are the initial PC value and the initial
stack pointer value stored at $00000000 and $00000004 respectively.
Reading a hidden value may require root euid.
S_GETBVAL 0x000c
Fetches and returns a byte from the address of supervisor area
specified as a 16-bit unsigned integer value passed as arg1. Bits
16-31 are masked out (ignored). The call returns a zero if the value
at the specified address has to be "hidden" from reading. Currently
the hidden values are the initial PC value and the initial stack
pointer value stored at $00000000 and $00000004 respectively. Reading
a hidden valuevalue may require root euid.
S_SETLVAL 0x000d
Places a longword value specified by arg2 at address specified as 16
bit integer by arg1. Bit 0 and bits 16-31 of the arg1 are masked out
(ignored). Since this call is designed to manipulate operating system
variables located within the supervisor area (first 32k), it is
restricted for root euid and returns EACCDN if called by an
unprivileged process.
S_SETWVAL 0x000e
Places a word value specified by arg2 at address specified as 16 bit
integer by arg1. Bit 0 and bits 16-31 of the arg1 are masked out
(ignored). Since this call is designed to manipulate operating system
variables located within the supervisor area (first 32k), it is
restricted for root euid and returns EACCDN if called by an
unprivileged process.
S_SETBVAL 0x000f
Places a byte value specified by arg2 at address specified as 16 bit
integer by arg1. Bits 16-31 of the arg1 are masked out (ignored).
Since this call is designed to manipulate operating system variables
located within the supervisor area (first 32k), it is restricted for
root euid and returns EACCDN if called by an unprivileged process.
S_SECLEVEL 0x0010
Resets the current security level to a value specified by arg1. Valid
levels are as follows:
0: none of hardware specific system calls are restricted. This is a
'MultiTOS compatibility' mode.
1: BIOS and XBIOS calls require root privileges; any call except
Supexec() and Super() returns EACCDN if called by an unprivileged
process.
2: as above, with except that Supexec() executing the user procedure
doesn't enter supervisor mode, and the Super(), if called without
root privileges, generates SIGSYS in order to kill the calling
process.
On values bigger than a 2, the EACCDN is returned. If arg1 is equal to
a -1, the current security level value is returned.
The call totally needs root privileges - user processes cannot even
inquire the current security level value.
S_RUNLEVEL 0x0011
Resets the current run level to a value specified by arg1. This mode
is restricted to euid root. If arg1 is equal to a -1, the current run
level value is returned.
No current version of MiNT understands the concept of run levels,
neither characteristics of run levels are defined. Thus the S_RUNLEVEL
mode should be considered reserved for future definition.
S_TSLICE 0x0012
Allows to set/interrogate the global timeslice value. Values are
exactly the same as for SLICES keyword in MINT.CNF. If arg1 is equal
to -1, the call returns the current global timeslice value.
Setting the timeslice requires root privileges.
S_FORCEFASTLOAD 0x0013
Allows to change the interpretation of the FASTLOAD bit in the program
header.
On Ssystem(S_FORCEFASTLOAD, 0L, 0L); the program header bit will be
used as before, this is actually equal to FASTLOAD=NO in MINT.CNF.
On Ssystem(S_FORCEFASTLOAD, 1L, 0L); the program header bit will be
ignored and fastload will be forced for all programs.
arg1 = -1 allows to interrogate the current state of this variable.
You need root privileges to toggle the FASTLOAD mode.
S_SYNCTIME 0x0014
Allows to interrogate or change the global filesystem sync time. The
default value is 5 sec.
If arg1 is a positive value, it is interpreted as a new sync time
value.
If arg1 is equal to -1, the current sync time value will be returned.
To be able to change the filesystem sync time you need root privileges
desperately.
S_CLOCKMODE 0x0064
S_CLOCKMODE called with an arg1 of -1 inquires the kernel's notion of
the hardware system clock. If the command returns a zero, the hardware clock is considered to tick in UTC; if it returns a positive non-zero
value, it is considered to tick in local time.
Any other positive value of the arg1 sets the current clock mode. On a
0 it is reset to UTC, or to local time otherwise.
Although this call will never really change the setting of the
hardware clock, due to the changed interpretation the clock seems to
warp; don't play around too much with it.
S_TIOCMGET 0x54f8
This mode is reserved for the internal and exclusive usage of the MiNT Library.
Binding move.l arg2,-(sp)
move.l arg1,-(sp)
move.w opcode,-(sp)
move.w #$0154,-(sp)
trap #1
lea $0c(sp),sp
Caveats Ssystem() was first introduced as of MiNT version 1.14.6,
but it is considered fully functional as of MiNT version
1.15.0 release.
The S_OSHEADER opcode should be only used for fetching the
TOS version number when running MiNTversions below 1.15.0
release.
You should never use Ssystem( S_TIOCMGET, ... ); in own
programs.
The Ssystem() behaviour does not depend on the S_SECLEVEL
settings.
Return Value Any values returned by the kernel on reserved fields
should be considered undocumented and no software should
rely on them.
Comments Its strictly encouraged to access GEMDOS variables and
system vectors via the Ssystem(), because this way is
considered safe for multiuser setups.
Prior to any further Ssystem() usage, your application
should first check if the kernel supports this call. If it
does, the Ssystem(-1, 0L, 0L); should return a zero.
Ssystem() is used and supported by the MiNT Library as of
patchlevel 48.
See Also Tgettimeofday(), Tsettimeofday()