errors

## errors errors — Error handling. |

## Synopsis

    enum                pskc_rc;
    const char *        pskc_strerror                       (int err);
    const char *        pskc_strerror_name                  (int err);

## Description

Most library functions uses an int return value to indicate success or failure, using pskc_rc values. The values can be converted into human readable explanations using `pskc_strerror()`. The symbolic error codes can be converted into strings using `pskc_strerror_name()`.

## Details

### enum pskc_rc

    typedef enum {
      PSKC_OK = 0,
      PSKC_MALLOC_ERROR = -1,
      PSKC_XML_ERROR = -2,
      PSKC_PARSE_ERROR = -3,
      PSKC_BASE64_ERROR = -4,
      PSKC_UNKNOWN_OUTPUT_FORMAT = -5,
      PSKC_XMLSEC_ERROR = -6,
      /* When adding anything above, you need to update errors.c and
         the following constant. */
      PSKC_LAST_ERROR = -6
    } pskc_rc;

Return codes for PSKC functions. All return codes are negative except for the successful code `PSKC_OK` which are guaranteed to be 0. Positive values are reserved for non-error return codes.

Note that the pskc_rc enumeration may be extended at a later date to include new return codes.

`PSKC_OK` | Successful return.
`PSKC_MALLOC_ERROR` | Memory allocation failed.
`PSKC_XML_ERROR` | Error returned from XML library.
`PSKC_PARSE_ERROR` | Error parsing PSKC data.
`PSKC_BASE64_ERROR` | Error decoding base64 data.
`PSKC_UNKNOWN_OUTPUT_FORMAT` | Unknown output format.
`PSKC_XMLSEC_ERROR` | Error returned from XMLSec library.
`PSKC_LAST_ERROR` | Meta-error indicating the last error code, for use when iterating over all error codes or similar.

### pskc_strerror ()

    const char *        pskc_strerror                       (int err);

Convert return code to human readable string explanation of the reason for the particular error code.

This string can be used to output a diagnostic message to the user.

This function is one of few in the library that can be used without a successful call to `pskc_init()`.

`err` : | error code, a pskc_rc value.
Returns : | Returns a pointer to a statically allocated string containing an explanation of the error code `err`.

### pskc_strerror_name ()

    const char *        pskc_strerror_name                  (int err);

Convert return code to human readable string representing the error code symbol itself. For example, pskc_strerror_name(`PSKC_OK`) returns the string "PSKC_OK".

This string can be used to output a diagnostic message to the user.

This function is one of few in the library that can be used without a successful call to `pskc_init()`.

`err` : | error code, a pskc_rc value.
Returns : | Returns a pointer to a statically allocated string containing a string version of the error code `err`, or NULL if the error code is not known.