File: gpgme.info,  Node: Error Values,  Next: Error Sources,  Up: Error Handling

5.1 Error Values
================

 -- Data type: gpgme_err_code_t
     The ‘gpgme_err_code_t’ type is an alias for the ‘libgpg-error’ type
     ‘gpg_err_code_t’.  The error code indicates the type of an error,
     or the reason why an operation failed.

     A list of important error codes can be found in the next section.

 -- Data type: gpgme_err_source_t
     The ‘gpgme_err_source_t’ type is an alias for the ‘libgpg-error’
     type ‘gpg_err_source_t’.  The error source has not a precisely
     defined meaning.  Sometimes it is the place where the error
     happened, sometimes it is the place where an error was encoded into
     an error value.  Usually the error source will give an indication
     to where to look for the problem.  This is not always true, but it
     is attempted to achieve this goal.

     A list of important error sources can be found in the next section.

 -- Data type: gpgme_error_t
     The ‘gpgme_error_t’ type is an alias for the ‘libgpg-error’ type
     ‘gpg_error_t’.  An error value like this has always two components,
     an error code and an error source.  Both together form the error
     value.

     Thus, the error value can not be directly compared against an error
     code, but the accessor functions described below must be used.
     However, it is guaranteed that only 0 is used to indicate success
     (‘GPG_ERR_NO_ERROR’), and that in this case all other parts of the
     error value are set to 0, too.

     Note that in GPGME, the error source is used purely for
     diagnostical purposes.  Only the error code should be checked to
     test for a certain outcome of a function.  The manual only
     documents the error code part of an error value.  The error source
     is left unspecified and might be anything.

 -- Function: static inline gpgme_err_code_t gpgme_err_code
          (gpgme_error_t ERR)
     The static inline function ‘gpgme_err_code’ returns the
     ‘gpgme_err_code_t’ component of the error value ERR.  This function
     must be used to extract the error code from an error value in order
     to compare it with the ‘GPG_ERR_*’ error code macros.

 -- Function: static inline gpgme_err_source_t gpgme_err_source
          (gpgme_error_t ERR)
     The static inline function ‘gpgme_err_source’ returns the
     ‘gpgme_err_source_t’ component of the error value ERR.  This
     function must be used to extract the error source from an error
     value in order to compare it with the ‘GPG_ERR_SOURCE_*’ error
     source macros.

 -- Function: static inline gpgme_error_t gpgme_err_make
          (gpgme_err_source_t SOURCE, gpgme_err_code_t CODE)
     The static inline function ‘gpgme_err_make’ returns the error value
     consisting of the error source SOURCE and the error code CODE.

     This function can be used in callback functions to construct an
     error value to return it to the library.

 -- Function: static inline gpgme_error_t gpgme_error
          (gpgme_err_code_t CODE)
     The static inline function ‘gpgme_error’ returns the error value
     consisting of the default error source and the error code CODE.

     For GPGME applications, the default error source is
     ‘GPG_ERR_SOURCE_USER_1’.  You can define ‘GPGME_ERR_SOURCE_DEFAULT’
     before including ‘gpgme.h’ to change this default.

     This function can be used in callback functions to construct an
     error value to return it to the library.

   The ‘libgpg-error’ library provides error codes for all system error
numbers it knows about.  If ERR is an unknown error number, the error
code ‘GPG_ERR_UNKNOWN_ERRNO’ is used.  The following functions can be
used to construct error values from system errnor numbers.

 -- Function: gpgme_error_t gpgme_err_make_from_errno
          (gpgme_err_source_t SOURCE, int ERR)
     The function ‘gpgme_err_make_from_errno’ is like ‘gpgme_err_make’,
     but it takes a system error like ‘errno’ instead of a
     ‘gpgme_err_code_t’ error code.

 -- Function: gpgme_error_t gpgme_error_from_errno (int ERR)
     The function ‘gpgme_error_from_errno’ is like ‘gpgme_error’, but it
     takes a system error like ‘errno’ instead of a ‘gpgme_err_code_t’
     error code.

   Sometimes you might want to map system error numbers to error codes
directly, or map an error code representing a system error back to the
system error number.  The following functions can be used to do that.

 -- Function: gpgme_err_code_t gpgme_err_code_from_errno (int ERR)
     The function ‘gpgme_err_code_from_errno’ returns the error code for
     the system error ERR.  If ERR is not a known system error, the
     function returns ‘GPG_ERR_UNKNOWN_ERRNO’.

 -- Function: int gpgme_err_code_to_errno (gpgme_err_code_t ERR)
     The function ‘gpgme_err_code_to_errno’ returns the system error for
     the error code ERR.  If ERR is not an error code representing a
     system error, or if this system error is not defined on this
     system, the function returns ‘0’.