doc/
[gpgme.git] / doc / gpgme.texi
index 0b40f98..4edf9ed 100644 (file)
@@ -20,7 +20,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
 @value{VERSION}.
 
-Copyright @copyright{} 2002, 2003 g10 Code GmbH.
+Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -104,8 +104,11 @@ Preparation
 
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support (LFS)::       How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
+* Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
+* Signal Handling::               How @acronym{GPGME} affects signal handling.
 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
 
 Protocols and Engines
@@ -158,6 +161,7 @@ Context Attributes
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Locale::                        Setting the locale of a context.
 
 Key Management
 
@@ -197,6 +201,7 @@ Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 
 Using External Event Loops
 
@@ -317,8 +322,11 @@ of the library are verified.
 @menu
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support (LFS)::       How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
+* Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
+* Signal Handling::               How @acronym{GPGME} affects signal handling.
 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
 @end menu
 
@@ -341,10 +349,6 @@ The name space of @acronym{GPGME} is @code{gpgme_*} for function names
 and data types and @code{GPGME_*} for other symbols.  Symbols internal
 to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
 
-Because @acronym{GPGME} links to the Assuan library, linking to
-@acronym{GPGME} will also use the @code{assuan_*} and @code{_assuan_*}
-name space indirectly.
-
 Because @acronym{GPGME} makes use of the GPG Error library, using
 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
 directly, and the @code{gpg_err*} and @code{gpg_str*} name space
@@ -399,6 +403,88 @@ specifying both options to @command{gpgme-config}:
 gcc -o foo foo.c `gpgme-config --cflags --libs`
 @end example
 
+If you want to link to one of the thread-safe versions of
+@acronym{GPGME}, you must specify the @option{--thread} option before
+any other option to select the thread package you want to link with.
+Supported thread packages are @option{--thread=pth} and
+@option{--thread=pthread}.
+
+
+@node Largefile Support (LFS)
+@section Largefile Support (LFS)
+@cindex largefile support
+@cindex LFS
+
+@acronym{GPGME} is compiled with largefile support by default, if it
+is available on the system.  This means that GPGME supports files
+larger than two gigabyte in size, if the underlying operating system
+can.  On some systems, largefile support is already the default.  On
+such systems, nothing special is required.  However, some systems
+provide only support for files up to two gigabyte in size by default.
+Support for larger file sizes has to be specifically enabled.
+
+To make a difficult situation even more complex, such systems provide
+two different types of largefile support.  You can either get all
+relevant functions replaced with alternatives that are largefile
+capable, or you can get new functions and data types for largefile
+support added.  Those new functions have the same name as their
+smallfile counterparts, but with a suffix of 64.
+
+An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC
+systems.  To address offsets in large files, you can either enable
+largefile support add-on.  Then a new data type @code{off64_t} is
+provided, which is 64 bit wide.  Or you can replace the existing
+@code{off_t} data type with its 64 bit wide counterpart.  All
+occurences of @code{off_t} are then automagically replaced.
+
+As if matters were not complex enough, there are also two different
+types of file descriptors in such systems.  This is important because
+if file descriptors are exchanged between programs that use a
+different maximum file size, certain errors must be produced on some
+file descriptors to prevent subtle overflow bugs from occuring.
+
+As you can see, supporting two different maximum file sizes at the
+same time is not at all an easy task.  However, the maximum file size
+does matter for @acronym{GPGME}, because some data types it uses in
+its interfaces are affected by that.  For example, the @code{off_t}
+data type is used in the @code{gpgme_data_seek} function, to match its
+@acronym{POSIX} counterpart.  This affects the call-frame of the
+function, and thus the ABI of the library.  Furthermore, file
+descriptors can be exchanged between GPGME and the application.
+
+For you as the user of the library, this means that your program must
+be compiled in the same file size mode as the library.  Luckily, there
+is absolutely no valid reason for new programs to not enable largefile
+support by default and just use that.  The compatibility modes (small
+file sizes or dual mode) can be considered an historic artefact, only
+useful to allow for a transitional period.
+
+@acronym{GPGME} is compiled using largefile support by default.  This
+means that your application must do the same, at least as far as it is
+relevant for using the @file{gpgme.h} header file.  All types in this
+header files refer to their largefile counterparts, if they are
+different from any default types on the system.
+
+You can enable largefile support, if it is different from the default
+on the system the application is compiled on, by using the Autoconf
+macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
+worry about anything else: It will just work.  In this case you might
+also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
+interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+
+If you do not use Autoconf, you can define the preprocessor symbol
+@code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
+files, for example by specifying the option
+@code{-D_FILE_OFFSET_BITS=64} on the compiler command line.  You will
+also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to
+1 in this case, to take advantage of some new interfaces.
+
+If you do not want to do either of the above, you probably know enough
+about the issue to invent your own solution.  Just keep in mind that
+the @acronym{GPGME} header file expects that largefile support is
+enabled, if it is available.  In particular, we do not support dual
+mode (@code{_LARGEFILE64_SOURCE}).
+
 
 @node Using Automake
 @section Using Automake
@@ -415,6 +501,8 @@ provides an extension to Automake that does all the work for you.
 @r{[}@var{\varname\}@r{]}
 @end macro
 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
 Check whether @acronym{GPGME} (at least version @var{minimum-version},
 if given) exists on the host system.  If it is found, execute
 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
@@ -424,6 +512,14 @@ Additionally, the function defines @code{GPGME_CFLAGS} to the flags
 needed for compilation of the program to find the @file{gpgme.h}
 header file, and @code{GPGME_LIBS} to the linker flags needed to link
 the program to the @acronym{GPGME} library.
+
+@code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
+that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
+@code{GPGME_PTH_LIBS}.
+
+@code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
+that can be used with the native pthread implementation, and defines
+@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -435,6 +531,16 @@ LDADD = $(GPGME_LIBS)
 @end example
 
 
+@node Using Libtool
+@section Using Libtool
+@cindex libtool
+
+The easiest way is to just use GNU Libtool.  If you use libtool, and
+link to @code{libgpgme.la}, @code{libgpgme-pth.la} or
+@code{libgpgme-pthread.la} respectively, everything will be done
+automatically by Libtool.
+
+
 @node Library Version Check
 @section Library Version Check
 @cindex version check, of the library
@@ -468,6 +574,59 @@ features are provided by the installed version of the library.
 @end deftypefun
 
 
+After initializing @acronym{GPGME}, you should set the locale
+information to the locale required for your output terminal (only
+required if your program runs on a text terminal, rather than in the X
+Window environment).  Here is an example of a complete initialization:
+
+@example
+#include <locale.h>
+#include <gpgme.h>
+
+void
+init_program (void)
+@{
+  /* Initialize the locale environment.  */
+  setlocale (LC_ALL, "");
+  gpgme_check_version (NULL);
+  gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
+  gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
+@}
+@end example
+
+Note that you are highly recommended to initialize the locale settings
+like this.  @acronym{GPGME} can not do this for you because it would
+not be thread safe.
+
+
+@node Signal Handling
+@section Signal Handling
+@cindex signals
+@cindex signal handling
+
+The @acronym{GPGME} library communicates with child processes (the
+crypto engines).  If a child process dies unexpectedly, for example
+due to a bug, or system problem, a @code{SIGPIPE} signal will be
+delivered to the application.  The default action is to abort the
+program.  To protect against this, @code{gpgme_check_version} sets the
+@code{SIGPIPE} signal action to @code{SIG_IGN}, which means that the
+signal will be ignored.
+
+@acronym{GPGME} will only do that if the signal action for
+@code{SIGPIPE} is @code{SIG_DEF} at the time
+@code{gpgme_check_version} is called.  If it is something different,
+@code{GPGME} will take no action.
+
+This means that if your application does not install any signal
+handler for @code{SIGPIPE}, you don't need to take any precautions.
+If you do install a signal handler for @code{SIGPIPE}, you must be
+prepared to handle any @code{SIGPIPE} events that occur due to
+@acronym{GPGME} writing to a defunct pipe.  Furthermore, if your
+application is multi-threaded, and you install a signal action for
+@code{SIGPIPE}, you must make sure you do this either before
+@code{gpgme_check_version} is called or afterwards.
+
+
 @node Multi Threading
 @section Multi Threading
 @cindex thread-safeness
@@ -490,62 +649,28 @@ Support for other thread libraries is very easy to add.  Please
 contact us if you have the need.
 
 @item
-If you link your program dynamically to @acronym{GPGME} and your
-supported thread library, @acronym{GPGME} will automatically detect
-the presence of this library and activate its use.  You must link to
-the thread library before linking to @acronym{GPGME}.  If you link to
-both pthread and GNU Pth, @acronym{GPGME} will use the pthread
-support.  This feature requires weak symbol support.
+If you want to use @acronym{GPGME} with threads, you must link to the
+right version of the library.  The name of the right library is
+@code{libgpgme-} followed by the name of the thread package you use.
+For example, if you use GNU Pth, the right name is
+@code{libgpgme-pth}.  Use the Automake macros or
+@command{gpgme-config} program for simplicity.
 
-@item
-If you link your program statically to @acronym{GPGME}, or your system
-does not support weak symbols, there is currently no easy way to make
-sure that @acronym{GPGME} detects the presence of the thread library.
-This will be solved in a future version.
 
 @item
 The function @code{gpgme_check_version} must be called before any
 other function in the library, because it initializes the thread
-support subsystem in @acronym{GPGME}.  To achieve this in all
-generality, it is necessary to synchronize the call to this function
-with all other calls to functions in the library, using the
-synchronization mechanisms available in your thread library.
-Otherwise, specific compiler or CPU memory cache optimizations could
-lead to the situation where a thread is started and uses
-@acronym{GPGME} before the effects of the initialization are visible
-for this thread.  It doesn't even suffice to call
-@code{gpgme_check_version} before creating this other
-thread@footnote{In SMP systems the new thread could be started on
-another CPU before the effects of the initialization are seen by that
-CPU's memory cache.  Not doing proper synchronization here leads to
-the same problems the double-checked locking idiom has.  You might
-find that if you don't do proper synchronization, it still works in
-most configurations.  Don't let this fool you.  Someday it might lead
-to subtle bugs when someone tries it on a DEC Alpha or an SMP
-machine.}.
-
-For example, if you are using POSIX threads, each thread that wants to
-call functions in @acronym{GPGME} could call the following function
-before any function in the library:
-
-@example
-#include <pthread.h>
-
-void
-initialize_gpgme (void)
-@{
-  static int gpgme_init;
-  static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;
-
-  pthread_mutex_lock (&gpgme_init_lock);
-  if (!gpgme_init)
-    @{
-      gpgme_check_version ();
-      gpgme_init = 1;
-    @}
-  pthread_mutex_unlock (&gpgme_init_lock);
-@}
-@end example
+support subsystem in @acronym{GPGME}.  To achieve this in
+multi-threaded programs, you must synchronize the memory with respect
+to other threads that also want to use @acronym{GPGME}.  For this, it
+is sufficient to call @code{gpgme_check_version} before creating the
+other threads using @acronym{GPGME}@footnote{At least this is true for
+POSIX threads, as @code{pthread_create} is a function that
+synchronizes memory with respects to other threads.  There are many
+functions which have this property, a complete list can be found in
+POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
+definition of the term ``Memory Synchronization''.  For other thread
+packages other, more relaxed or more strict rules may apply.}.
 
 @item
 Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be
@@ -558,6 +683,10 @@ Only one thread at any time is allowed to call @code{gpgme_wait}.  If
 multiple threads call this function, the caller must make sure that
 all invocations are fully synchronized.  It is safe to start
 asynchronous operations while a thread is running in gpgme_wait.
+
+@item
+The function @code{gpgme_strerror} is not thread safe.  You have to
+use @code{gpgme_strerror_r} instead.
 @end itemize
 
 
@@ -927,21 +1056,21 @@ error code part of an error value.  The error source is left
 unspecified and might be anything.
 @end deftp
 
-@deftypefun {static __inline__ gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
+@deftypefun {static inline gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
 The static inline function @code{gpgme_err_code} returns the
 @code{gpgme_err_code_t} component of the error value @var{err}.  This
 function must be used to extract the error code from an error value in
 order to compare it with the @code{GPG_ERR_*} error code macros.
 @end deftypefun
 
-@deftypefun {static __inline__ gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
+@deftypefun {static inline gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
 The static inline function @code{gpgme_err_source} returns the
 @code{gpgme_err_source_t} component of the error value @var{err}.  This
 function must be used to extract the error source from an error value in
 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
 @end deftypefun
 
-@deftypefun {static __inline__ gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
+@deftypefun {static inline gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
 The static inline function @code{gpgme_err_make} returns the error
 value consisting of the error source @var{source} and the error code
 @var{code}.
@@ -950,7 +1079,7 @@ This function can be used in callback functions to construct an error
 value to return it to the library.
 @end deftypefun
 
-@deftypefun {static __inline__ gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
+@deftypefun {static inline gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
 The static inline function @code{gpgme_error} returns the error value
 consisting of the default error source and the error code @var{code}.
 
@@ -1030,7 +1159,7 @@ OpenPGP protocol.
 
 @item GPG_ERR_SOURCE_GPGSM
 The error source is GPGSM, which is the crypto engine used for the
-OpenPGP protocol.
+CMS protocol.
 
 @item GPG_ERR_SOURCE_GCRYPT
 The error source is @code{libgcrypt}, which is used by crypto engines
@@ -1144,7 +1273,8 @@ were configured to exclude support for this engine, or because the
 engine is not installed properly.
 
 @item GPG_ERR_AMBIGUOUS_NAME
-This value indicates that a user ID did not specify a unique key.
+This value indicates that a user ID or other specifier did not specify
+a unique key.
 
 @item GPG_ERR_WRONG_KEY_USAGE
 This value indicates that a key is not used appropriately.
@@ -1208,6 +1338,18 @@ The function @code{gpgme_strerror} returns a pointer to a statically
 allocated string containing a description of the error code contained
 in the error value @var{err}.  This string can be used to output a
 diagnostic message to the user.
+
+This function is not thread safe.  Use @code{gpgme_strerror_r} in
+multi-threaded programs.
+@end deftypefun
+
+
+@deftypefun {char *} gpgme_strerror_r (@w{gpgme_error_t @var{err}})
+The function @code{gpgme_strerror_r} returns a pointer to a
+dynamically allocated string containing a description of the error
+code contained in the error value @var{err}.  This string can be used
+to output a diagnostic message to the user.  When it is not needed
+anymore, the user must deallocate it with @code{free}.
 @end deftypefun
 
 
@@ -1532,8 +1674,7 @@ from the data object with the handle @var{dh} into the space starting
 at @var{buffer}.
 
 If no error occurs, the actual amount read is returned.  If the end of
-the data object is reached, the function returns @code{GPG_ERR_EOF} and
-sets @var{nread} to zero.
+the data object is reached, the function returns 0.
 
 In all other cases, the function returns -1 and sets @var{errno}.
 @end deftypefun
@@ -1701,6 +1842,7 @@ The function @code{gpgme_release} destroys the context with the handle
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Locale::                        Setting the locale of a context.
 @end menu
 
 
@@ -1834,7 +1976,7 @@ is the default.
 
 @item GPGME_KEYLIST_MODE_EXTERN
 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
-source should be should be searched for keys in the keylisting
+source should be searched for keys in the keylisting
 operation.  The type of external source is dependant on the crypto
 engine used.  For example, it can be a remote keyserver or LDAP
 certificate server.
@@ -1842,6 +1984,14 @@ certificate server.
 @item GPGME_KEYLIST_MODE_SIGS
 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
 signatures should be included in the listed keys.
+
+@item GPGME_KEYLIST_MODE_VALIDATE
+The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
+backend should do key or certificate validation and not just get the
+validity information from an interna cache.  This might be an
+expensive operation and is in general not usefule.  Currently only
+implemented for the S/MIME backend and ignored for other backends.
+
 @end table
 
 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
@@ -1978,6 +2128,43 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Locale
+@subsection Locale
+@cindex locale, default
+@cindex locale, of a context
+
+A locale setting can be associated with a context.  This locale is
+passed to the crypto engine, and used for applications like the PIN
+entry, which is displayed to the user when entering a passphrase is
+required.
+
+The default locale is used to initialize the locale setting of all
+contexts created afterwards.
+
+@deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
+The function @code{gpgme_set_locale} sets the locale of the context
+@var{ctx}, or the default locale if @var{ctx} is a null pointer.
+
+The locale settings that should be changed are specified by
+@var{category}.  Supported categories are @code{LC_CTYPE},
+@code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
+if you want to change all the categories at once.
+
+The value to be used for the locale setting is @var{value}, which will
+be copied to @acronym{GPGME}'s internal data structures.  @var{value}
+can be a null pointer, which disables setting the locale, and will
+make PIN entry and other applications use their default setting, which
+is usually not what you want.
+
+Note that the settings are only used if the application runs on a text
+terminal, and that the settings should fit the configuration of the
+output terminal.  Normally, it is sufficient to initialize the default
+value at startup.
+
+The function returns an error if not enough memory is available.
+@end deftypefun
+
+
 @node Key Management
 @section Key Management
 @cindex key management
@@ -2023,6 +2210,9 @@ This is true if the subkey can be used to create data signatures.
 @item unsigned int can_certify : 1
 This is true if the subkey can be used to create key certificates.
 
+@item unsigned int can_authenticate : 1
+This is true if the subkey can be used for authentication.
+
 @item unsigned int secret : 1
 This is true if the subkey is a secret key.
 
@@ -2074,7 +2264,7 @@ This is true if the key signature is expired.
 @item unsigned int invalid : 1
 This is true if the key signature is invalid.
 
-@item unsigned int disabled : 1
+@item unsigned int exportable : 1
 This is true if the key signature is exportable.
 
 @item gpgme_pubkey_algo_t pubkey_algo
@@ -2096,7 +2286,7 @@ signature does not expire.
 This is the status of the signature and has the same meaning as the
 member of the same name in a @code{gpgme_signature_t} object.
 
-@item unsigned int class
+@item unsigned int sig_class
 This specifies the signature class of the key signature.  The meaning
 is specific to the crypto engine.
 
@@ -2167,7 +2357,10 @@ This is true if the key is expired.
 This is true if the key is disabled.
 
 @item unsigned int invalid : 1
-This is true if the key is invalid.
+This is true if the key is invalid. This might have several reasons,
+for a example for the S/MIME backend, it will be set in during key
+listsing if the key could not be validated due to a missing
+certificates or unmatched policies.
 
 @item unsigned int can_encrypt : 1
 This is true if the key (ie one of its subkeys) can be used for
@@ -2181,6 +2374,10 @@ data signatures.
 This is true if the key (ie one of its subkeys) can be used to create
 key certificates.
 
+@item unsigned int can_authenticate : 1
+This is true if the key (ie one of its subkeys) can be used for
+authentication.
+
 @item unsigned int secret : 1
 This is true if the key is a secret key.
 
@@ -2326,10 +2523,7 @@ if (!err)
         err = gpgme_op_keylist_next (ctx, &key);
         if (err)
           break;
-        printf ("%s: %s <%s>\n",
-                gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
-               gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
-               gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
+        printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
         gpgme_key_release (key);
       @}
     gpgme_release (ctx);
@@ -2372,10 +2566,9 @@ following function can be used to retrieve a single key.
 @deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}})
 The function @code{gpgme_get_key} gets the key with the fingerprint
 (or key ID) @var{fpr} from the crypto backend and return it in
-@var{r_key}.  If @var{force_update} is true, force a refresh of the
-key from the crypto backend and replace the key in the cache, if any.
-If @var{secret} is true, get the secret key.  The currently active
-keylist mode is used to retrieve the key.
+@var{r_key}.  If @var{secret} is true, get the secret key.  The
+currently active keylist mode is used to retrieve the key.  The key
+will have one reference for the user.
 
 If the key is not found in the keyring, @code{gpgme_get_key} returns
 the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
@@ -2383,8 +2576,9 @@ the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
 
 The function returns the error code @code{GPG_ERR_INV_VALUE} if
 @var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
-fingerprint or key ID, and @code{GPG_ERR_ENOMEM} if at some time
-during the operation there was not enough memory available.
+fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
+not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
+time during the operation there was not enough memory available.
 @end deftypefun
 
 
@@ -3330,12 +3524,13 @@ algorithm that is not supported.
 
 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_decrypt_result} returns a
-@code{gpgme_decrypt_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_decrypt} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_decrypt} or
-@code{gpgme_op_decrypt_start} operation, and if this operation
-finished successfully.  The returned pointer is only valid until the
-next operation is started on the context.
+@code{gpgme_decrypt_result_t} pointer to a structure holding the
+result of a @code{gpgme_op_decrypt} operation.  The pointer is only
+valid if the last operation on the context was a
+@code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
+If the operation failed this might be a @code{NULL} pointer.  The
+returned pointer is only valid until the next operation is started on
+the context.
 @end deftypefun
 
 
@@ -3361,10 +3556,10 @@ with @code{gpgme_op_verify_result}.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx}, @var{sig}, @var{plain} or @var{r_stat} is not a valid
-pointer, @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data
-to verify, and passes through any errors that are reported by the
-crypto engine support routines.
+@var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
+verify, and passes through any errors that are reported by the crypto
+engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
@@ -3374,9 +3569,9 @@ The function @code{gpgme_op_verify_start} initiates a
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
-@var{ctx}, @var{sig}, @var{plain} or @var{r_stat} is not a valid
-pointer, and @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does
-not contain any data to verify.
+@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
+@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
+any data to verify.
 @end deftypefun
 
 @deftp {Data type} {gpgme_sig_notation_t}
@@ -3425,8 +3620,8 @@ The defined bits are:
   information.  Check the other bits.
 
   @item GPGME_SIGSUM_RED
-  The signature is bad. It might be useful to checkother bits and
-  display moe information, i.e. a revoked certificate might not render a
+  The signature is bad. It might be useful to check other bits and
+  display more information, i.e. a revoked certificate might not render a
   signature invalid when the message was received prior to the cause for
   the revocation.
 
@@ -3441,7 +3636,7 @@ The defined bits are:
   The signature has expired.
 
   @item GPGME_SIGSUM_KEY_MISSING
-  Can't verifydue to a missing key o certificate.
+  Can't verify due to a missing key or certificate.
 
   @item GPGME_SIGSUM_CRL_MISSING
   The CRL (or an equivalent mechanism) is not available. 
@@ -3503,19 +3698,23 @@ The expiration timestamp of this signature, or 0 if the signature does
 not expire.
 
 @item int wrong_key_usage : 1;
+This is true if the key was not used according to its policy.
 
 @item gpgme_validity_t validity
+The validity of the signature.
 
 @item gpgme_error_t validity_reason
+If a signature is not valid, this provides a reason why.
+
 @end table
 @end deftp
 
 @deftp {Data type} {gpgme_verify_result_t}
 This is a pointer to a structure used to store the result of a
-@code{gpgme_op_verify} operation.  After successfully verifying a
-signature, you can retrieve the pointer to the result with
-@code{gpgme_op_verify_result}.  The structure contains the following
-member:
+@code{gpgme_op_verify} operation.  After verifying a signature, you
+can retrieve the pointer to the result with
+@code{gpgme_op_verify_result}.  If the operation failed this might be
+a @code{NULL} pointer.  The structure contains the following member:
 
 @table @code
 @item gpgme_signature_t signatures
@@ -3607,7 +3806,7 @@ The function @code{gpgme_get_sig_status} is equivalent to:
 
   if (r_stat)
     @{
-      switch (sig->status)
+      switch (gpg_err_code (sig->status))
        @{
        case GPG_ERR_NO_ERROR:
          *r_stat = GPGME_SIG_STAT_GOOD;
@@ -3780,18 +3979,18 @@ the data object @var{cipher} and stores it into the data object
 @var{plain}.  If @var{cipher} contains signatures, they will be
 verified.
 
-After the operation completed, @code{gpgme_op_get_sig_status} and
-@code{gpgme_op_get_sig_key} can be used to retrieve more information
+After the operation completed, @code{gpgme_op_decrypt_result} and
+@code{gpgme_op_verify_result} can be used to retrieve more information
 about the signatures.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
-if @var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
-pointer, @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any
-data to decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not
-a valid cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
-for the secret key could not be retrieved, and passes through any
-errors that are reported by the crypto engine support routines.
+if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
+decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
+cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
+secret key could not be retrieved, and passes through any errors that
+are reported by the crypto engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
@@ -3895,8 +4094,9 @@ signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
 @var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
 @code{GPG_ERR_NO_DATA} if the signature could not be created,
 @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
-could not be retrieved, and passes through any errors that are
-reported by the crypto engine support routines.
+could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are
+invalid signers, and passes through any errors that are reported by the
+crypto engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
@@ -3928,7 +4128,7 @@ The public key algorithm used to create this signature.
 @item gpgme_hash_algo_t
 The hash algorithm used to create this signature.
 
-@item unsigned long class
+@item unsigned int sig_class
 The signature class of this signature.
 
 @item long int timestamp
@@ -3958,12 +4158,14 @@ A linked list with information about all signatures created.
 
 @deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_sign_result} returns a
-@code{gpgme_sign_result_t} pointer to a structure holding the result of a
-@code{gpgme_op_sign} operation.  The pointer is only valid if the last
-operation on the context was a @code{gpgme_op_sign} or
-@code{gpgme_op_sign_start} operation, and if this operation finished
-successfully.  The returned pointer is only valid until the next
-operation is started on the context.
+@code{gpgme_sign_result_t} pointer to a structure holding the result
+of a @code{gpgme_op_sign} operation.  The pointer is only valid if the
+last operation on the context was a @code{gpgme_op_sign},
+@code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or
+@code{gpgme_op_encrypt_sign_start} operation.  If that operation
+failed, the function might return a @code{NULL} pointer, The returned
+pointer is only valid until the next operation is started on the
+context.
 @end deftypefun
 
 
@@ -4026,7 +4228,7 @@ ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if
 @var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid
 pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some
 invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
-for the secret key could not be retrieved, and passes through any
+for the symmetric key could not be retrieved, and passes through any
 errors that are reported by the crypto engine support routines.
 @end deftypefun
 
@@ -4062,12 +4264,14 @@ the data could not be encrypted.
 
 @deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_encrypt_result} returns a
-@code{gpgme_encrypt_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_encrypt} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_encrypt} or
-@code{gpgme_op_encrypt_start} operation, and if this operation
-finished successfully.  The returned pointer is only valid until the
-next operation is started on the context.
+@code{gpgme_encrypt_result_t} pointer to a structure holding the
+result of a @code{gpgme_op_encrypt} operation.  The pointer is only
+valid if the last operation on the context was a
+@code{gpgme_op_encrypt}, @code{gpgme_op_encrypt_start},
+@code{gpgme_op_sign} or @code{gpgme_op_sign_start} operation.  If this
+operation failed, this might be a @code{NULL} pointer.  The returned
+pointer is only valid until the next operation is started on the
+context.
 @end deftypefun
 
 
@@ -4112,6 +4316,7 @@ time.
 @menu
 * Waiting For Completion::        Waiting until an operation is completed.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 @end menu
 
 
@@ -4695,6 +4900,43 @@ my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
 @end example
 
 
+@node Cancellation
+@subsection Cancellation
+@cindex cryptographic operation, aborting
+@cindex cryptographic operation, cancelling
+@cindex aborting operations
+@cindex cancelling operations
+
+Sometimes you do not want to wait for an operation to finish.  If you
+use external I/O callbacks, you can cancel a pending operation.
+However, you must ensure that no other thread is currently using the
+context in which the operation you want to cancel runs.  This includes
+callback handlers.  So your external event loop must either be halted
+or otherwise it must be guaranteed that no installed I/O callbacks are
+run for this context.
+
+@deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}.  This only works if you use the
+global event loop or your own event loop.
+
+If you use the global event loop, you must not call @code{gpgme_wait}
+or @code{gpgme_wait} during cancellation.  After successful
+cancellation, you can call @code{gpgme_wait} (optionally waiting on
+@var{ctx}), and the context @var{ctx} will appear as if it had
+finished with the error code @code{GPG_ERR_CANCEL}.
+
+If you use your an external event loop, you must ensure that no I/O
+callbacks are invoked for this context (for example by halting the
+event loop).  On successful cancellation, all registered I/O callbacks
+for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
+event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
+
+
 @include gpl.texi