Nix 2.29.1
Nix, the purely functional package manager: C API (experimental)
 
Loading...
Searching...
No Matches
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 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_contextnix_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.
 

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() {
if (nix_err_code(ctx) != NIX_OK) {
printf("error: %s\n", nix_err_msg(NULL, ctx, NULL));
return 1;
}
return 0;
}
nix_c_context * nix_c_context_create()
Allocate a new nix_c_context.
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_code(const nix_c_context *read_context)
Retrieves the most recent error code from a nix_c_context.
@ NIX_OK
No error occurred.
Definition nix_api_util.h:67
nix_err nix_libutil_init(nix_c_context *context)
Initializes nix_libutil and its dependencies.
This object stores error state.

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]startthe string to copy.
[in]nthe string length.
[in]user_dataoptional, 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 error occurred (-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 error occurred.

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

NIX_ERR_NIX_ERROR 

A generic Nix error occurred.

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

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]contextThe 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_contextthe 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]contextoptional, the context to store errors in if this function fails
[in]read_contextthe context to retrieve the error message from.
[in]callbackCalled with the error message.
[in]user_dataoptional, 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]contextoptional, the context to store errors in if this function fails
[in]ctxthe context to retrieve the error message from
[out]noptional: 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
contextoptional, the context to store errors in if this function fails
[in]read_contextthe context to retrieve the error message from
[in]callbackCalled with the error name.
[in]user_dataoptional, 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
contextcontext to write the error message to, required unless C++ exceptions are supported
errThe error code to set and return
msgThe error message to set. This string is copied.
Returns
the error code set