Home --> Documentations --> PJLIB Reference

Modules | Macros | Typedefs | Functions
Error Subsystem

Modules

 PJLIB's Own Error Codes
 

Macros

#define PJ_ERR_MSG_SIZE   80
 
#define PJ_PERROR_TITLE_BUF_SIZE   120
 
#define PJ_PERROR(level, arg)
 
#define PJ_RETURN_OS_ERROR(os_code)
 
#define PJ_STATUS_FROM_OS(e)
 
#define PJ_STATUS_TO_OS(e)
 

Typedefs

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

Functions

pj_status_t pj_get_os_error (void)
 
void pj_set_os_error (pj_status_t code)
 
pj_status_t pj_get_netos_error (void)
 
void pj_set_netos_error (pj_status_t code)
 
pj_str_t pj_strerror (pj_status_t statcode, char *buf, pj_size_t bufsize)
 
void pj_perror (int log_level, const char *sender, pj_status_t status, const char *title_fmt,...)
 
pj_status_t pj_register_strerror (pj_status_t start_code, pj_status_t err_space, pj_error_callback f)
 

Detailed Description

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:

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.

Macro Definition Documentation

#define PJ_ERR_MSG_SIZE   80

Guidelines on error message length.

#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
levelThe 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).
argEnclosed '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"));
#define PJ_PERROR_TITLE_BUF_SIZE   120

Buffer for title string of PJ_PERROR().

#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_codePlatform OS error code. This value may be evaluated more than once.
Returns
The platform os error code folded into pj_status_t.
#define PJ_STATUS_FROM_OS (   e)

Fold a platform specific error into an pj_status_t code.

Parameters
eThe platform os error code.
Returns
pj_status_t
Warning
Macro implementation; the syserr argument may be evaluated multiple times.
#define PJ_STATUS_TO_OS (   e)

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

Parameters
eThe 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.

Typedef Documentation

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()

Parameters
eThe error code to lookup.
msgBuffer to store the error message.
maxLength of the buffer.
Returns
The error string.

Function Documentation

pj_status_t pj_get_netos_error ( void  )

Get the last error from socket operations.

Returns
Last socket error, folded into pj_status_t.
pj_status_t pj_get_os_error ( void  )

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

Returns
OS dependent error code, folded into pj_status_t.
Remarks
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()
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_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_codeThe starting error code where the handler should be called to retrieve the error message.
err_spaceThe size of error space. The error code range then will fall in start_code to start_code+err_space-1 range.
fThe 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.
void pj_set_netos_error ( pj_status_t  code)

Set error code.

Parameters
codepj_status_t.
void pj_set_os_error ( pj_status_t  code)

Set last error.

Parameters
codepj_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
statcodeThe error code.
bufBuffer to hold the error message string.
bufsizeSize 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.