5.14 Systemfunktionen

• Salert	Warnung bzw. Fehlermeldung ausgeben.
• Sconfig	Betriebssystem-Konfiguration ermitteln/setzen.
• Scookie	Controlling Cookie Jar.
• Shutdown	Kills all processes, syncs filesystems then halts or reboots the system.
• Slbclose	Schließt eine Shared Library
• Slbopen	Öffnet eine Shared Library
• Srealloc	Bildschirmspeicher reservieren.
• Ssystem	Controlling Cookie Jar, memory access and various system settings.
• STEFcntrl	STEmulator Kontrollfunktionen
• Super	Supervisor-Modus ermitteln oder ändern.
• Suptime	Returns the current uptime and load averages from the system.
• Sversion	Versionsnummer von GEMDOS ermitteln.
• Syield	CPU für andere Prozesse freigeben.
• Sync	Synchronisation der gemounteten Dateisysteme.
• Sysconf	Betriebssystem-Konfiguration überprüfen.

Querverweis: Dateifunktionen Prozessfunktionen

5.14.1 Salert

Name:	»Salert« - Warnung bzw. Fehlermeldung ausgeben.
Gemdosnummer:	316
Deklaration:	void Salert ( int8_t *msg );
Beschreibung:	Die Funktion gibt eine Fehler- bzw. Warnmeldung aus, die in die Alert-Pipeline U:\PIPE\ALERT geschrieben wird. Die Meldung msg sollte keine Steuerzeichen, Linefeeds etc. enthalten. Sie sollte eine einfache einzeilige Warn- oder Fehlermeldung sein. Die Funktion formatiert die Meldung selbständig und sendet sie dem Benutzer. Die genaue Form des Outputs hängt jedoch von der verwendeten Systemkonfiguration ab.
Ergebnis:	Die Funktion hat kein direktes Ergebnis.
Verfügbar:	Verfügbar, wenn ein 'MiNT' Cookie mit einer Versionsnummer von mindestens 0.98 existiert.
Gruppe:	Systemfunktionen
Querverweis:	Binding Cconws Test auf Pipes

5.14.1.1 Bindings für Salert

C:	void Salert ( int8_t *msg );
Assembler:	pea msg ; Offset 2 move.w #316,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #6,sp ; Stack korrigieren

5.14.2 Sconfig

Name:

»Sconfig« - erlaubt die Konfigurierung von Teilen des Betriebssystems.

Gemdosnummer:

Deklaration:

int32_t Sconfig ( int16_t mode, int32_t flags );

Beschreibung:

Die Funktion erlaubt die Konfigurierung von Teilen des Betriebssystems. Es gilt:

Parameter

Bedeutung

mode

Aktion

0 =	Konfiguration ermitteln
1 =	Konfiguration setzen
2 =	Zeiger auf DOSVARS-Struktur ermitteln; seit KAOS 1.4.2 und MagiC
3 =	reserviert; MagiC 3.00
4 =	für WBDAEMON; MagiC 4.01
5 =	reserviert; MagiC 4.01
6 =	reserviert; MagiC 4.01

flags

Konfiguration als Bitvektor

Bit-0 =	Pfadüberprüfung ein
Bit-1 =	Einfügemodus für GEMDOS und Dialogboxen
Bit-2 =	reserviert
Bit-3 =	reserviert
Bit-4 =	Fastload für Diskette aus
Bit-5 =	TOS-Kompatibilität ein
Bit-6 =	Smart-Redraw aus
Bit-7 =	Grow-/Shrinkboxen aus
Bit-8 =	kein Halt nach TOS-Programmen
Bit-9 =	reserviert
Bit-10 =	Pulldown-Menüs
Bit-11 =	Floppy-Hintergrundbetrieb

Hinweis: Gesetzte Bits schalten die jeweilige Funktion ein, nicht gesetzte Bits schalten sie wieder aus.
Bit-11 steht erst ab MagiC 3.0 zur Verfügung. Das Setzen der Konfiguration ist nur bei abgeschalteter TOS-Kompatibilität möglich.

Die Funktion ist auch in KAOS vorhanden, allerings mit einer etwas anderen Belegung des Bitvektors. Als mode kennt KAOS 1.2 nur die ersten beiden Unterfunktionen.

Bit-0 =	Pfadüberprüfung ein
Bit-1 =	Diskwechsel-Simulation im Desktop ein
Bit-2 =	Break ein; CTRL-C Abfrage bei jedem DOS-Aufruf
Bit-3 =	CTRL-C Abfrage aus; für zeichenorientierte Funktionen
Bit-4 =	Fastload für Diskette aus
Bit-5 =	TOS-Kompatibilität ein (seit KAOS 1.4.2)
Bit-6 =	Smart-Redraw aus (seit KAOS 1.4.2)
Bit-7 =	Grow-/Shrinkboxen aus (seit KAOS 1.4.2)
Bit-8 =	kein Halt nach TOS-Programmen (seit KAOS 1.4.2)
Bit-9 =	MF2-Layout ein (seit KAOS 1.4.2)
Bit-10 =	Pulldown-Menüs (seit KAOS 1.4.2)
Bit-11..30 =	reserviert (seit KAOS 1.4.2)
Bit-31 =	muß unbedingt 0 sein, sonst Fehler! (seit KAOS 1.4.2)

Ergebnis:

Die Funktion liefert, in Abhängigkeit des Parameters mode, die aktuell gültige Konfiguration oder einen Zeiger auf eine DOSVARS-Struktur zurück.
Im Fehlerfall wird EINVFN oder EACCDN zurückgeben.

Verfügbar:

seit KAOS Version 1.2 und MagiC ab Version 1.0

Gruppe:

Systemfunktionen

Querverweis:

Binding Sysconf

5.14.2.1 Bindings für Sconfig

C:	int32_t Sconfig ( int16_t mode, int32_t flags );
Assembler:	move.l flags,-(sp) ; Offset 4 move.w mode,-(sp) ; Offset 2 move.w #51,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #8,sp ; Stack korrigieren

5.14.3 Scookie

Name:

»Scookie« - Cookie jar management.

Gemdosnummer:

330 (0x014a)

Deklaration:

int32_t Scookie ( int16_t action, COOKIE *cookie );

Beschreibung:

The function Scookie permits the management of the cookie jar. The following apply:

action	Meaning

C_BAKE (0x01)	cookie is a pointer to a cookie you want to install into the cookie jar. Only root can bake a cookie (or you get EACCDN), and you cannot overwrite an existing cookie (ELOCKED). Returns 0 for success, or a negative error code
C_GRAB (0x02)	cookie is a pointer to a cookie you want to grab from the cookie jar. You must supply a cookie with a tag name to look for. If you use a -1 (LONG) value for the cookie tag, then the first cookie will be returned to you. If the cookie is found, it will be copied into the cookie pointed to by cookie. Returns 0 for success or EFILNF. If you need direct access to the jar, pass -1L as your cookie pointer. This will return a pointer to the jar
C_MORE (0x04)	Like C_GRAB but find the NEXT cookie after the one with a tag like cookie's. This is so that you can find the entire jar with C_GRAB and C_MORE. The found cookie is copied into cookie. The NULL cookie is copied into cookie if cookie was the last cookie, or returns EFILNF if not found. Returns 0 for success (or last cookie)
C_READ (0x08)	cookie should be a LONG tag value to find, NOT a pointer! The returned value is the value of the cookie indicated, or EFILNF if not found. Use this when you know the cookie exists, such as "_MCH" since this is faster and easier.
C_SIZE (0x10)	Returns the number of cookies that are actually in the jar. Use C_READ,0 to find out how many cookies can be put in the jar without resizing
C_EAT (0x20)	cookie is the cookie to delete (only need tag value). Only root can eat cookies (or you get EACCDN). Returns EFILNF if cookie is not found or zero for success.

Ergebnis:

The return value depends on the parameter action
In case of invalid action value the function will return EINVFN.

Verfügbar:

This function is not available, use Ssystem() instead to manage cookies.

This function has been disabled as of FreeMiNT 1.12.4. Opcode 330 is now assigned to Dchroot().

Gruppe:

Systemfunktionen

Querverweis:

Binding Ssystem

5.14.3.1 Bindings für Scookie

C:	int32_t Scookie ( int16_t action, COOKIE *cookie );
Assembler:	pea cookie ; Offset 4 move.w action,-(sp) ; Offset 2 move.w #330,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #8,sp ; Stack korrigieren

5.14.4 Shutdown

Name:	»Shutdown« - kills all processes, syncs filesystems then halts or reboots the system.
Gemdosnummer:	337 (0x0151)
Deklaration:	int32_t Shutdown ( int32_t mode );
Beschreibung:	This function kills all processes, syncs filesystems then halts or reboots the system. On mode equal to SHUT_POWER (0L), the system will turn the power off. The only hardware that supports it at present is CT60 and the FireBee. If the hardware does not support it, SHUT_HALT will be performed. SHUT_POWER mode is recognized as of FreeMiNT version 1.16a; older versions of the kernel will treat the SHUT_POWER mode as SHUT_COLD. On mode equal to SHUT_BOOT (1L), the system will reboot the machine after shutting everything down. On mode equal to SHUT_COLD (2L), the system will act the same as with the SHUT_BOOT mode, except that a cold start rather than the warm start will be performed. SHUT_COLD mode is recognized as of FreeMiNT version 1.15.5, older versions of the kernel will treat the SHUT_COLD as SHUT_BOOT. On mode equal to SHUT_HALT (3L), the system will shut down, then enter a halted condition. All other values of mode are reserved for future definition. Older versions of MiNT contained a bug that might cause the system to crash, if you called Shutdown() while both GEM AES and virtual console daemon were present. You need root privileges to shut the system down.
Ergebnis:	Returns a negative GEMDOS error code, if failed. On success this call obviously never returns.
Verfügbar:	Seit der ersten in MultiTOS integrierten MiNT Version 1.04.
Gruppe:	Systemfunktionen
Querverweis:	Binding Sync

5.14.4.1 Bindings für Shutdown

C:	void Shutdown ( int32_t mode );
Assembler:	move.l mode,-(sp) ; Offset 2 move.w #337,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #6,sp ; Stack korrigieren

5.14.5 Slbclose

Name:	»Slbclose« - schließt eine "shared lib".
Gemdosnummer:	23 (0x017)
Deklaration:	int32_t Slbclose( SHARED_LIB *sl );
Beschreibung:	Die Funktion schließt eine Shared Lib Der Parameter sl ist der Deskriptor welcher bei Slbopen ermittelt wird. Seit MagiC 6: Ist sl=-1, dann werden alle Shared Lib geschlossen.
Ergebnis:	E_OK = Alles OK oder negative GEMDOS-Fehlernummer.
Verfügbar:	Sie steht ab MagiC 5.20 und FreeMiNT 1.15.4 zu Verfügung.
Gruppe:	Systemfunktionen
Querverweis:	Binding Slbopen Shared Libraries

5.14.5.1 Bindings für Slbclose

C:	int32_t Slbclose( SHARED_LIB *sl );
Assembler:	pea sl ; Offset 2 move.w #23,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #6,sp ; Stack korrigieren

5.14.6 Slbopen

Name:

»Slbopen« - Öffnet eine "shared lib"

Gemdosnummer:

22 (0x016)

Deklaration:

int32_t Slbopen( int8_t *name, int8_t *path, int32_t min_ver, SHARED_LIB *sl, SLB_EXEC *fn );

Beschreibung:

Die Funktion öffnet eine Shared Lib

Parameter	Bedeutung
name	Der Name der Bibliothek, in Großschrift, inkl. Extension (".SLB"). Der Bibliotheksname ist gleichzeitig Dateiname.
path	Pfad bei dem zuerst nach der Bibliothek gesucht (der Pfad muß in MagiC 5.20 mit '\' abgeschlossen sein; dies ist in MagiC 6 nicht mehr nötig). Wenn der Parameter NULL ist oder die Bibliothek im angegebenen Pfad nicht gefunden wurde, wird im XTENSION-Ordner gesucht. Ab MagiC 6 wird die Environment-Variable SLBPATH ausgewertet. Sie enthält wie PATH eine Liste der Suchpfade, jeweils durch ';' getrennt. Ist die Variable definiert, wird nicht mehr extra im XTENSION-Ordner gesucht. Bei FreeMiNT wird versucht die Bibliothek aus dem aktuellen Verzeichnis zu laden, falls path NULL ist.
min_ver	Minimal notwendige Versionsnummer der Bibliothek.
sl	Zeiger auf den Deskriptor.
fn	Zeiger auf den Funktionszeiger.

Ergebnis:

>= 0	Alles OK, Versionsnummer der Bibliothek.
ERANGE	Versionsnummer zu niedrig
EACCDN	Bibliothek schon von diesem Prozeß geöffnet
EFILNF	Bibliothek nicht gefunden
ENSMEM	zuwenig Speicher

Verfügbar:

Sie steht ab MagiC 5.20 und FreeMiNT 1.15.4 zu Verfügung.

Gruppe:

Systemfunktionen

Querverweis:

Binding Slbclose Shared Libraries

5.14.6.1 Bindings für Slbopen

C:	int32_t Slbopen( int8_t name, int8_t path, int32_t min_ver, SHARED_LIB sl, SLB_EXEC fn );
Assembler:	pea fn ; Offset 18 pea sl ; Offset 14 move.l minver,-(sp) ; Offset 10 pea path ; Offset 6 pea name ; Offset 2 move.w #22,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen lea 22(sp),sp ; Stack korrigieren

5.14.7 Srealloc

Name:	»Srealloc« - Bildschirmspeicher allozieren.
Gemdosnummer:	21
Deklaration:	int32_t Srealloc ( int32_t len );
Beschreibung:	Die GEMDOS-Routine Srealloc alloziert für den Bildschirmspeicher einen Bereich der Länge len Bytes. Der Bildschirmspeicher ist ein Block des ST-RAM, dessen Eigner der Bootprozeß ist. Die Adresse des Bildschirmspeichers (logbase oder physbase) wird von dieser Funktion nicht beeinflußt.
Ergebnis:	Die Funktion liefert (falls len den Wert -1 besitzt) die maximal mögliche Größe des Bildschirmspeichers zurück.
Verfügbar:	ab GEMDOS 0.30 (TOS 4).
Gruppe:	Systemfunktionen
Querverweis:	Binding

5.14.7.1 Bindings für Srealloc

C:	int32_t Srealloc ( int32_t len );
Assembler:	move.l len,-(sp) ; Offset 2 move.w #21,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #6,sp ; Stack korrigieren

5.14.8 Ssystem

Name:

»Ssystem« - controlling Cookie Jar, memory access and various system settings.

Gemdosnummer:

340 (0x0154)

Deklaration:

int32_t Ssystem ( int16_t mode, int32_t arg1, int32_t arg2 );

Beschreibung:

The Ssystem call has been designed to make your life easier. Using this you can get some closer control on the system and the kernel itself. Via this call the kernel now supports e.g. an easy Cookie Jar management and provides a safe access to supervisor memory. It's strictly encouraged to access GEMDOS variables and system vectors via the Ssystem(), because this way is considered safe for multiuser setups.

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:

mode

meaning

S_INQUIRE(0xffff)

Returns a zero if the kernel supports Ssystem. You can expect the function to be present if MiNT version at least 1.15 is detected.

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 (0x01 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 values are 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 (0x07dd for 1998)
16-23	binary month (0x0c 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.

The call should never return a zero in these bits, but if it does, it should be interpreted as 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. A value of $00 is assigned to the Motorola 68k series and since kernel version 1.19 a value of $01 is assigned to the ColdFire processors. 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:

0x00	68000
0x0a	68010
0x14	68020
0x1e	68030
0x28	68040
0x3c	68060

For the ColdFire series:

0x00	isa_a
0X01	isa_a+
0X02	isa_b
0X03	isa_c

This is not the same as the _CPU cookie value. The _CPU cookie 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 0x00 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.

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.
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.
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 MiNT versions 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 ENOMEM is returned instead.

S_SETCOOKIE requires root euid, EACCES 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 0x00000000 and 0x00000004 respectively. Reading a hidden value may require root euid.

If the desired address is LONGword 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 0x00000000 and 0x00000004 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 0x00000000 and 0x00000004 respectively. Reading a hidden value 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 to root euid and returns EACCES 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 EACCES 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 EACCES 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 EACCES if called by an unprivileged process. This does not apply to Setexc, which sends SIGSYS to the caller if a change of an exception vector was attempted.

2: as above, with except that Supexec and Super generates SIGSYS in order to kill the calling process.

On values bigger than 2, EACCES is returned. If arg1 is equal to -1, the current security level value is returned.

The call absolutely needs root privileges - user processes cannot even inquire the current security level value.

S_RUNLEVEL(0x0011)

Reserved for future definition.

S_TSLICE(0x0012)

Allows setting/interrogating 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_FASTLOAD(0x0013)

Allows changing the interpretation of the FASTLOAD bit in the program header.

On Ssystem(S_FASTLOAD, 0L, 0L); the program header bit will be used as before, this is actually equal to FASTLOAD=NO in mint.cnf.

On Ssystem(S_FASTLOAD, 1L, 0L); , the program header bit will be ignored and fastload will be forced for all programs.

arg1 = -1 allows interrogation of the current state of this variable.

You need root privileges to toggle the FASTLOAD mode.

S_SYNCTIME(0x0014)

Allows interrogation or changing the global file-system 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 file-system sync time you must have root privileges.

S_BLOCKCACHE(0x0015)

A positive value of arg1 ranging from 0 to 100 specifies the percentage of file-system cache to be filled with linear reads, as in the PERCENTAGE keyword in the mint.cnf file. A negative value of arg1 returns the currently set percentage value.

Root privileges are required to use this mode.

S_FLUSHCACHE(0x0016)

Invalidates CPU cache entries. arg1 is a pointer to the memory area whose cache entries should be invalidated, arg2 is the size of the area in bytes. Passing -1 as arg2 invalidates all cache entries. If the CPU features separate instruction and data caches, both are flushed.

This call automatically recognizes caches in 68020/030/040/060 and handles them as appropriate. The 68060 branch cache is automatically invalidated too. On 68000/68010 calling this mode has no effect. This mode is in fact just an interface to the MiNT function cpush used internally by the system.

Root privileges are NOT required to use this mode.

S_CTRLCACHE(0x0017)

Provides an universal (among 68k family members) way of controlling the CPU on-chip caches. arg1, referenced as Cache Control Word (CCW), is a bit-field where each bit enables (if 1) or disables (if 0) a particular function of CPU caches. arg2, referenced as Cache Control Mask (CCM), is a bit-mask where you define (by setting appropriate bits to 1) which bits of the Cache Control Word should be actually taken into account and written into the Cache Control Register (CACR). This is the control mode of the S_CTRLCACHE.

In inquire mode you can pass -1 as either argument. If the CCW is -1, the call returns a LONGword reflecting the actual state of the caches.

If the CCM is -1, a default bit-mask is returned, where any bit set indicates that a cache function defined by the same bit in the Cache Control Word is valid for the processor the MiNT is currently running on.

If both arguments are negative, the call simply returns E_OK if it is valid at all, or ENOSYS otherwise. This is the acknowledge mode of the S_CTRLCACHE.

Bits in either argument are defined as follows:

		020	030	040	060	CFv4e
0	Enable instruction cache	x	x	x	x	x
1	Enable data cache	-	x	x	x	x
2	Enable branch cache	-	-	-	x	x
3	Freeze instruction cache	x	x	-	-	-
4	Freeze data cache	-	x	-	-	-
5	Instruction burst enable	-	x	-	-	-
6	Data burst enable	-	x	-	-	-
7	Enable write allocate	-	x	-	-	-
8	Instruction cache full mode enable	-	-	-	x	-
9	Instruction cache read/write allocate	-	-	-	x	-
10	Data cache full mode enable	-	-	-	x	-
11	Data cache read/write allocate enable	-	-	-	x	-
12	Invalidate branch cache	-	-	-	x	x
13	Invalidate branch cache user entries	-	-	-	x	-
14	Enable CPUSH invalidate	-	-	-	x	x
15	Enable store buffer	-	-	-	x	x
16	Instruction cache invalidate all	-	-	-	-	x
17	Instruction cache mode default	-	-	-	-	x
18	Instruction cache half lock enable	-	-	-	-	x
19	CPUSH invalidate enable (instruction)	-	-	-	-	x
20	Default cache-inhibited fill buffer	-	-	-	-	x
21	Data cache invalidate all	-	-	-	-	x
22	Default data cache mode (bit 0)	-	-	-	-	x
23	Default data cache mode (bit 1)	-	-	-	-	x
24	Data cache half lock enable	-	-	-	-	x
25-31	Reserved for future definition

Note that no processor currently supports all of these functions and some (68000 and 68010) have no on-chip caches at all. To figure out what functions are valid for the actual CPU used, you should first request the default bit-mask using the inquire mode described above. Your program should save this mask, logically AND the arg2 with it, then pass the result as the Cache Control Mask for a control mode call.

Also note that the above bit definition does not exactly reflect the function and even position of actual bits in the physical Cache Control Register. The bits of either argument are arbitrarily assigned to particular cache functions, but their position and state are converted by the system before the Cache Control Register is written and after it is read, so that the user program can see always the same functions assigned to bits as above regardless of the physical configuration of the Cache Control Register.

Since changing cache configuration is global and may severely affect system performance, root privileges are needed to use S_CTRLCACHE control mode.

S_INITIALTPA(0x0018)

A positive non-zero value of arg1 defines the default amount of memory (in bytes) allocated for TPA space, as in the INITIALMEM keyword of the mint.cnf file. A negative value allows one to interrogate the value currently set. A value of 0 is illegal and will cause the call to fail and return EBADARG. Note that even if you define a very small value, like 1 or 2 bytes, the system will round this up to the smallest size of a memory block possible to allocate.

Root privileges are required to use this mode.

S_CTRLALTDEL(0x0019)

Reserved for future definition.

S_DELCOOKIE(0x001a)

Removes a tag ID specified by arg1 from the cookie jar. If there is no slot with the specified tag ID, no action is performed and EINVAL is returned instead.

S_DELCOOKIE requires root euid, EPERM is returned otherwise and no action is performed.

S_LOADKBD(0x001b)

Load the keyboard table into memory. arg1 specify the address of the complete path to the keyboard table or NULL. If path is NULL the default path of <sysdir>/keyboard.tbl is used. Returns a negative GEMDOS error-code if it fails. On success this call returns 0 and _AKP and _ISO cookies are updated.

S_LOADKBD requires root euid, EPERM is returned otherwise and no action is performed.

S_SETEXC(0x001c)

Allow Setexc(). Valid argc1 values are as follows:

Value	Meaning

-1	Return the current setting
0	Deny all (only kernel-processes may change sys-vectors)
1	Deny trap-changes (numbers 0-15)
2	Allow all (default)

Returns EBADARG if arg1 is greater than 2, or 0 on success.

S_SETEXC requires root euid, EPERM is returned otherwise and no action is performed.

S_GETBOOTLOG(0x001d)

Inquires the file path of bootlog file. arg1 and arg2 specify the address and length in bytes, respectively, of a memory buffer where a NULL-terminated ASCII string will be written identifying the full name of the bootlog file. If the memory buffer is not long enough to hold the entire string, the string is truncated down to the buffer size. Returns EBADARG if arg1 is null or if arg2 is 0. On success this call returns 0.

S_GETBOOTLOG requires root euid, EPERM is returned otherwise and no action is performed.

S_CLOCKUTC(0x0064)

S_CLOCKUTC 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 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_KNAME(0x0384)

arg1 and arg2 specify the address and length in bytes, respectively, of a memory buffer where a NULL-terminated ASCII string will be written identifying the full name and version of the system kernel. If the memory buffer is not long enough to hold the entire string, the string is truncated down to the buffer size.

S_CNAME(0x038e)

arg1 and arg2 specify the address and length in bytes, respectively, of a memory buffer where a NULL-terminated ASCII string will be written identifying the full name of the compiler used to compile the system kernel. If the memory buffer is not long enough to hold the entire string, the string is truncated down to the buffer size.

S_CVERSION(0x038f)

arg1 and arg2 specify the address and length in bytes, respectively, of a memory buffer where a NULL-terminated ASCII string will be written identifying the version of the compiler used to compile the system kernel. If the memory buffer is not long enough to hold the entire string, the string is truncated down to the buffer size.

S_CDEFINES(0x0390)

arg1 and arg2 specify the address and length in bytes, respectively, of a memory buffer where a NULL-terminated ASCII string will be written containing the compile time definitions (switches) used while compiling the system kernel. If the memory buffer is not long enough to hold the entire string, the string is truncated down to the buffer size.

S_COPTIM(0x0391)

arg1 and arg2 specify the address and length in bytes, respectively, of a memory buffer where a NULL-terminated ASCII string will be written containing the compile time optimization options used while compiling the system kernel. If the memory buffer is not long enough to hold the entire string, the string is truncated down to the buffer size.

S_DEBUGLEVEL(0x03e8)

S_DEBUGLEVEL called with an arg1 of -1 inquires the kernel's current debug level. Any other positive value will set the current debug level. If it is a zero, the kernel will not output any debugging information, except for fatal error-messages. The higher the debug level, the more MiNT will spew about what it is doing.

Note that special debug kernels will output more information than an ordinary distribution kernel.

Root privileges are needed to change the debug level.

S_DEBUGDEVICE(0x03e9)

S_DEBUGDEVICE called with an arg1 of -1 inquires the current BIOS device to output the debug information to. The order of defined BIOS devices is as follows:

0, printer
1, AUX:
2, console (default)
3, MIDI
4, keyboard
5, raw screen

Any positive value of arg1, ranging from 0 to 9, will redirect the debug information output to an appropriate BIOS device. Notice however, that setting device 4 (keyboard) as a debug device does not make much sense and may produce undesired results. The system does not restrict this in any way though, just assuming that you know what you're doing.

Root privileges are needed to change the debug device.

S_DEBUGKMTRACE(0x044c)

Dump out kmalloc'ed blocks with size and caller (debug kernel). arg1 specify the address of the kmalloc'ed block to check and arg2 specify the memory buffer where the dump will be written. Returns ENOENT if it fails. On success this call returns 0.

S_DEBUGKMTRACE requires root euid, EPERM is returned otherwise and no action is performed.

S_TIOCMGET(0x54f8)

This mode is reserved for the internal and exclusive usage of the MiNT Library.

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 MiNT versions below 1.15.0 release.

The S_FLUSHCACHE, S_CTRLCACHE, S_DEBUGLEVEL and S_DEBUGDEV are supported as of MiNT version 1.15.1 release.

You should never use Ssystem(S_TIOCMGET, ...); in your own programs.

The Ssystem behaviour does not depend on the S_SECLEVEL settings.

Any values returned by the kernel on reserved fields should be considered undocumented and no software should rely on them.

It's strictly encouraged to access GEMDOS variables and system vectors via the Ssystem, because this way is considered safe for multi-user setups. For example, you can access the cookie jar pointer using the call Ssystem(S_GETLVAL, 0x05a0, NULL), though if TOS-compatibility is the issue you should rather use (2, -1).

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.

Ergebnis:

Verfügbar:

Available when a 'MiNT' cookie with a version of at least 1.15 exists.

Gruppe:

Systemfunktionen

Querverweis:

Binding Tgettimeofday Tsettimeofday

5.14.8.1 Bindings für Ssystem

C:	int32_t Ssystem ( int16_t mode, int32_t arg1, int32_t arg2 );
Assembler:	move.l arg2,-(sp) ; Offset 8 move.l arg1,-(sp) ; Offset 4 move.w mode,-(sp) ; Offset 2 move.w #340,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen lea $0c(sp),sp ; Stack korrigieren

5.14.9 STEFcntrl

Name:	»STEFcntrl« - STEmulator Kontrollfunktionen
Gemdosnummer:	24000 (0x5DC0)
Deklaration:	int32_t STEFcntrl ( int16_t func, int32_t special1, int32_t special2 );
Beschreibung:	SET_INFOTEXT (1) special1 = (int8_t ) Zeiger auf neue Infozeile special2 = (int8_t ) Zeiger auf alte Infozeile Der String auf den special1 zeigt, wird als neue Infozeile in die Status-Zeile des STEmulator übernommen. Ein Wert von NULL schaltet wieder auf die Standard-Anzeige zurück. Wenn in special2 ein gültiger Zeiger auf einen Buffer übergeben wird, enthält dieser nach dem Funktionsaufruf den alten Text der Infozeile. Bei NULL, passiert nichts. SET_WINDOWTITLE (2) special1 = (int8_t ) Zeiger auf neue Titelzeile special2 = (int8_t ) Zeiger auf alte Titelzeile Der String auf den special1 zeigt, wird als neue Titel des STEmulator-Fenster übernommen. Wenn in special2 ein gültiger Zeiger auf einen Buffer übergeben wird, enthält dieser nach dem Funktionsaufruf den alten Fenstertitel. Bei NULL, passiert nichts.
Ergebnis:	EINVFN = Unbekannte Funktion ERANGE = ungültiger Parameter
Verfügbar:	STEmulator
Gruppe:	Systemfunktionen
Querverweis:	Binding

5.14.9.1 Bindings für STEFcntrl

C:	int32_t STEFcntrl ( int16_t func, int32_t special1, int32_t special2 );
Assembler:	move.l special2,-(sp) ; Offset 8 move.l special1,-(sp) ; Offset 4 move.w func,-(sp) ; Offset 2 move.w #24000,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen lea $0c(sp),sp ; Stack korrigieren

5.14.10 Super

Name:	»supervisor« - Supervisor-Modus umschalten.
Gemdosnummer:	32 (0x0020)
Deklaration:	int32_t Super ( void *stack );
Beschreibung:	Die GEMDOS-Routine Super schaltet zwischen User- und Supervisor-Modus um bzw. fragt den aktuellen Betriebsmodus ab. Die Adresse des Supervisor-Stacks kann beim Umschalten verändert werden. übergibt man für den Parameter stack den Wert 1, so wird der aktuelle Betriebsmodus erfragt. Der Wert 0 schaltet zwischen User und Supervisor-Modus um. Alle anderen Werten werden als neue Adresse für den Supervisor-Stack betrachtet. Im Supervisor-Modus kann auf alle geschützten Speicherstellen zugegriffen werden. Hinweis: Im Hinblick auf zukünftige Betriebssystemversionen sollten Sie den Einsatz der Super-Funktion vermeiden. Diese Funktion verursacht im Zusammenhang mit virtuellem Speicher und unterbrechbaren (und reentranten) Dateisystemen in einem Multitaskingsystem große Probleme. Stellen Sie ggf. Ihren Code so um, daß Sie die BIOS-Funktion Supexec verwenden können. Für MiNT gilt: If you are in SECURELEVEL > 1, you must have root privileges to get into supervisor mode. If you don't have them and call Super, the SIGSYS signal (12) will be raised.
Ergebnis:	Sollte der Zustand ermittelt werden, erhält man als Resultat 0 für den User- und -1 für den Supervisor-Modus. Ansonsten liefert die Funktion als Ergebnis die Adresse des alten Supervisor-Stacks, sofern in den Supervisor-Modus umgeschaltet wurde.
Verfügbar:	Alle GEMDOS Versionen
Gruppe:	Systemfunktionen
Querverweis:	Binding Supexec

5.14.10.1 Bindings für Super

C:	int32_t Super ( void *stack );
Assembler:	pea stack ; Offset 2 move.w #32,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #6,sp ; Stack korrigieren

5.14.10.2 Hinweis zur Verwendung der GEMDOS-Funktion Super

Die Funktion Super setzt bei der Umschaltung in den Supervisor-Modus den Super-Stackpointer auf den User-Stack des Programms. Das kann fatal sein, da das Programm nicht wissen kann, wie groß ein Super-Stackbereich sein muß. Ein zu kleiner Stack kann zu Fehlverhalten, Abstürzen o.ä. führen. Der Super-Stack liegt nicht mehr in einem möglicherweise durch Speicherschutzmechanismen gesicherten Bereich, kann also durch das Programm zerstört werden.

Ein Teil des User-Stacks könnte durch virtuelle Speichermechanismen ausgelagert worden sein. Ein ausgelagerter Super-Stack bedeutet Prozessorhalt, da der MC-680x0 Prozessor seine bei Exceptions übliche Sicherung des CPU-Status auf den Super-Stack nicht mehr durchführen kann und dann absichtlich stehenbleibt. Kein Anwendungsprogrammierer sollte es sich anmaßen, dem System irgendeine Beschränkung der Supervisor-Stackgröße aufzuerlegen.

Querverweis: GEMDOS Supexec

5.14.11 Suptime

Name:	»Suptime« - returns the current uptime and load averages from the system.
Gemdosnummer:	319 (0x013f)
Deklaration:	int32_t Suptime ( int32_t uptime, int32_t loadaverage );
Beschreibung:	This function returns the current uptime and load averages from the system. uptime is a pointer to a LONG value that will be filled with the current amount of seconds elapsed since last reboot. loadaverage is a pointer to a three longword array, that will be filled with the current load averages (for last 1, 5 and 15 minutes). The load average value is calculated using the following formula: sum += (new_load - old_load) * LOAD_SCALE; load_avg = sum / MAX_SIZE; where LOAD_SCALE is 2048, MAX_SIZE is the number of 5 second periods in the specified amount of time (12 for 1 min., 60 for 5 min. and 180 for 15 min). new_load is the number of currently running processes, old_load is the number of processes running previous time. A 'running' process is considered the one which is put onto run or ready queue.
Ergebnis:	Returns E_OK or a negative GEMDOS error code otherwise (actually it may be only ENOSYS if the call is not supported...).
Verfügbar:	Available when a 'MiNT' cookie with a version of at least 1.11 exists.
Gruppe:	Systemfunktionen
Querverweis:	Binding

5.14.11.1 Bindings für Suptime

C:	int32_t Suptime ( int32_t uptime, int32_t loadaverage );
Assembler:	pea loadaverage ; Offset 6 pea uptime ; Offset 4 move.w #48,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen lea $0a(sp),sp ; Stack korrigieren

5.14.12 Sversion

Name:

»operating system version« - ermittelt die Nummer der GEMDOS-Version.

Gemdosnummer:

Deklaration:

uint16_t Sversion ( void );

Beschreibung:

Die GEMDOS-Routine Sversion ermittelt die Versionsnummer des GEMDOS. Zur Zeit sind folgende Versionen bekannt:

Version	Erklärung
0.13	Findet sich in TOS 1.00 und 1.02. Diese Version zeichnet sich durch etliche Fehler aus, sollte daher nicht mehr benutzt werden.
0.14	Nummer des Turbo-DOS, welches für eine kurze Zeit von Atari mit Festplatten ausgeliefert wurde. Schnell, aber auch sehr unsicher. Auch KAOS 1.2.x besitzt diese Versionsnummer
0.15	Findet sich in TOS 1.04 und 1.06. Diese Version ist relativ schnell und stabil.
0.16	KAOS 1.4.x
0.17	Findet sich in TOS 1.62. Der Unterschied zur Version 0.15 liegt lediglich darin, daß das Patchprogramm POOLFIX3.PRG nicht mehr benötigt wird.
0.19	Findet sich in TOS 2.01, 2.05, 2.06, 3.01, 3.05, 3.06. Diese Version wurde im wesentlichen um Funktionen zur Verwaltung des Alternate-Memory erweitert, und wird auch von MagiC bis Version 6.10 angezeigt.
0.20	TOS 2.06 bis TOS 2.95 und TOS 3.06 haben die GEMDOS-Version 0.20. Einzige bislang bekannte Änderung: Medien mit nur einer FAT werden unterstützt. MagiC 6.20 gibt ebenfalls 0.20 zurück.
0.30	TOS 4.00 bis 4.04, auch MultiTOS 1.00 und 1.08.
0.31	Milan-TOS 4.05. Mxalloc() ignoriert Bit 2 bis 15 von mode.
0.32	Milan-TOS 4.08, Release 08.07.1999
0.33	Milan-TOS 4.08, Release 15.06.2001
0.40	FreeMiNT

Ergebnis:

Die Funktion liefert die genannte Versionsnummer, und zwar wie folgt:

Low-Byte :	Haupt-Versionsnummer
High-Byte :	Neben-Versionsnummer

Der Wert wird im BCD Format geliefert.

Verfügbar:

Alle GEMDOS Versionen

Gruppe:

Systemfunktionen

Querverweis:

Binding Sysconf TOS Liste

5.14.12.1 Bindings für Sversion

C:	uint16_t Sversion ( void );
Assembler:	move.w #48,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #2,sp ; Stack korrigieren

5.14.13 Syield

Name:	»Syield« - CPU für andere Prozesse freigeben.
Gemdosnummer:	255
Deklaration:	void Syield ( void );
Beschreibung:	Durch den Aufruf dieser Funktion, gibt ein Prozeß die CPU ab, so daß anderen Prozessen diese (möglicherweise früher als geplant) zugeteilt werden kann. Hinweis: Unter MagiC ruft diese Funktion direkt die AES-Routine appl_yield auf, und wird im Auto-Ordner ignoriert.
Ergebnis:	Die Funktion liefert kein Ergebnis.
Verfügbar:	Sie steht in MagiC ab Version 3.0 und wenn der MiNT Cookie vorhanden ist zur Verfügung.
Gruppe:	Systemfunktionen
Querverweis:	Binding Pause Fselect

5.14.13.1 Bindings für Syield

C:	void Syield ( void );
Assembler:	move.w #255,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #2,sp ; Stack korrigieren

5.14.14 Sync

Name:	»Sync« - synchronisiert alle gemounteten Dateisysteme.
Gemdosnummer:	336 (0x0150)
Deklaration:	void Sync ( void );
Beschreibung:	Die Funktion synchronisiert alle gemounteten Dateisysteme. Achtung: In MagiC wird diese Funktion mit Ssync bezeichnet.
Ergebnis:	Die Funktion liefert kein Ergebnis zurück.
Verfügbar:	MagiC ab Version 4.01 und seit der ersten in MultiTOS integrierten MiNT Version 1.04.
Gruppe:	Systemfunktionen
Querverweis:	Binding Shutdown

5.14.14.1 Bindings für Sync

C:	void Sync ( void );
Assembler:	move.w #336,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #2,sp ; Stack korrigieren

5.14.15 Sysconf

Name:

»Sysconf« - Informationen über die Konfiguration des Betriebssystems ermitteln.

Gemdosnummer:

290

Deklaration:

int32_t Sysconf ( int16_t n );

Beschreibung:

Die Funktion liefert Informationen über die Möglichkeiten (bzw. die Konfiguration) des Betriebssystems. Über den Parameter n lassen sich die verschiedenen Werte abfragen:

n	Bedeutung

-1	max. legaler Wert für n selbst.
0	max. Wert von Speicherbereichen pro Prozeß.
1	max. Länge der Kommandozeile für Pexec.
2	max. Anzahl offener Dateien pro Prozess.
3	max. Anzahl der Supplementary-Groups pro Prozess.
4	max. Anzahl der Prozesse je Benutzer.
5	HZ (CLK_TCK).
6	Größe einer Speicherseite.
7	verfügbare physikalische Seiten.
8	Größe des Passwort-Puffers.
9	Größe des Gruppe-Puffers.

Ein Rückgabewert von 0x7fffffff (2^31 - 1) bedeutet, daß der entsprechende Wert unbegrenzt ist.
Achtung: MagiC gibt -1 für unbegrenzte Werte zurück.

Ergebnis:

Die Funktion liefert die durch den Parameter n spezifizierte Information zurück.

Verfügbar:

Seit der ersten in MultiTOS integrierten MiNT Version 1.04.

Gruppe:

Systemfunktionen

Querverweis:

Binding Dpathconf

5.14.15.1 Bindings für Sysconf

C:	int32_t Sysconf ( int16_t n );
Assembler:	move.w n,-(sp) ; Offset 2 move.w #290,-(sp) ; Offset 0 trap #1 ; GEMDOS aufrufen addq.l #4,sp ; Stack korrigieren

GEMDOS

Netzwerkfunktionen

Verzeichnisfunktionen