Nix 2.30.0
Nix, the purely functional package manager: C API (experimental)
|
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 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... |
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. |
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:
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.
[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. |
enum nix_err |
Type for error codes in the Nix system.
This type can have one of several predefined constants:
nix_c_context * nix_c_context_create | ( | ) |
Allocate a new nix_c_context.
std::bad_alloc |
void nix_c_context_free | ( | nix_c_context * | context | ) |
Free a nix_c_context. Does not fail.
[out] | context | The context to free, mandatory. |
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:
This failure can be avoided by clearing the error message after handling it.
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
[in] | read_context | the context to retrieve the error message from |
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.
[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. |
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.
[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. |
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.
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. |
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.
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. |