Error Codes

Detailed Description

In PJLIB, error/status codes from operating system are translated into PJLIB error namespace, and stored in pj_status_t. All functions that work with pj_status_t expect to get PJLIB error code instead of native codes.

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.

Error Message

To get the error message corresponding to a particular code, use function pj_strerror(). This function expects error code in PJLIB error namespace, not the native error code. Application can pass the value from the following sources to this function:

pj_get_os_error()
pj_get_netos_error()
any return value from function returning pj_status_t.

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

Modules

PJLIB's Own Error Codes

Defines

#define PJ_ERR_MSG_SIZE 80

#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, int options)

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

Define Documentation

#define PJ_ERR_MSG_SIZE 80

Guidelines on error message length.

#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.

#define PJ_STATUS_FROM_OS ( e )

Fold a platform specific error into an pj_status_t code.

Parameters:

The 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:

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.

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:

	e	The error code to lookup.
	msg	Buffer to store the error message.
	max	Length 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,
		int	options
	)

Print the error message pertaining to the specified error code to the log.

Parameters:

	log_level	The log will be printed at this log level.
	sender	The log sender string.
	status	The error code which error message will be printed.
	title	String to be printed before the error message. Note that a colon will be added automatically between this string and the error message.
	options	Options, currently must be zero.

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.

void pj_set_netos_error ( pj_status_t code )

Set error code.

Parameters:

code

pj_status_t.

void pj_set_os_error ( pj_status_t code )

Set last error.

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.