Executing system calls (syscalls.h)

This API is defined in the header file sysroot-*-kos/include/coresrv/syscalls.h from the KasperskyOS SDK.

The API allows execution of the Call(), Recv(), and Reply() system calls for sending and receiving IPC messages.

Information about API functions is provided in the table below.

Using the API

Pointers to buffers containing the constant part and arena of IPC messages are passed to API functions by using an IPC message header whose type is defined in the header file sysroot-*-kos/include/ipc/if_rend.h from the KasperskyOS SDK. Prior to API function calls, the headers of IPC messages must be bound to buffers containing the constant part and arena of IPC messages. To do so, use the PackInMsg() and PackOutMsg() functions that are declared in the header file sysroot-*-kos/include/services/rtl/nk_msg.h from the KasperskyOS SDK.

The Call(), CallEx(), Recv(), and RecvEx() functions lock execution of the calling thread while waiting for the system calls to complete. The CallEx() and RecvEx() functions let you define the timeout for completion of a system call. When this timeout is reached, an uncompleted system call is interrupted and the thread that is waiting for its completion resumes execution. A system call is also interrupted if an error occurs during its execution (such as an error due to termination of a server process). If a thread waiting on the completion of a system call is terminated externally, this system call is also interrupted. A system call executed by the CallEx() or RecvEx() function can be interrupted (for example, for correct termination of a process) by using the API ipc_api.h.

If a system call was interrupted using the API ipc_api.h, the CallEx() and RecvEx() functions return the error code rcIpcInterrupt. If IPC message transmission is prohibited by security mechanisms (such as the Kaspersky Security Module or a capability-based security mechanism implemented by the KasperskyOS kernel), the Call(), CallEx(), and Reply() functions return the error code rcSecurityDisallow.

Information about API functions

syscalls.h functions

Function

Information about the function

Call()

Purpose

Executes the Call() system call with an unlimited timeout for its completion.

Parameters

  • [in] handle – client IPC handle.
  • [in] msgOut – pointer to the header of IPC requests.
  • [in,out] msgIn – pointer to the header of IPC responses.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

CallEx()

Purpose

Executes the Call() system call with a defined timeout for its completion and the capability to interrupt its execution.

Parameters

  • [in] handle – client IPC handle.
  • [in] msgOut – pointer to the header of IPC requests.
  • [in,out] msgIn – pointer to the header of IPC responses.
  • [in] mdelay – timeout (in milliseconds) for completion of a Call() system call, or INFINITE_TIMEOUT to define an unlimited timeout.
  • [in,optional] syncHandle – handle of the IPC synchronization object, or INVALID_HANDLE if an interrupt of the Call() system call is not required.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

Reply()

Purpose

Executes the Reply() system call.

Parameters

  • [in] handle – server IPC handle.
  • [in] msgOut – pointer to the header of IPC responses.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

Recv()

Purpose

Executes the Recv() system call with an unlimited timeout for its completion.

Parameters

  • [in] handle – server IPC handle.
  • [in,out] msgIn – pointer to the header of IPC requests.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

RecvEx()

Purpose

Executes the Recv() system call with a defined timeout for its completion and the capability to interrupt its execution.

Parameters

  • [in] handle – server IPC handle.
  • [in,out] msgIn – pointer to the header of IPC responses.
  • [in] mdelay – timeout (in milliseconds) for completion of a Recv() system call, or INFINITE_TIMEOUT to define an unlimited timeout.
  • [in,optional] syncHandle – handle of the IPC synchronization object, or INVALID_HANDLE if an interrupt of the Recv() system call is not required.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

Page top