SIRTX System API
Information on the SIRTX System API
Unlike other systems that are based on syscalls and userland runtimes SIRTX focuses on the database and handles. Handles are the main way to interact with the system. They provide a way that is transparent to whether it is interacting with the kernel or the userland. Handles are also used together with the database to query or manipulate data in the database.
Handles in SIRTX are similar to POSIX file descriptors, however are used in a wider range of applications. Any tag can be opened creating a handle to the subject of the given tag. The handle can be used to access both properties and methods of the tag and the subject.
Modes
Handles are commonly opened with one of the following access modes. All modes require correct permissions on and state of the subject to be used.
SIRTX_ACCESS_PATH-
The handle is open for tag level operations only.
This is a very common mode.
In this mode no reading, writing, or any other form of manipulation to the subject is possible.
However, such handles are often used to identify ("name") a subject.
All other modes also support all operations supported by this mode.
It is similar to POSIX's
O_EXECandO_SEARCHas well as Linux'sO_PATH. SIRTX_ACCESS_RDONLY- In this mode the handle is open for reading. This mode requires the subject to be something that can be read from, such as a memory region or file.
SIRTX_ACCESS_WRONLY- In this mode the handle is open for writing only. Reading might not be possible. This mode requires the subject to be something that can be written to, such as a memory region or file. It also requires the subject to be in the correct state (such as not being write-protected).
SIRTX_ACCESS_RDWR-
In this mode the handle is open for reading, and writing.
This mode has the same requirements as
SIRTX_ACCESS_RDONLY, andSIRTX_ACCESS_WRONLYcombined. SIRTX_ACCESS_ONLINE- This mode provides access to manipulate the subject other than reading or writing. It is for example useful when only control calles are to be issued on a device.
Operations
There are a small number of operations that can be performed on handles. Not all operations are supported on all handles and modes.
read
Handles that support the read operations provide a way to read individual octets.
This is very similar to the POSIX function read(2).
write
Handles supporting the write operation provide a way to write individual octets.
This is very similar to the POSIX function write(2).
seek
Some handles support a seek operation as a performance optimised way of using control with control-seek.
close
This is a operation handles that require explicit resource cleanup implement. This is called automatically by the system once the last reference to a handle is dropped. It is never called directly by any userland code.
control
The control method implements the main part of operations. It allows handles to interact with other handles, performing a large range of tasks. This operation is also used to implement user defined methods. Many well known commands are also assigned a SIRTX numerical identifiers (sni). They are documented in the corresponding list.
transfer
Transfers are used to transfer one subject to another. This is useful to copy data, deliver messages, print data, or similar.
contents
The contents operation, when called, will call a callback for every subject that is part of this subject. This is useful in a large range of applications, such as listing directory contents, print queues, or lists.
status
The status operation is called by the system and never by the userland. It is used to communicate the status for multi-handle polling.
call
The call operation is used to call the subject. This is used when the subject refers to some other code or function.