The `GnuPG Made Easy' Reference Manual: Error Handling

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 4. Error Handling

Many functions in GPGME can return an error if they fail. For this reason, the application should always catch the error condition and take appropriate measures, for example by releasing the resources and passing the error up to the caller, or by displaying a descriptive message to the user and cancelling the operation.

Some error values do not indicate a system error or an error in the operation, but the result of an operation that failed properly. For example, if you try to decrypt a tempered message, the decryption will fail. Another error value actually means that the end of a data buffer or list has been reached. The following descriptions explain what each error message means in general. Some error values have specific meanings if returned by a specific function. Such cases are described in the documentation of those functions.

> 4.1 Error Values |  | A list of all error values used.
> 4.2 Error Strings |  | How to get a descriptive string from a value.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 4.1 Error Values

Data type: enum GpgmeError
  The `GpgmeError` type specifies the set of all error values that are used by GPGME. Possible values are:

  `GPGME_EOF`
    This value indicates the end of a list, buffer or file.

  `GPGME_No_Error`
    This value indicates success. The value of this error is `0`.

  `GPGME_General_Error`
    This value means that something went wrong, but either there is not enough information about the problem to return a more useful error value, or there is no separate error value for this type of problem.

  `GPGME_Out_Of_Core`
    This value means that an out-of-memory condition occurred.

  `GPGME_Invalid_Value`
    This value means that some user provided data was out of range. This can also refer to objects. For example, if an empty `GpgmeData` object was expected, but one containing data was provided, this error value is returned.

  `GPGME_Busy`
    This value is returned if you try to start a new operation in a context that is already busy with some earlier operation which was not cancelled or finished yet.

  `GPGME_No_Request`
    This value is in some sense the opposite of `GPGME_Busy`. There is no pending operation, but it is required for the function to succeed.

  `GPGME_Exec_Error`
    This value means that an error occurred when trying to spawn a child process.

  `GPGME_Too_Many_Procs`
    This value means that there are too many active backend processes.

  `GPGME_Pipe_Error`
    This value means that the creation of a pipe failed.

  `GPGME_No_Recipients`
    This value means that no valid recipients for a message have been set.

  `GPGME_Invalid_Recipients`
    This value means that some, but not all, recipients for a message have been invalid.

  `GPGME_No_Data`
    This value means that a `GpgmeData` object which was expected to have content was found empty.

  `GPGME_Conflict`
    This value means that a conflict of some sort occurred.

  `GPGME_Not_Implemented`
    This value indicates that the specific function (or operation) is not implemented. This error should never happen. It can only occur if you use certain values or configuration options which do not work, but for which we think that they should work at some later time.

  `GPGME_Read_Error`
    This value means that an I/O read operation failed.

  `GPGME_Write_Error`
    This value means that an I/O write operation failed.

  `GPGME_Invalid_Type`
    This value means that a user provided object was of a wrong or incompatible type. Usually this refers to the type of a `GpgmeData` object.

  `GPGME_Invalid_Mode`
    This value means that a `GpgmeData` object has an incorrect mode of operation (for example, doesn't support output although it is attempted to use it as an output buffer).

  `GPGME_File_Error`
    This value means that a file I/O operation failed. The value of `errno` contains the system error value.

  `GPGME_Decryption_Failed`
    This value indicates that a decryption operation was unsuccessful.

  `GPGME_No_Passphrase`
    This value means that the user did not provide a passphrase when requested.

  `GPGME_Canceled`
    This value means that the operation was canceled.

  `GPGME_Invalid_Key`
    This value means that a key was invalid.

  `GPGME_Invalid_Engine`
    This value means that the engine that implements the desired protocol is currently not available. This can either be because the sources were configured to exclude support for this engine, or because the engine is not installed properly.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 4.2 Error Strings

Function: const char * gpgme_strerror (GpgmeError err)
  The function `gpgme_strerror` returns a pointer to a statically allocated string containing a description of the error with the error value err. This string can be used to output a diagnostic message to the user.

  The following example illustrates the use of `gpgme_strerror`:

      GpgmeCtx ctx;
      GpgmeError err = gpgme_new (&ctx);
      if (err)
        {
          fprintf (stderr, "%s: creating GpgME context failed: %s\n",
                   argv[0], gpgme_strerror (err));
          exit (1);
        }

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by John Goerzen on November, 21 2002 using texi2html