HomeGEMDOSNetwork functionsDirectory functions

5.14 System functions

Salert    Outputs alerts or error-messages.
Sconfig   Obtains/Sets operating system configuration.
Shutdown  Kills all processes, syncs file-systems then halts or reboots the system.
Slbclose  Closes a shared library
Slbopen   Opens a shared library.
Srealloc  Allocates screen memory.
Ssync     Synchronises all mounted file-systems.
Ssystem   Controls cookie jar, memory access and various system settings.
STEFcntrl STEmulator control functions.
Super     Obtains or alters supervisor-mode.
Suptime   Obtains the current uptime and load averages for the system.
Sversion  Obtains the version number of GEMDOS.
Syield    Releases CPU for other processes.
Sysconf   Checks operating system configuration.

See also: File functions   Process functions

5.14.1 Salert

Name: »Salert« - Output alert or error-message.
Opcode: 316
Syntax: void Salert ( int8_t *msg );
Description: The function Salert outputs an alert or error-message that is written to the alert pipeline U:\PIPE\ALERT.

The message msg should not contain any escape or control characters, linefeeds etc. It should be a simple one-line NULL-terminated character string alert- or error-message.

The function formats the message itself and sends it to the user. The exact format of the output however depends on the system configuration in use.
Return value: The function has no direct result.
Availability: Available when a 'MiNT' cookie with a version of at least 0.98 exists.
Group: System functions
See also: Binding   Cconws   Test for pipes

5.14.1.1 Bindings for Salert

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

5.14.2 Sconfig

Name: »Sconfig« - Configuration of parts of the operating system.
Opcode: 51
Syntax: int32_t Sconfig ( int16_t mode, int32_t flags );
Description: The function Sconfig permits the configuration of parts of the operating system. The following apply:
Parameter Meaning
   
mode Action
0 = Obtain configuration
1 = Set configuration
2 = Get pointer to DOSVARS structure
3 = Reserved; MagiC 3.00
4 = For WBDAEMON; MagiC 4.01
5 = Reserved; MagiC 4.01
6 = Reserved; MagiC 4.01
flags Configuration as bit-vector:
Bit-0 = Path-checking on
Bit-1 = Insert mode for GEMDOS and dialog boxes
Bit-2 = Reserved
Bit-3 = Reserved
Bit-4 = Fastload for diskette off
Bit-5 = TOS-compatibility on
Bit-6 = Smart redraw off
Bit-7 = Grow-/Shrinkboxes off
Bit-8 = No pause after TOS programs
Bit-9 = Reserved
Bit-10 = Pulldown menus
Bit-11 = Floppy background operation


Note: Set bits switch the relevant function on, cleared bits switch in off again.(!nl) Bit 11 is only available as of MagiC 3.0. The setting of the configuration is only possible with TOS-compatibility switched off.

The function is also present in KAOS, though with a somewhat different assignment of the bit-vector. For mode, KAOS 1.2 only knows the first two subfunctions.
Bit-0 = Path-checking on
Bit-1 = Disk change simulation in desktop on
Bit-2 = Break on; CTRL-C interrogation at every DOS call
Bit-3 = CTRL-C interrogation off; for character-oriented functions
Bit-4 = Fastload for diskette off
Bit-5 = TOS-compatibility on (as of KAOS 1.4.2)
Bit-6 = Smart redraw off (as of KAOS 1.4.2)
Bit-7 = Grow-/shrinkboxes off (as of KAOS 1.4.2)
Bit-8 = No pause after TOS programs (as of KAOS 1.4.2)
Bit-9 = Reserved (as of KAOS 1.4.2)
Bit-10 = Pulldown menus (as of KAOS 1.4.2)
Bit-11..30 = Reserved (as of KAOS 1.4.2)
Bit-31 = Has to be 0, else error! (as of KAOS 1.4.2)
Return value: The function returns, depending on the parameter mode, the currently valid configuration or a pointer to a DOSVARS structure.
Availability: As of KAOS Version 1.2, and MagiC Version 1.0.
Group: System functions
See also: Binding   Sysconf

5.14.2.1 Bindings for 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
addq.l    #8,sp        ; Correct stack

5.14.3 Shutdown

Name: »Shutdown« - Kill all processes, sync file-systems then halt or reboot the system.
Opcode: 337 (0x0151)
Syntax: void Shutdown ( int32_t mode );
Description: The function Shutdown kills all processes, syncs file-systems then halts or reboots the system.

On mode equal to SHUT_HALT (0L), the system will shut down, then enter a halted condition.

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 mode as SHUT_BOOT.

On mode equal to SHUT_POWER (3L), the system will turn the power off. The only hardware that supports it at present is CT60. 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.

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.
Return value: Returns a negative GEMDOS error-code if it fails. On success this call obviously never returns.
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
Group: System functions
See also: Binding   Sync

5.14.3.1 Bindings for Shutdown

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

5.14.4 Slbclose

Name: »Slbclose« - Close a shared library
Opcode: 23 (0x017)
Syntax: int32_t Slbclose( SHARED_LIB *sl );
Description: The function Slbclose closes a shared library.

The parameter sl is the descriptor that is obtained with Slbclose.
Return value: E_OK = All OK, version number of the library, else a negative GEMDOS error-number.
Availability: As of MagiC 5.20 and FreeMiNT 1.15.4.
Group: System functions
See also: Binding   Slbopen   Shared libraries

5.14.4.1 Bindings for Slbclose

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

5.14.5 Slbopen

Name: »Slbopen« - Open a shared library
Opcode: 22 (0x016)
Syntax: int32_t Slbopen( int8_t *name, int8_t *path, int32_t min_ver, SHARED_LIB *sl, SLB_EXEC *fn );
Description: The function Slbopen opens a shared library.
Parameter Meaning
name The name of the library, in capitals, incl. extension (".SLB"). The library name is the filename as well.
path Path where the library is first looked for (the path must be terminated in MagiC 5.20 with '\'; this is no longer necessary in MagiC 6). If the parameter is NULL, or the library was not found in the specified bath, then it will be looked for in the XTENSION folder.(!nl) From MagiC 6 onwards the environmental variable SLBPATH will be evaluated. As in PATH, it contains a list of the search paths, each separated by ';'. If the variable is defined, then no extra search will be made in the XTENSION folder.

With FreeMiNT an attempt will be made to load the library from the current directory if path is NULL.
min_ver Lowest required version number of the library
sl Pointer to the descriptor
fn Pointer to the function pointer
Return value:
>= 0 All OK, version number of the library
ERANGE Version number too low
EACCDN Library already opened by the process
EFILNF Library not found
ENSMEM Insufficient memory available
Availability: As of MagiC 5.20 and FreeMiNT 1.15.4.
Group: System functions
See also: Binding   Slbclose   Shared libraries

5.14.5.1 Bindings for 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
addq.l    #22,sp       ; Correct stack

5.14.6 Srealloc

Name: »Srealloc« - Allocate screen memory.
Opcode: 21
Syntax: int32_t Srealloc ( int32_t len );
Description: The GEMDOS routine Srealloc allocates a block of length len bytes for the screen memory.

The screen memory is a block of the ST-RAM whose owner is the boot process. The address of the screen memory (logbase or physbase) is not affected by this function.
Return value: The function returns (if len has the value -1) the maximum possible size of the screen memory.
Availability: As of GEMDOS 0.30 (TOS 4).
Group: System functions
See also: Binding

5.14.6.1 Bindings for Srealloc

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

5.14.7 Ssync

Name: »Ssync« - Synchronise all mounted file-systems.
Opcode: 336 (0x0150)
Syntax: void Ssync ( void );
Description: The function Ssync synchronises all mounted file-systems.

Warning: In MiNT this function is designated as Sync.
Return value: The function does not return a result.
Availability: MagiC as of Version 4.01, and under all MiNT versions integrated with MultiTOS.
Group: System functions
See also: Binding   Shutdown

5.14.7.1 Bindings for Ssync

C: void Ssync ( void );
Assembler:
move.w    #336,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.14.8 Ssystem

Name: »Ssystem« - Control cookie jar, memory access and various system settings.
Opcode: 340 (0x0154)
Syntax: int32_t Ssystem ( int16_t mode, int32_t arg1, int32_t arg2 );
Description: The Ssystem call has been designed to make your life easier. Using this you can get some closer control of 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 multi-user setups.

arg1 and arg2 are LONG parameters specific to a particular mode. If a mode doesn't use a parameter, it is usually ignored, but should be set to 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 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 a value of 0 is returned in bits 0-7...
S_OSHEADER(0x0003) Allows accessing the @{TOS ignore} header so as to get some information from it. Current implementation permits access to the first 256 LONGwords of the header. The address of the required LONGword, relative to the start address of the TOS header, has to be specified as arg1. Only even values are allowed (bit 0 of the @{I}arg1@{0} is masked out by the kernel). A whole LONGword is returned always.
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 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. Currently only a value of $00 is defined 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:

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


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.

  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 zero, then the cookie jar is searched for the NULL cookie, and the corresponding slot value is returned.



The place where the value fetched from the cookie jar will be returned is defined by arg2. If this is a zero, the call returns its values in the GEMDOS return value (d0). If 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) 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 arg1 with the value of 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_FORCEFASTLOAD(0x0013) Allows changing 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 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:
0 Enable instruction cache
1 Enable data cache
2 Enable branch cache
3 Freeze instruction cache
4 Freeze data cache
5 Instruction burst enable
6 Data burst enable
7 Enable write allocate
8 Instruction cache full mode enable
9 Instruction cache read/write allocate enable
10 Data cache full mode enable
11 Data cache read/write allocate enable
12 Invalidate branch cache
13 Invalidate branch cache user entries
14 Enable CPUSH invalidate
15 Enable store buffer
16-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_CAD(0x0019) Reserved for future definition.
S_CLOCKMODE(0x0064) 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 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_DEBUGDEV(0x03e9) S_DEBUGDEV 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_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.
Return value:
Availability: Available when a 'MiNT' cookie with a version of at least 1.15 exists.
Group: System functions
See also: Binding   Tgettimeofday   Tsettimeofday

5.14.8.1 Bindings for 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
lea       $0c(sp),sp   ; Correct stack

5.14.9 STEFcntrl

Name: »STEFcntrl« - STEmulator nolink [control functions]).
Opcode: 24000 (0x5DC0)
Syntax: int32_t STEFcntrl ( int16_t func, int32_t special1, int32_t special2 );
Description:

SET_INFOTEXT (1)
special1 = (int8_t *) Pointer to new info-line
special2 = (int8_t *) Pointer to old info-line

The string pointed to be special1 will be adopted as the new info-line in the status-line of the STEmulator. A value of NULL switches back to the standard display again.

If a valid pointer to a buffer is passed in special2, this will contain the old text of the info-line after the function call. With NULL, nothing happens.

SET_WINDOWTITLE (2)
special1 = (int8_t *) Pointer to new title-line
special2 = (int8_t *) Pointer to old title-line

The string pointed to by special1 will be adopted as the new title-line of the STEmulator window.

If a valid pointer to a buffer is passed in special2, this will contain the old text of the window title after the function call. With NULL, nothing happens.
Return value: EINVFN = Unknown function.
ERANGE = Invalid parameter.
Availability: STEmulator
Group: System functions
See also: Binding

5.14.9.1 Bindings for 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
lea       $0c(sp),sp       ; Correct stack

5.14.10 Super

Name: »supervisor« - Switch supervisor-mode.
Opcode: 32 (0x0020)
Syntax: int32_t Super ( void *stack );
Description: The GEMDOS routine Super switches between user- and supervisor-mode, or interrogates the current operating

The address of the supervisor stack may be altered during switching. If one passes the value 1 for the parameter stack, then the current mode will be interrogated. The value 0 switches between user- and supervisor-mode. All other values will be regarded as the new address for the supervisor stack. In the supervisor-mode one can access all protected memory blocks.

Note: With regard to future operating system versions, you should avoid use of the Super function. This function gives rise to major problems in conjunction with virtual memory and interruptible (and re-entrant) file-systems in a multitasking system. If neccesary, alter your code so that you can use the BIOS function Supexec.

For MiNT the following applies:
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.
Return value: If the state is to be obtained, one gets the value 0 for the user-mode and -1 for the supervisor-mode. Else the function returns the address of the old supervisor stack, provided one had switched to the supervisor-mode.
Availability: All GEMDOS versions.
Group: System functions
See also: Binding   Supexec

5.14.10.1 Bindings for Super

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

5.14.10.2 Note for the use of the GEMDOS function Super

The function Super in switching to the supervisor-mode sets the Super stack pointer to the user-stack of the program. This can be fatal, as the program can not know how large a super stack block has to be. Too small a stack can lead to faulty behaviour, crashes or similar. The super stack no longer lies in a block that is possibly protected by memory protection mechanisms, so it can be destroyed by the program.

A part of the user stack could have been laid-off by virtual memory mechanisms. A laid-off super stack as seen from the processor means that the MC-680x0 processor can no longer save its CPU status to the super stack as usual for exceptions, and then stop intentionally. No applications programmer should be so arrogant as to burden the system with any kind of restriction to the supervisor stack size.

See also: GEMDOS   Supexec

5.14.11 Suptime

Name: »Suptime« - Return the current uptime and load averages from the system.
Opcode: 319 (0x013f)
Syntax: int32_t Suptime ( int32_t *uptime, int32_t *loadaverage );
Description: The function Suptime 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 the last reboot.

loadaverage is a pointer to a three LONGword array, that will be filled with the current load averages (for the 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.
Return value: Returns E_OK if successful, or a negative GEMDOS error-code otherwise (actually it may be only ENOSYS if the call is not supported...).
Availability: Available when a 'MiNT' cookie with a version of at least 1.11 exists.
Group: System functions
See also: Binding

5.14.11.1 Bindings for 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
lea       $0a(sp),sp   ; Correct stack

5.14.12 Sversion

Name: »Operating system version« - Obtain the number of the current GEMDOS version.
Opcode: 48
Syntax: uint16_t Sversion ( void );
Description: The GEMDOS routine Sversion obtains the version number of the GEMDOS. At the present time, the following versions are known:
Version Explanation
0.13 Found in TOS 1.00 and 1.02. This version distinguishes itself with several errors, so should not be used any more.
0.14 Number of the Turbo-DOS, which was issued for a short time by Atari with hard drives. Fast, but also very unsafe. KAOS 1.2.x also has this version number.
0.15 Found in TOS 1.04 and 1.06. This version is relatively fast and stable.
0.16 KAOS 1.4.x
0.17 Found in TOS 1.62. The difference from version 0.15 lies only in the fact that the patch program POOLFIX3.PRG is no longer required.
0.19 Normally found in TOS 2.01, 2.05, 2.06, 3.01, 3.05, 3.06. This version was mainly extended by functions for managing alternate memory, and is also reported by MagiC up to Version 6.10.
0.20 TOS 2.06 up to 2.95 and TOS 3.06 have the GEMDOS version 0.20. Only change known so far: Media with only one FAT are supported.)
MagiC 6.20 returns also 0.20.
0.30 TOS 4.00 bis 4.04, also MultiTOS 1.00 and 1.08.
0.31 Milan-TOS 4.05. Mxalloc ignores bit 2 to 15 of mode.
0.32 Milan-TOS 4.08, Release 08.07.1999
0.33 Milan-TOS 4.08, Release 15.06.2001
0.40 FreeMiNT
Return value: The function returns the named version number, in the following manner:
Low byte : Main version number
High byte : Minor version number


The value is BCD coded.
Availability: All GEMDOS versions.
Group: System functions
See also: Binding   Sysconf   TOS list

5.14.12.1 Bindings for Sversion

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

5.14.13 Syield

Name: »Syield« - Release CPU for other processes.
Opcode: 255
Syntax: void Syield ( void );
Description: By calling the Syield function a process releases the CPU, so that it can be allocated to other processes (possibly earlier than planned).

Note: Under MagiC this function directly calls the AES routine appl_yield, and will be ignored in the Auto folder.
Return value: The function does not return a result.
Availability: In MagiC as of Version 3.0, and when the MiNT cookie is present.
Group: System functions
See also: Binding   Pause   Fselect

5.14.13.1 Bindings for Syield

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

5.14.14 Sysconf

Name: »Sysconf« - Obtain information about the operating system configuration.
Opcode: 290
Syntax: int32_t Sysconf ( int16_t n );
Description: The function Sysconf returns information about the capabilities (or the configuration) of the operating system. With the parameter n various values can be interrogated:
n Meaning
   
-1 Max. legal value for n itself
 0 Max. value of memory regions per process
 1 Max. length of command line string for Pexec
 2 Max. number of open files per process
 3 Max. number of supplementary groups per process
 4 Max. number pf processes per user


A return value of 0xfffffff (2^31 - 1) means that the corresponding value is unlimited.
Return value: Return value: The function returns the information specified by the parameter n.
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
Group: System functions
See also: Binding   Dpathconf

5.14.14.1 Bindings for Sysconf

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

HomeGEMDOSNetwork functionsDirectory functions