src/error.h

   1 #ifndef LBX_ERROR_H_
   2 #define LBX_ERROR_H_
   3
   4 enum {
   5         LBX_EOK,
   6         LBX_EMAGIC,
   7         LBX_EFORMAT,
   8         LBX_EINVAL,
   9         LBX_ENOMEM,
  10         LBX_EEOF,
  11         LBX_EMAX,
  12
  13         LBX_EUBASE = 9000
  14 };
  15
  16 /*
  17  * Create a new user error.  User errors are primarily intended to be used by
  18  * lbx_file_ops callback functions, but can be used for any purpose.
  19  *
  20  * Returns a positive code on success (which can be subsequently passed to
  21  * lbx_error_raise), or a negative value on failure.
  22  */
  23 int lbx_error_new(const char *str);
  24
  25 /*
  26  * Signal an error.  The given code is recorded for later retreival by
  27  * lbx_error_get.  Errors are reported on a first-in, first-out basis.
  28  * Errors are stored in a ring buffer which can overflow, at which point
  29  * the oldest unretrieved error will be deleted.
  30  *
  31  * Negative codes represent system errors.  That is, the negation of some
  32  * (positive) errno value as returned by a library function.  If a positive
  33  * code does not correspond to any error, nothing is recorded.
  34  *
  35  * Returns -1 if the error code was not valid, or if an unretreived code
  36  * was deleted.  Otherwise, this function returns 0.
  37  */
  38 int lbx_error_raise(int code);
  39
  40 /*
  41  * Retrieves an error.  The oldest reported error is removed from the buffer.
  42  * If msg is not NULL, a pointer to a human-readable description of the error
  43  * is stored in *msg.
  44  *
  45  * Returns the retrieved error code, or 0 if there were no errors.
  46  */
  47 int lbx_error_get(const char **msg);
  48
  49 /*
  50  * Retrieves an error.  This function is the same as lbx_error_get, except that
  51  * the error code is not removed from the buffer and will be reported by a
  52  * subsequent call to lbx_error_get or lbx_error_peek.
  53  */
  54 int lbx_error_peek(const char **msg);
  55
  56 /*
  57  * Helper function for when you only care about the message.
  58  */
  59 static inline const char *lbx_errmsg(void)
  60 {
  61         const char *msg;
  62
  63         lbx_error_get(&msg);
  64         return msg;
  65 }
  66
  67 #endif