Handling errors

Dealing with errors from the Nix side. More...

Data Structures
struct	nix_c_context
	This object stores error state. More...

Macros
#define	NIX_OK   0
	No error occurred. More...
#define	NIX_ERR_UNKNOWN   -1
	An unknown error occurred. More...
#define	NIX_ERR_OVERFLOW   -2
	An overflow error occurred. More...
#define	NIX_ERR_KEY   -3
	A key error occurred. More...
#define	NIX_ERR_NIX_ERROR   -4
	A generic Nix error occurred. More...

Typedefs
typedef int	nix_err
	Type for error codes in the NIX system. More...
typedef struct nix_c_context	nix_c_context

Functions
nix_c_context *	nix_c_context_create ()
	Allocate a new nix_c_context. More...
void	nix_c_context_free (nix_c_context *context)
	Free a nix_c_context. Does not fail. More...
const char *	nix_err_msg (nix_c_context *context, const nix_c_context *ctx, unsigned int *n)
	Retrieves the most recent error message from a context. More...
nix_err	nix_err_info_msg (nix_c_context *context, const nix_c_context *read_context, char *value, int n)
	Retrieves the error message from errorInfo in a context. More...
nix_err	nix_err_name (nix_c_context *context, const nix_c_context *read_context, char *value, int n)
	Retrieves the error name from a context. More...
nix_err	nix_err_code (const nix_c_context *read_context)
	Retrieves the most recent error code from a nix_c_context. More...

Detailed Description

Dealing with errors from the Nix side.

To handle errors that can be returned from the Nix API, a nix_c_context can be passed to any function that potentially returns an error.

Error information will be stored in this context, and can be retrieved using nix_err_code and nix_err_msg.

Passing NULL instead will cause the API to throw C++ errors.

Example:

int main() {
    nix_c_context* ctx = nix_c_context_create();
    nix_libutil_init(ctx);
    if (nix_err_code(ctx) != NIX_OK) {
        printf("error: %s\n", nix_err_msg(NULL, ctx, NULL));
        return 1;
    }
    return 0;
}

Macro Definition Documentation

NIX_ERR_KEY

#define NIX_ERR_KEY   -3

A key error occurred.

This error code is returned when a key error occurred during the function execution.

NIX_ERR_NIX_ERROR

#define NIX_ERR_NIX_ERROR   -4

A generic Nix error occurred.

This error code is returned when a generic Nix error occurred during the function execution.

NIX_ERR_OVERFLOW

#define NIX_ERR_OVERFLOW   -2

An overflow error occurred.

This error code is returned when an overflow error occurred during the function execution.

NIX_ERR_UNKNOWN

#define NIX_ERR_UNKNOWN   -1

An unknown error occurred.

This error code is returned when an unknown error occurred during the function execution.

NIX_OK

#define NIX_OK   0

No error occurred.

This error code is returned when no error has occurred during the function execution.

Typedef Documentation

nix_err

typedef int nix_err

Type for error codes in the NIX system.

This type can have one of several predefined constants:

• NIX_OK: No error occurred (0)
• NIX_ERR_UNKNOWN: An unknown error occurred (-1)
• NIX_ERR_OVERFLOW: An overflow error occurred (-2)
• NIX_ERR_KEY: A key error occurred (-3)
• NIX_ERR_NIX_ERROR: A generic Nix error occurred (-4)

Function Documentation

nix_c_context_create()

nix_c_context * nix_c_context_create

(

)

Allocate a new nix_c_context.

Exceptions

std::bad_alloc

Returns

allocated nix_c_context, owned by the caller. Free using nix_c_context_free.

nix_c_context_free()

void nix_c_context_free

(

nix_c_context *

context

)

Free a nix_c_context. Does not fail.

Parameters

[out]

context

The context to free, mandatory.

nix_err_code()

nix_err nix_err_code

(

const nix_c_context *

read_context

)

Retrieves the most recent error code from a nix_c_context.

Equivalent to reading the first field of the context.

Does not fail

Parameters

[in]

read_context

the context to retrieve the error message from

Returns

most recent error code stored in the context.

nix_err_info_msg()

nix_err nix_err_info_msg	(	nix_c_context *	context,
		const nix_c_context *	read_context,
		char *	value,
		int	n
	)

Retrieves the error message from errorInfo in a context.

Used to inspect nix Error messages.

Precondition

This function should only be called after a previous nix function has returned a NIX_ERR_NIX_ERROR

Parameters

[out]	context	optional, the context to store errors in if this function fails
[in]	read_context	the context to retrieve the error message from
[out]	value	The allocated area to write the error string to.
[in]	n	Maximum size of the returned string.

Returns

NIX_OK if there were no errors, an error code otherwise.

nix_err_msg()

const char * nix_err_msg	(	nix_c_context *	context,
		const nix_c_context *	ctx,
		unsigned int *	n
	)

Retrieves the most recent error message from a context.

Precondition

This function should only be called after a previous nix function has returned an error.

Parameters

[out]	context	optional, the context to store errors in if this function fails
[in]	ctx	the context to retrieve the error message from
[out]	n	optional: a pointer to an unsigned int that is set to the length of the error.

Returns

nullptr if no error message was ever set, a borrowed pointer to the error message otherwise.

nix_err_name()

nix_err nix_err_name	(	nix_c_context *	context,
		const nix_c_context *	read_context,
		char *	value,
		int	n
	)

Retrieves the error name from a context.

Used to inspect nix Error messages.

Precondition

This function should only be called after a previous nix function has returned a NIX_ERR_NIX_ERROR

Parameters

	context	optional, the context to store errors in if this function fails
[in]	read_context	the context to retrieve the error message from
[out]	value	The allocated area to write the error string to.
[in]	n	Maximum size of the returned string.

Returns

NIX_OK if there were no errors, an error code otherwise.