System X trap instruction has three fixed arguments and in addition up to four arguments supplied using the arg instruction. The first three arguments are bytes that define the kernel trap to be called and the rest are arguments to that trap function passed in registers ax, bx, cx and dx. If the trap function returns a value it is returned in the ax register. If the trap fails, the ax register will contain value -1 otherwise the return value will be nonnegative.
Currently the first and the third byte arguments have zero value and the second argument value determine the virtual operating system function to be called.
| trap | second byte value | arguments | description |
|---|---|---|---|
| trap_exit | 0 | exit code (byte) | exits a process |
| trap_memory_page_size | 1 | - | returns the size of memory page in bytes (ulong) |
| trap_heap_start | 2 | - | returns the starting address of the heap (ulong) |
| trap_heap_length | 3 | - | returns the current size of the heap in bytes (ulong) |
| trap_allocate_memory_pages | 4 | number of pages to allocate (int) | allocates given number of memory pages from the heap and returns the number of bytes allocated (ulong) |
| trap_dump_heap | 5 | - | writes information about the heap contents to the standard output |
| trap_random_seed | 6 | - | returns a randomly chosen seed value, it will be truely random if the hardware supports it (uint) |
| trap_current_time_point | 7 | - | returns the number of nanoseconds elapsed since epoch (ulong) |
| trap_sleep | 8 | duration in nanoseconds (long) | puts the calling process to sleep for the given duration, the duration the process will actually sleep will be accurate only about in hundreds of milliseconds |
| trap_current_date | 9 | address of year variable (pointer to short), address of month variable (pointer to sbyte), address of day variable (pointer to sbyte) | obtains current date |
| trap_current_date_time | 10 | address of year variable (pointer to short), address of month variable (pointer to sbyte), address of day variable (a pointer to sbyte), address of seconds variable (pointer to int) | obtains current date and time |
| trap_times | 11 | address of variable containing user time in nanoseconds (pointer to ulong), address of variable containing sleep time in nanoseconds (pointer to ulong), address of variable containing kernel time in nanoseconds (pointer to ulong) | obtains process times |
| trap_pow | 12 | x (double), y (double) | returns exponentiation x to the power of y (double) |
| trap_throw | 13 | address of exception (pointer), class ID of exception (ulong) | throws an exception |
| trap_catch | 14 | - | returns the address of the currently thrown exception |
| trap_resume | 15 | - | continues exception dispatch after a cleanup, or in case of rethrow |
| trap_stack_trace | 16 | address of string buffer (pointer to string), size of the string buffer (long) | obtains a stack trace |
| trap_get_system_error | 17 | address of the error code (pointer to int), address to string buffer for error message (pointer to string buffer), size of the string buffer (long) | obtains latest occurred kernel error when a kernel trap has returned -1 |
| trap_fork | 18 | - | forks a child process, returns the PID of the child to the parent and 0 to the child |
| trap_exec | 19 | address of file path to execute (pointer to string), address of argument array (pointer), address environment array (pointer) | executes a program within context of the current process, does not return if no error, otherwise returns -1 |
| trap_wait | 20 | address of child exit code (pointer to byte) | waits one child process to exit (the called process is put to sleep), returns the PID of the child exited or -1 in case of error and when there are no more child processes to wait (system error code will be ENOCHILD in that case) |
| trap_getpid | 21 | - | returns the nonnegative process id of the calling process, or -1 if an error occurred |
| trap_create | 22 | address of file path to create (pointer to string), mode (int) | creates a file, returns a nonnegative file descriptor (int), or -1 in case of error, has the same effect as calling trap_open with flags OpenFlags.create | OpenFlags.truncate | OpenFlags.write |
| trap_open | 23 | address of file path to open (pointer to string), flags (int): 1 << 0 = read, 1 << 1 = write, 1 << 2 = create, 1 << 3 = append, 1 << 4 = truncate, 1 << 5 = text, 1 << 6 = random_access, mode (int) | opens a file, returns a nonnegative file descriptor (int), or -1 in case of error |
| trap_close | 24 | a file descriptor to close (int) | closes a file, returns 0, or -1 in case of error |
| trap_read | 25 | a file descriptor (int), address of a buffer (ulong), maximum number of bytes to read (long) | reads the contents of the file, returns the number of bytes actually read, or -1 in case of error |
| trap_write | 26 | a file descriptor (int), address of a buffer (ulong), maximum number of bytes to write (long) | writes to a file, returns the number of bytes actually written, or -1 in case of error |
| trap_ioctl | 27 | a file descriptor (int), an item ID (int), argument pointer (pointer to byte), argument size ( | performs I/O-control function or returns information about a file: IOControlItem.isConsole=0, returns 1 if file is a console, 0 if file is not a console, -1 if error; IOControlItem.isHostTextFile=1, returns 1 if file is is host text file, 0 if file is not a host text file, -1 if error; IOControlItem.hasColors=2, returns 1 if file has colors, 0 if file does not have colors, -1 if error; IOControlItem.columns=3, returns the number of screen columns, 0 if file has no screen columns, -1 if error; IOControlItem.rows=4, returns the number of screen rows, 0 if file has no screen rows, -1 if error; IOControlItem.cursor_x=5, returns the x-coordinate of the cursor location; IOControlItem.cursor_y=6, returns the y-coordinate of the cursor location; IOControlItem.set_cursor_pos=7, sets the cursor location, argument must point to two ints; IOControlItem.set_cooked=8, sets the terminal to the cooked mode (default); IOControlItem.set_raw=9, sets the terminal to the raw mode; IOControlItem.set_echo=10, sets terminal echo on/off, argument must point to a byte with value (1 = on, or 0 = off); IOControlItem.push_lines=11, push terminal line history; IOControlItem.pop_lines=12, pop terminal line history |
| trap_unlink | 28 | address of a file or directory path (pointer to a string) | decrements the link count of a file or a directory; if the link count drops to zero, deletes the file or directory and frees the blocks the file or directory has occupied, returns 0, or -1 in case of error |
| trap_seek | 29 | a file descriptor (int), offset (long), whence (int): 0=seekSet, 1=seekCur, 2=seekEnd | sets the file position of the given file, the next read or write operation will start in that file position, returns the current file position after it has been set |
| trap_tell | 30 | a file descriptor (int) | returns the current file position of the given file, or -1 in case of error |
| trap_stat | 31 | path address of a file or directory (pointer to string), stat buffer address (pointer), stat buffer size (int), stat buffer size must be at least 68 | obtains information about a file or a directory, returns 0, or -1 in case of error, system error code will be ENOTFOUND if the path is not found |
| trap_getcwd | 32 | buffer address (pointer to string buffer), buffer size (long) | obtains the current working directory of the calling process, returns 0, or -1 in case of error |
| trap_chdir | 33 | path address (pointer to a string) | changes the current working directory of the calling process, returns 0, or -1 in case of error |
| trap_mkdir | 34 | path address (pointer to a string), mode (int) (mode not used currently) | creates a directory, returns 0, or -1 in case of error |
| trap_opendir | 35 | path address (pointer to a string) | opens a directory for inspection, returns a nonnegative directory descriptor (int), or -1 in case of error |
| trap_closedir | 36 | directory descriptor (int) | close a directory, returns -1 in case of error |
| trap_readdir | 37 | directory descriptor (int), directory entry buffer address (pointer), directory entry buffer size (long) | reads a directory entry, returns 1 if an entry read, 0 if no more entries, or -1 in case of error |
| trap_utime | 38 | path address (pointer to string), time buffer address (pointer to two ulongs that contain time in nanoseconds), time buffer size (long) | updates the access and modification timestamps of a file or directory, returns 0, or -1 in case of error |
| trap_mcpy | 39 | source buffer address (pointer), target buffer address (pointer), count (long) | copies memory from source buffer to target buffer, returns 0, or -1 in case of error |
| trap_open_resource | 40 | address of resource name (pointer to string) | returns a nonnegative resource descriptor (int) for a resource linked inside the program executable of the calling process, or -1 in case of error |
| trap_close_resource | 41 | a resource descriptor (int) | closes a resource, returns 0, or -1 in case of error |
| trap_get_resource_size | 42 | a resource descriptor (int) | returns the size of the given resource (long), or -1 in case of error |
| trap_read_resource | 43 | a resource descriptor (int), offset (long), length (long), address of buffer (pointer) | reads the contents of a resource to a buffer, returns 0, or -1 in case of error |
| trap_decompress | 44 | buffer address (pointer), length (long) | decompresses a memory buffer using ZLIB, returns a nonnegative decompression descriptor, or -1 in case of error |
| trap_get_decompressed_data_size | 45 | decompression descriptor (int), | returns the size of the decompressed data (long), or -1 in case of error |
| trap_get_decompressed_data | 46 | decompression descriptor (int), address of a buffer (pointer), buffer size (long) | reads the decompressed data to a buffer, returns 0, or -1 in case of error |
| trap_close_decompression | 47 | decompression descriptor (int) | closes a decompression descriptor, returns 0, or -1 in case of error |
| trap_get_host_name | 48 | buffer address (pointer to string), buffer size (long) | obtains the computer name, returns 0, or -1 in case of error |
| trap_get_user_name | 49 | buffer address (pointer to string), buffer size (long) | obtains the name of the logged on user, returns 0, or -1 in case of error |
| trap_pipe | 50 | read file descriptor (pointer to int), write file descriptor (pointer to int) | creates a pipe and obtains file descriptors for reading from and writing to the pipe, returns 0, or -1 in case of error |
| trap_dup | 51 | file descriptor (int) | duplicates a file descriptor returning an identical file descriptor that has the smallest available number, returns -1 in case of error |
| trap_setuid | 52 | user identifier (int) | sets the user ID and the effective user ID of the current process, if permissions allow it, returns -1 in case of error |
| trap_setgid | 53 | group identifier (int) | sets the group ID and the effective group ID of the current process, if permissions allow it, returns -1 in case of error |
| trap_getuid | 54 | - | returns the user ID of the current process, returns -1 in case of error |
| trap_getgid | 55 | - | returns the group ID of the current process, returns -1 in case of error |
| trap_seteuid | 56 | effective user identifier (int) | sets the effective user ID of the current process, if permissions allow it, returns -1 in case of error |
| trap_setegid | 57 | effective group identifier (int) | sets the effective group ID of the current process, if permissions allow it, returns -1 in case of error |
| trap_geteuid | 58 | - | returns the effective user ID of the current process, returns -1 in case of error |
| trap_getegid | 59 | returns the effective group ID of the current process, returns -1 in case of error | |
| trap_umask | 60 | umask (int) | sets the umask of the current process, returns -1 in case of error |
| trap_chmod | 61 | path (pointer to a string), mode (int) | changes the access mode of a file, returns -1 in case of error |
| trap_chown | 62 | path (pointer to a string), UID (int), GID (int) | changes the owner of a file, if permmissions allow it, returns -1 in case of error |
| trap_rename | 63 | source file path (pointer to a string), target file path (pointer to a string) | renames or moves a file, returns -1 in case of error |
| trap_add_dir_change_notification | 64 | directories separated by colons (pointer to a string) | starts watching changes in the specified directories, returns -1 in case of error |
| trap_remove_dir_change_notifications | 65 | - | stops watching changes in directories, returns -1 in case of error |
| trap_directories_changed | 66 | - | returns 1 if watched directories have been changed (new or removed files), 0 if no changes have occurred, returns -1 in case of error |
| trap_clear_directories_changed | 67 | - | resets the 'directories changed' flag from the current process, returns -1 in case of error |
| trap_child_times | 68 | address of a variable containing child user time in nanoseconds (pointer to ulong), address of a variable containing child sleep time in nanoseconds (pointer to ulong), address of a variable containing child kernel time in nanoseconds (pointer to ulong) | obtains execution statistics for the exited child processes of the current process |
| trap_msgq | 69 | name of the message queueu to create or open (pointer to string) | creates or opens a message queue, returns message queue descriptor, or -1 in case of error |
| trap_close_msgq | 70 | message queue descriptor (int) | closes a message queue, returns 0, or -1 in case of error |
| trap_wait_msg | 71 | message queue descriptor (int) | waits until message queue is not empty, returns 0, or -1 in case of error |
| trap_put_msg | 72 | message queue descriptor (int), message data buffer (pointer), message size (int) | enqueues a message to the given message queue |
| trap_get_msgq_length | 73 | message queue descriptor (int) | returns the length of the given message queue, or -1 in case of error |
| trap_get_msg_size | 74 | message queue descriptor (int) | returns the size of the message in front of the given message queue, or -1 in case of error |
| trap_get_msg | 75 | message queue descriptor (int), buffer address (pointer) | fetches and removes the message in front of the given message queue, returns 0, or -1 in case of error |
| trap_bind_terminal | 76 | message queue descriptor (int) | binds terminal input system to the given message queue, returns 0, or -1 in case of error |
| trap_unbind_terminal | 77 | - | unbinds terminal input system from message queues, returns 0, or -1 in case of error |
| trap_timer_msg | 78 | duration in nanoseconds (long), message queue descriptor (int), message data (pointer), message size (int) | generates given message until duration nanoseconds have been elapsed and puts the message to the given message queue, returns 0, or -1 in case of error |
| trap_connect | 79 | node (pointer to string), service (pointer to strign) | connects to the given node address and service (or port number) and returns a connected socket descriptor |
| trap_get_debug_mode | 80 | - | returns current kernel debug mode (0 is the default=no kernel debugging enabled), or -1 in case of error |
| trap_set_debug_mode | 81 | mode (int) | sets the kernel debug mode to the given mode value, returns 0, or -1 in case of error |
| trap_write_debug_message | 82 | debug messsage (pointer to string) | writes a debug message, returns 0, or -1 in case of error (debug messsages show up in a 'cmlog' command line process if it is started and kernel debugging is enabled) |