Return codes

A KasperskyOS-based solution uses several different types of return codes to encode the results of API functions. Almost all API functions of the libkos library that transmit return codes return values of the Retcode type, which is defined in the header file sysroot-*-kos/include/rtl/retcode.h from the KasperskyOS SDK. Also, return codes of this type are transmitted by API functions of the kdf library and API functions of programs supplied as part of the KasperskyOS SDK (for example, drivers and other system programs created for use in KasperskyOS-based solutions). Transport code functions, several API functions of the libkos library for working with IPC transport, and functions of some other IPC-related APIs (for example, functions defined in the header file sysroot-*-kos/include/nk/transport.h from the KasperskyOS SDK) transmit return codes of the nk_err_t type, which is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK. POSIX interface functions and third-party API functions transmit other types of return codes.

It is recommended that the solution developer encode the results of executing their functions by using return codes of the Retcode type.

Retcode return code format

The Retcode type is defined in the header file retcode.h as a 32-bit signed integer:

typedef __INT32_TYPE__ Retcode;

The set of return codes of the Retcode type consists of a success code with a value of 0 and error codes. The error code is interpreted as a data structure whose format is shown in the figure below.

Retcode return code format

This format provides for multiple fields that contain not only information about the results of a function execution (in the Code field), but also the following additional information:

• Flag in the Severity field that distinguishes the error code (1) from the success code (0). This field is used for backward compatibility with other error code formats.
• Flag in the Customer field indicating that the error code was defined by the developers of the solution and not by the developers of software from the KasperskyOS SDK.

  Thanks to the flag in the Customer field, developers of a solution and developers of software from the KasperskyOS SDK can define error codes from non-overlapping sets.

• Global ID of the error code in the Space field.

  Global IDs let you define non-overlapping sets of error codes. Error codes can be generic or specific. Generic error codes can be used in the APIs of any solution components and in the APIs of any constituent parts of solution components (for example, a driver or VFS may be a constituent part of a solution component). Specific error codes are used in the APIs of one or more solution components or in the APIs of one or more constituent parts of solution components.

  For example, the RC_SPACE_GENERAL ID corresponds to generic errors, the RC_SPACE_KERNEL ID corresponds to error codes of the kernel, and the RC_SPACE_DRIVERS ID corresponds to error codes of drivers.

• Local ID of the error code in the Facility field.

  Local IDs let you define non-overlapping subsets of error codes within the set of error codes corresponding to one global ID. For example, the set of error codes with the global ID RC_SPACE_DRIVERS includes non-overlapping subsets of error codes with the local IDs RC_FACILITY_I2C, RC_FACILITY_USB, and RC_FACILITY_BLKDEV. (These local identifiers are defined in the header file sysroot-*-kos/include/kdf/facilities.h from the KasperskyOS SDK.)

The global and local IDs of specific error codes are assigned by the developers of a solution and by the developers of software from the KasperskyOS SDK independently of each other. In other words, two sets of global IDs are generated. Each global ID has a unique meaning within one set. Each local ID has a unique meaning within a set of local IDs related to one global ID.

This type of centralized approach helps avoid situations in which the same error codes have various meanings within a solution. This is necessary to eliminate a potential problem transmitting error codes through different APIs. For example, this problem occurs when drivers call kdf library functions, receive error codes, and return these codes through their own APIs. If error codes are generated without a centralized approach, the same error code can have different meanings for the kdf library and for the driver. Under these conditions, drivers return correct error codes only if the error codes of the kdf library are converted into error codes of each driver. In other words, error codes are assigned in such way that does not require conversion of these codes during their transit through various APIs.

General return codes of the Retcode type

The general return codes of the Retcode type as defined in the header file retcode.h are shown in the table below. This table also shows the mapping between the return codes of the Retcode type and the return codes of the nk_err_t type, which are defined in the header file sysroot-*-kos/include/nk/errno.h from the KasperskyOS SDK. This mapping is required for conversions between these two types of return codes. For example, conversion is required if a developed function that returns values of the Retcode type "wraps" a transport code function that returns values of the nk_err_t type. However, please keep in mind that conversion is not always possible for the following reasons:

• Some return codes are not mapped to return codes of the other type.
• Some return codes of the nk_err_t type are mapped to multiple return codes of the Retcode type. In other words, it may be impossible to explicitly determine which return code of the Retcode type corresponds to a return code of the nk_err_t type that needs to be converted.

  General return codes of the Retcode type

  Retcode return code	Description	Nk_err_t return code
  rcOk (corresponds to the 0 value)	The function completed successfully.	NK_EOK
  rcInvalidArgument	Invalid function parameter.	NK_EINVAL
  rcNotConnected	No connection between the client and server sides of interaction. For example, there is no server IPC handle.	NK_ENOTCONN
  rcOutOfMemory	Insufficient memory to perform the operation.	NK_ENOMEM
  rcBufferTooSmall	Insufficient buffer size.	NK_EBADMSG
  rcInternalError	The function ended with an internal error related to incorrect logic. Some examples of internal errors include values outside of the permissible limits, and null indicators and values where they are not permitted.	No
  rcTransferError	Error sending an IPC message.	No
  rcReceiveError	Error receiving an IPC message.	No
  rcSourceFault	IPC message was not transmitted due to the IPC message source.	No
  rcTargetFault	IPC message was not transmitted due to the IPC message recipient.	No
  rcIpcInterrupt	IPC was interrupted by another process thread.	No
  rcInvalidFormat	Data format is incorrect.	No
  rcRestart	Indicates that the function needs to be called again.	No
  rcFail	The function ended with an error.	No
  rcNoCapability	The operation cannot be performed with the resource.	NK_ENOENT
  rcNotReady	Initialization failed.	NK_EAGAIN
  rcUnimplemented	The function was not implemented.	No
  rcBufferTooLarge	Large buffer size.	NK_EBADMSG
  rcBusy	Resource temporarily unavailable.	No
  rcResourceNotFound	Resource not found.	No
  rcTimeout	Timed out.	NK_EAGAIN
  rcSecurityDisallow	The operation was denied by security mechanisms.	NK_EPERM
  rcFutexWouldBlock	The operation will result in a block.	No
  rcAbort	The operation was aborted.	NK_ENOENT
  rcInvalidThreadState	Invalid function called in the interrupt handler.	No
  rcAlreadyExists	Set of elements already contains the element being added.	NK_ENOTEMPTY
  rcInvalidOperation	Operation cannot be completed.	No
  rcHandleRevoked	Resource access rights were revoked.	NK_EREVOKED
  rcQuotaExceeded	Resource quota exceeded.	No
  rcDeviceNotFound	Device not found.	No
  rcOverflow	An overflow occurred.	No
  rcAlreadyDone	Operation has already been completed.	No
  rcNotRun	Operation has not been started.	No
  rcEntropySourceStuck	Source of entropy may be unreliable.	No
  rcDeadlock	A deadlock has occurred.	No
  rcInvalidHandle	Handle is closed.	No

Defining a Retcode error code

To define an error code of the Retcode type, the solution developer must use the MAKE_RETCODE() macro that is defined in the retcode.h header file. The developer must also use the customer parameter to pass the symbolic constant RC_CUSTOMER_TRUE.

Example:

#define LV_EBADREQUEST MAKE_RETCODE(RC_CUSTOMER_TRUE, RC_SPACE_APPS, RC_FACILITY_LogViewer, 5, "Bad request")

An error description that is passed via the desc parameter is not used by the MAKE_RETCODE() macro. This description is needed to create a database of error codes when building a KasperskyOS-based solution. At present, a mechanism for creating and using such a database has not been implemented.

Reading Retcode type error code structure fields

The macros RC_GET_CUSTOMER(), RC_GET_SPACE(), RC_GET_FACILITY(), and RC_GET_CODE() defined in the retcode.h header file allow you to read the fields of the Retcode error code structure.

The RETCODE_HR_PARAMS() and RETCODE_HR_FMT() macros defined in the sysroot-*-kos/include/rtl/retcode_hr.h header file from the KasperskyOS SDK are used for formatted display of Retcode type error details.

Page top