Handling errors

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

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

Typedefs
typedef enum nix_err	nix_err
typedef enum nix_verbosity	nix_verbosity
typedef struct nix_c_context	nix_c_context
typedef void(*	nix_get_string_callback) (const char *start, unsigned int n, void *user_data)
	Called to get the value of a string owned by Nix.

Enumerations
enum	nix_err {   NIX_OK = 0 , NIX_ERR_UNKNOWN = -1 , NIX_ERR_OVERFLOW = -2 , NIX_ERR_KEY = -3 ,   NIX_ERR_NIX_ERROR = -4 }
	Type for error codes in the Nix system. More...
enum	nix_verbosity {   NIX_LVL_ERROR = 0 , NIX_LVL_WARN , NIX_LVL_NOTICE , NIX_LVL_INFO ,   NIX_LVL_TALKATIVE , NIX_LVL_CHATTY , NIX_LVL_DEBUG , NIX_LVL_VOMIT }
	Verbosity level. More...

Functions
nix_c_context *	nix_c_context_create ()
	Allocate a new nix_c_context.
void	nix_c_context_free (nix_c_context *context)
	Free a nix_c_context. Does not fail.
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.
nix_err	nix_err_info_msg (nix_c_context *context, const nix_c_context *read_context, nix_get_string_callback callback, void *user_data)
	Retrieves the error message from errorInfo in a context.
nix_err	nix_err_name (nix_c_context *context, const nix_c_context *read_context, nix_get_string_callback callback, void *user_data)
	Retrieves the error name from a context.
nix_err	nix_err_code (const nix_c_context *read_context)
	Retrieves the most recent error code from a nix_c_context.
nix_err	nix_set_err_msg (nix_c_context *context, nix_err err, const char *msg)
	Set an error message on a nix context.
void	nix_clear_err (nix_c_context *context)
	Clear the error message from a nix context.
nix_err	nix_set_verbosity (nix_c_context *context, nix_verbosity level)
	Sets the verbosity level.

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;
}

Typedef Documentation

nix_get_string_callback

typedef void(* nix_get_string_callback) (const char *start, unsigned int n, void *user_data)

Called to get the value of a string owned by Nix.

Parameters

[in]	start	the string to copy.
[in]	n	the string length.
[in]	user_data	optional, arbitrary data, passed to the nix_get_string_callback when it's called.

Enumeration Type Documentation

nix_err

enum 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/index access error occurred in C API functions (-3)
• NIX_ERR_NIX_ERROR: A generic Nix error occurred (-4)

Enumerator
NIX_OK	No error occurred. This error code is returned when no error has occurred during the function execution.
NIX_ERR_UNKNOWN	An unknown error occurred. This error code is returned when an unknown error occurred during the function execution.
NIX_ERR_OVERFLOW	An overflow error occurred. This error code is returned when an overflow error occurred during the function execution.
NIX_ERR_KEY	A key/index access error occurred in C API functions. This error code is returned when accessing a key, index, or identifier that does not exist in C API functions. Common scenarios include: Setting keys that don't exist (nix_setting_get, nix_setting_set) List indices that are out of bounds (nix_get_list_byidx*) Attribute names that don't exist (nix_get_attr_byname*) Attribute indices that are out of bounds (nix_get_attr_byidx*, nix_get_attr_name_byidx) This error typically indicates incorrect usage or assumptions about data structure contents, rather than internal Nix evaluation errors. Note This error code should ONLY be returned by C API functions themselves, not by underlying Nix evaluation. For example, evaluating {}.foo in Nix will throw a normal error (NIX_ERR_NIX_ERROR), not NIX_ERR_KEY.
NIX_ERR_NIX_ERROR	A generic Nix error occurred. This error code is returned when a generic Nix error occurred during the function execution.

nix_verbosity

enum nix_verbosity

Verbosity level.

Note

This should be kept in sync with the C++ implementation (nix::Verbosity)

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

void nix_clear_err

(

nix_c_context *

context

)

Clear the error message from a nix context.

This is performed implicitly by all functions that accept a context, so this won't be necessary in most cases. However, if you want to clear the error message without calling another function, you can use this.

Example use case: a higher order function that helps with error handling, to make it more robust in the following scenario:

1. A previous call failed, and the error was caught and handled.
2. The context is reused with our error handling helper function.
3. The callback passed to the helper function doesn't actually make a call to a Nix function.
4. The handled error is raised again, from an unrelated call.

This failure can be avoided by clearing the error message after handling it.

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,
		nix_get_string_callback	callback,
		void *	user_data )

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.
[in]	callback	Called with the error message.
[in]	user_data	optional, arbitrary data, passed to the callback when it's called.

See also

nix_get_string_callback

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, which is valid until the next call to a Nix function, or until the context is destroyed.

nix_err_name()

nix_err nix_err_name	(	nix_c_context *	context,
		const nix_c_context *	read_context,
		nix_get_string_callback	callback,
		void *	user_data )

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
[in]	callback	Called with the error name.
[in]	user_data	optional, arbitrary data, passed to the callback when it's called.

See also

nix_get_string_callback

Returns

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

nix_set_err_msg()

nix_err nix_set_err_msg	(	nix_c_context *	context,
		nix_err	err,
		const char *	msg )

Set an error message on a nix context.

This should be used when you want to throw an error from a PrimOp callback.

All other use is internal to the API.

Parameters

context	context to write the error message to, required unless C++ exceptions are supported
err	The error code to set and return
msg	The error message to set. This string is copied.

Returns

the error code set

nix_set_verbosity()

nix_err nix_set_verbosity	(	nix_c_context *	context,
		nix_verbosity	level )

Sets the verbosity level.

Parameters

[out]	context	Optional, additional error context.
[in]	level	Verbosity level