Home --> Documentations --> PJLIB Reference
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.
◆ PJ_ERR_MSG_SIZE
#define PJ_ERR_MSG_SIZE 80 |
Guidelines on error message length.
◆ PJ_PERROR
#define 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.
- 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.
|
Sample: PJ_PERROR(2, (__FILE__, PJ_EBUSY, "Error making %s", "coffee"));
◆ PJ_PERROR_TITLE_BUF_SIZE
#define PJ_PERROR_TITLE_BUF_SIZE 120 |
◆ PJ_RETURN_OS_ERROR
#define 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
#define PJ_STATUS_FROM_OS |
( |
|
e | ) |
|
Fold a platform specific error into an pj_status_t code.
- Parameters
-
e | The platform os error code. |
- Returns
- pj_status_t
- Warning
- Macro implementation; the syserr argument may be evaluated multiple times.
◆ PJ_STATUS_TO_OS
#define PJ_STATUS_TO_OS |
( |
|
e | ) |
|
Fold an pj_status_t code back to the native platform defined error.
- Parameters
-
e | The pj_status_t folded platform os error code. |
- Returns
- pj_os_err_type
- 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.
◆ pj_error_callback
Type of callback to be specified in pj_register_strerror()
- Parameters
-
e | The error code to lookup. |
msg | Buffer to store the error message. |
max | Length of the buffer. |
- Returns
- The error string.
◆ pj_get_netos_error()
Get the last error from socket operations. - Returns
- Last socket error, folded into pj_status_t.
◆ pj_get_os_error()
Get the last platform error/status, folded into pj_status_t. - Returns
- OS dependent error code, folded into pj_status_t.
- See also
- pj_get_netos_error()
◆ pj_perror()
void pj_perror |
( |
int |
log_level, |
|
|
const char * |
sender, |
|
|
pj_status_t |
status, |
|
|
const char * |
title_fmt, |
|
|
|
... |
|
) |
| |
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_register_strerror()
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.
◆ pj_set_netos_error()
Set error code. - Parameters
-
◆ pj_set_os_error()
Set last error. - Parameters
-
◆ pj_strerror()
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.
PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.
|