C API: Make nix_err an enum

This generally gives a better experience with bindings generators,
possibly other tooling.

A possible risk is that some generators may not represent unknown
codes correctly.
Rust bindgen by default generates suitable code:
  * a type alias nix_err = c_int
  * individual constants for the known enum values
It does _not_ generate a closed type that can only hold the values
that were known at code generation time.

If this proves to be a problem, we could instead split the type:

`typedef int nix_err;` for return values
`enum nix_known_err` for code generation.

This would complicate the interface, so let's not do it unless it
is shown to be needed.
This commit is contained in:
Robert Hensing 2024-07-17 15:19:17 +02:00
parent 464e5925cb
commit 83d585b423

View file

@ -56,47 +56,51 @@ extern "C" {
* - NIX_ERR_KEY: A key error occurred (-3) * - NIX_ERR_KEY: A key error occurred (-3)
* - NIX_ERR_NIX_ERROR: A generic Nix error occurred (-4) * - NIX_ERR_NIX_ERROR: A generic Nix error occurred (-4)
*/ */
typedef int nix_err; enum nix_err {
/** /**
* @brief No error occurred. * @brief No error occurred.
* *
* This error code is returned when no error has occurred during the function * This error code is returned when no error has occurred during the function
* execution. * execution.
*/ */
#define NIX_OK 0 NIX_OK = 0,
/** /**
* @brief An unknown error occurred. * @brief An unknown error occurred.
* *
* This error code is returned when an unknown error occurred during the * This error code is returned when an unknown error occurred during the
* function execution. * function execution.
*/ */
#define NIX_ERR_UNKNOWN -1 NIX_ERR_UNKNOWN = -1,
/** /**
* @brief An overflow error occurred. * @brief An overflow error occurred.
* *
* This error code is returned when an overflow error occurred during the * This error code is returned when an overflow error occurred during the
* function execution. * function execution.
*/ */
#define NIX_ERR_OVERFLOW -2 NIX_ERR_OVERFLOW = -2,
/** /**
* @brief A key error occurred. * @brief A key error occurred.
* *
* This error code is returned when a key error occurred during the function * This error code is returned when a key error occurred during the function
* execution. * execution.
*/ */
#define NIX_ERR_KEY -3 NIX_ERR_KEY = -3,
/** /**
* @brief A generic Nix error occurred. * @brief A generic Nix error occurred.
* *
* This error code is returned when a generic Nix error occurred during the * This error code is returned when a generic Nix error occurred during the
* function execution. * function execution.
*/ */
#define NIX_ERR_NIX_ERROR -4 NIX_ERR_NIX_ERROR = -4,
};
typedef enum nix_err nix_err;
/** /**
* @brief This object stores error state. * @brief This object stores error state.