Group pj_errno

group pj_errno

The PJLIB Error Subsystem is a framework to unify all error codes produced by all components into a single error space, and provide uniform set of APIs to access them. With this framework, any error codes are encoded as pj_status_t value. The framework is extensible, application may register new error spaces to be recognized by the framework.

Return Values

All functions that returns pj_status_t returns PJ_SUCCESS if the operation was completed successfully, or non-zero value to indicate error. If the error came from operating system, then the native error code is translated/folded into PJLIB’s error namespace by using PJ_STATUS_FROM_OS() macro. The function will do this automatically before returning the error to caller.

Retrieving and Displaying Error Messages

The framework provides the following APIs to retrieve and/or display error messages:

  • pj_strerror(): this is the base API to retrieve error string description for the specified pj_status_t error code.

  • PJ_PERROR() macro: use this macro similar to PJ_LOG to format an error message and display them to the log

  • pj_perror(): this function is similar to PJ_PERROR() but unlike PJ_PERROR(), this function will always be included in the link process. Due to this reason, prefer to use PJ_PERROR() if the application is concerned about the executable size.

Application MUST NOT pass native error codes (such as error code from functions like GetLastError() or errno) to PJLIB functions expecting pj_status_t.

Extending the Error Space

Application may register new error space to be recognized by the framework by using pj_register_strerror(). Use the range started from PJ_ERRNO_START_USER to avoid conflict with existing error spaces.

Defines

PJ_ERR_MSG_SIZE

Guidelines on error message length.

PJ_PERROR_TITLE_BUF_SIZE

Buffer for title string of PJ_PERROR().

PJ_PERROR(level, arg)

A utility macro to print error message pertaining to the specified error code to the log. This macro will construct the error message title according to the ‘title_fmt’ argument, and add the error string pertaining to the error code after the title string. A colon (‘:’) will be added automatically between the title and the error string.

This function is similar to pj_perror() function, but has the advantage that the function call can be omitted from the link process if the log level argument is below PJ_LOG_MAX_LEVEL threshold.

Note that the title string constructed from the title_fmt will be built on a string buffer which size is PJ_PERROR_TITLE_BUF_SIZE, which normally is allocated from the stack. By default this buffer size is small (around 120 characters). Application MUST ensure that the constructed title string will not exceed this limit, since not all platforms support truncating the string.

Sample: 

PJ_PERROR(2, (__FILE__, PJ_EBUSY, "Error making %s", "coffee"));

See also

pj_perror()

Parameters:

  • level – The logging verbosity level, valid values are 0-6. Lower number indicates higher importance, with level zero indicates fatal error. Only numeral argument is permitted (e.g. not variable).

  • arg – Enclosed ‘printf’ like arguments, with the following arguments:

    • the sender (NULL terminated string),

    • the error code (pj_status_t)

    • the format string (title_fmt), and

    • optional variable number of arguments suitable for the format string.

PJ_RETURN_OS_ERROR(os_code)

Return platform os error code folded into pj_status_t code. This is the macro that is used throughout the library for all PJLIB’s functions that returns error from operating system. Application may override this macro to reduce size (e.g. by defining it to always return PJ_EUNKNOWN).

Note: This macro MUST return non-zero value regardless whether zero is passed as the argument. The reason is to protect logic error when the operating system doesn’t report error codes properly.

Parameters:

  • os_code – Platform OS error code. This value may be evaluated more than once.

Returns:

The platform os error code folded into pj_status_t.

PJ_STATUS_FROM_OS(e)

Fold a platform specific error into an pj_status_t code.

Warning

Macro implementation; the syserr argument may be evaluated multiple times.

Parameters:

  • e – The platform os error code.

Returns:

pj_status_t

PJ_STATUS_TO_OS(e)

Fold an pj_status_t code back to the native platform defined error.

Warning

macro implementation; the statcode argument may be evaluated multiple times. If the statcode was not created by pj_get_os_error or PJ_STATUS_FROM_OS, the results are undefined.

Parameters:

  • e – The pj_status_t folded platform os error code.

Returns:

pj_os_err_type

Typedefs

typedef pj_str_t (*pj_error_callback)(pj_status_t e, char *msg, pj_size_t max)

Type of callback to be specified in pj_register_strerror()

Param e:

The error code to lookup.

Param msg:

Buffer to store the error message.

Param max:

Length of the buffer.

Return:

The error string.

Functions

pj_status_t pj_get_os_error(void)

Get the last platform error/status, folded into pj_status_t.

Remark

This function gets errno, or calls GetLastError() function and convert the code into pj_status_t with PJ_STATUS_FROM_OS. Do not call this for socket functions!

See also

pj_get_netos_error()

Returns:

OS dependent error code, folded into pj_status_t.

void pj_set_os_error(pj_status_t code)

Set last error.

Parameters:

code – pj_status_t

pj_status_t pj_get_netos_error(void)

Get the last error from socket operations.

Returns:

Last socket error, folded into pj_status_t.

void pj_set_netos_error(pj_status_t code)

Set error code.

Parameters:

code – pj_status_t.

pj_str_t pj_strerror(pj_status_t statcode, char *buf, pj_size_t bufsize)

Get the error message for the specified error code. The message string will be NULL terminated.

Parameters:

  • statcode – The error code.

  • buf – Buffer to hold the error message string.

  • bufsize – Size of the buffer.

Returns:

The error message as NULL terminated string, wrapped with pj_str_t.

void pj_perror (int log_level, const char *sender, pj_status_t status, const char *title_fmt,...) PJ_PRINT_FUNC_DECOR(4)

A utility function to print error message pertaining to the specified error code to the log. This function will construct the error message title according to the ‘title_fmt’ argument, and add the error string pertaining to the error code after the title string. A colon (‘:’) will be added automatically between the title and the error string.

Unlike the PJ_PERROR() macro, this function takes the log_level argument as a normal argument, unlike in PJ_PERROR() where a numeral value must be given. However this function will always be linked to the executable, unlike PJ_PERROR() which can be omitted when the level is below the PJ_LOG_MAX_LEVEL.

Note that the title string constructed from the title_fmt will be built on a string buffer which size is PJ_PERROR_TITLE_BUF_SIZE, which normally is allocated from the stack. By default this buffer size is small (around 120 characters). Application MUST ensure that the constructed title string will not exceed this limit, since not all platforms support truncating the string.

See also

PJ_PERROR()

pj_status_t pj_register_strerror(pj_status_t start_code, pj_status_t err_space, pj_error_callback f)

Register strerror message handler for the specified error space. Application can register its own handler to supply the error message for the specified error code range. This handler will be called by pj_strerror().

Parameters:

  • start_code – The starting error code where the handler should be called to retrieve the error message.

  • err_space – The size of error space. The error code range then will fall in start_code to start_code+err_space-1 range.

  • f – The handler to be called when pj_strerror() is supplied with error code that falls into this range.

Returns:

PJ_SUCCESS or the specified error code. The registration may fail when the error space has been occupied by other handler, or when there are too many handlers registered to PJLIB.