Adjust configure.ac for modern autoconf.
[gpgme.git] / doc / gpgme.texi
index 1fc4849..72b9e22 100644 (file)
@@ -1,4 +1,5 @@
-\input texinfo                  @c -*- Texinfo -*-
+\input texinfo                   @c -*- mode: texinfo; coding: latin-1; -*-
+@documentencoding ISO-8859-1
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -7,12 +8,42 @@
 * @acronym{GPGME}: (gpgme).          Adding support for cryptography to your program.
 @end direntry
 
-@include version.texi
-
 @c Unify some of the indices.
 @syncodeindex tp fn
 @syncodeindex pg fn
 
+@copying
+Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
+2008, 2010 g10 Code GmbH.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version. The text of the license can be found in the
+section entitled ``Copying''.
+@end quotation
+
+This document is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+@end copying
+
+@include version.texi
+
+@c Macros used by the description of the UI server protocol
+@macro clnt
+  @sc{c:} @c
+@end macro
+@macro srvr
+  @sc{s:} @c
+@end macro
+
+
+@c 
+@c  T I T L E  P A G E
+@c
 @ifinfo
 This file documents the @acronym{GPGME} library.
 
@@ -21,27 +52,14 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @value{VERSION}.
 
 @c NOTE: Don't forget to update the year for the TeX version, too.
-Copyright @copyright{} 2002, 2003, 2004, 2005 g10 Code GmbH.
-
-The GPGME reference manual is free software; you can redistribute it
-and/or modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either version
-2.1 of the License, or (at your option) any later version.
-
-The GPGME reference manual is distributed in the hope that it will be
-useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public
-License along with this program; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+@insertcopying
 
 @end ifinfo
 
-@iftex
-@shorttitlepage The `GnuPG Made Easy' Reference Manual
-@end iftex
+@c We do not want that bastard short titlepage.
+@c @iftex
+@c @shorttitlepage The `GnuPG Made Easy' Reference Manual
+@c @end iftex
 @titlepage
 @center @titlefont{The `GnuPG Made Easy'}
 @sp 1
@@ -54,25 +72,15 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2002, 2003, 2004, 2005 g10 Code GmbH.
-
-
-The GPGME reference manual is free software; you can redistribute it
-and/or modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either version
-2.1 of the License, or (at your option) any later version.
-
-The GPGME reference manual is distributed in the hope that it will be
-useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-Lesser General Public License for more details.
+Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
-You should have received a copy of the GNU Lesser General Public
-License along with this program; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+@insertcopying
 @end titlepage
 @page
 
+@summarycontents
+@contents
+
 @ifnottex
 @node Top
 @top Main Menu
@@ -92,8 +100,12 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 
 Appendices
 
+* UI Server Protocol::            The GnuPG UI Server Protocol.
+
 * Library Copying::               The GNU Lesser General Public License says
                                   how you can copy and share `GnuPG Made Easy'.
+* Copying::                       The GNU General Public License says how you
+                                  can copy and share this manual.
 
 Indices
 
@@ -162,6 +174,7 @@ Contexts
 
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
@@ -190,6 +203,7 @@ Key Management
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
 
@@ -565,13 +579,17 @@ automatically by Libtool.
 @cindex version check, of the library
 
 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
-The function @code{gpgme_check_version} has three purposes.  It can be
+The function @code{gpgme_check_version} has four purposes.  It can be
 used to retrieve the version number of the library.  In addition it
 can verify that the version number is higher than a certain required
 version number.  In either case, the function initializes some
 sub-systems, and for this reason alone it must be invoked early in
 your program, before you make use of the other functions in
-@acronym{GPGME}.
+@acronym{GPGME}.  The last purpose is to run selftests.
+
+As a side effect for W32 based systems, the socket layer will get
+initialized.
+
 
 If @var{required_version} is @code{NULL}, the function returns a
 pointer to a statically allocated string containing the version number
@@ -590,6 +608,11 @@ If you use a version of a library that is backwards compatible with
 older releases, but contains additional interfaces which your program
 uses, this function provides a run-time check if the necessary
 features are provided by the installed version of the library.
+
+If a selftest fails, the function may still succeed.  Selftest errors
+are returned later when invoking @code{gpgme_new}, so that a detailed
+error code can be returned (historically, @code{gpgme_check_version}
+does not return a detailed error code).
 @end deftypefun
 
 
@@ -603,19 +626,22 @@ pinentry.  Here is an example of a complete initialization:
 #include <gpgme.h>
 
 void
-init_program (void)
+init_gpgme (void)
 @{
   /* Initialize the locale environment.  */
   setlocale (LC_ALL, "");
   gpgme_check_version (NULL);
   gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
+#ifdef LC_MESSAGES
   gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
+#endif
 @}
 @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.
+not be thread safe.  The conditional on LC_MESSAGES is only necessary
+for portability to W32 systems.
 
 
 @node Signal Handling
@@ -740,6 +766,21 @@ This specifies the OpenPGP protocol.
 
 @item GPGME_PROTOCOL_CMS
 This specifies the Cryptographic Message Syntax.
+
+@item GPGME_PROTOCOL_ASSUAN
+Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
+
+@item GPGME_PROTOCOL_G13
+Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
+
+@item GPGME_PROTOCOL_UISERVER
+Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
+
+@item GPGME_PROTOCOL_UNKNOWN
+Reserved for future extension.  You may use this to indicate that the
+used protocol is not known to the application.  Currently,
+@acronym{GPGME} does not accept this value in any operation, though,
+except for @code{gpgme_get_protocol_name}.
 @end table
 @end deftp
 
@@ -849,12 +890,12 @@ if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
         if (!info)
           fprintf (stderr, "GPGME compiled without support for protocol %s",
                    gpgme_get_protocol_name (info->protocol));
-        else if (info->path && !info->version)
+        else if (info->file_name && !info->version)
           fprintf (stderr, "Engine %s not installed properly",
-                   info->path);
-        else if (info->path && info->version && info->req_version)
+                   info->file_name);
+        else if (info->file_name && info->version && info->req_version)
           fprintf (stderr, "Engine %s version %s installed, "
-                   "but at least version %s required", info->path,
+                   "but at least version %s required", info->file_name,
                    info->version, info->req_version);
         else
           fprintf (stderr, "Unknown problem with engine for protocol %s",
@@ -929,8 +970,10 @@ The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
 @cindex algorithms
 
 The crypto backends support a variety of algorithms used in public key
-cryptography.  The following sections list the identifiers used to
-denote such an algorithm.
+cryptography.@footnote{Some engines also provide symmetric only
+encryption; see the description of the encryption function on how to use
+this.}  The following sections list the identifiers used to denote such
+an algorithm.
 
 @menu
 * Public Key Algorithms::         A list of all public key algorithms.
@@ -972,6 +1015,18 @@ This value indicates ElGamal.
 
 @item GPGME_PK_ELG_E
 This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ELG_E
+This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ECDSA
+This value indicates ECDSA, the Elliptic Curve Digital Signature
+Algorithm as defined by FIPS 186-2.
+
+@item GPGME_PK_ECDH
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption
+algorithm as defined by the ECC in OpenPGP draft.
+
 @end table
 @end deftp
 
@@ -1400,12 +1455,15 @@ 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}.
+@deftypefun {int} gpgme_strerror_r (@w{gpgme_error_t @var{err}}, @w{char *@var{buf}}, @w{size_t @var{buflen}})
+The function @code{gpgme_strerror_r} returns the error string for
+@var{err} in the user-supplied buffer @var{buf} of size @var{buflen}.
+This function is, in contrast to @code{gpgme_strerror}, thread-safe if
+a thread-safe @code{strerror_r} function is provided by the system.
+If the function succeeds, 0 is returned and @var{buf} contains the
+string describing the error.  If the buffer was not large enough,
+ERANGE is returned and @var{buf} contains as much of the beginning of
+the error string as fits into the buffer.
 @end deftypefun
 
 
@@ -1447,6 +1505,14 @@ The @code{gpgme_data_t} type is a handle for a container for generic
 data, which is used by @acronym{GPGME} to exchange data with the user.
 @end deftp
 
+@code{gpgme_data_t} objects do not provide notifications on events.
+It is assumed that read and write operations are blocking until data
+is available.  If this is undesirable, the application must ensure
+that all GPGME data operations always have data available, for example
+by using memory buffers or files rather than pipes or sockets.  This
+might be relevant, for example, if the external event loop mechanism
+is used.
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -1558,6 +1624,10 @@ When using the data object as an input buffer, the function might read
 a bit more from the file descriptor than is actually needed by the
 crypto engine in the desired operation because of internal buffering.
 
+Note that GPGME assumes that the file descriptor is set to blocking
+mode.  Errors during I/O operations, except for EINTR, are usually
+fatal for crypto operations.
+
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
 enough memory is available.
@@ -1573,6 +1643,10 @@ When using the data object as an input buffer, the function might read
 a bit more from the stream than is actually needed by the crypto
 engine in the desired operation because of internal buffering.
 
+Note that GPGME assumes that the stream is in blocking mode.  Errors
+during I/O operations, except for EINTR, are usually fatal for crypto
+operations.
+
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
 enough memory is available.
@@ -1594,6 +1668,10 @@ data object.  The function should read up to @var{size} bytes from the
 current read position into the space starting at @var{buffer}.  The
 @var{handle} is provided by the user at data object creation time.
 
+Note that GPGME assumes that the read blocks until data is available.
+Errors during I/O operations, except for EINTR, are usually fatal for
+crypto operations.
+
 The function should return the number of bytes read, 0 on EOF, and -1
 on error.  If an error occurs, @var{errno} should be set to describe
 the type of the error.
@@ -1607,6 +1685,10 @@ data object.  The function should write up to @var{size} bytes to the
 current write position from the space starting at @var{buffer}.  The
 @var{handle} is provided by the user at data object creation time.
 
+Note that GPGME assumes that the write blocks until data is available.
+Errors during I/O operations, except for EINTR, are usually fatal for
+crypto operations.
+
 The function should return the number of bytes written, and -1 on
 error.  If an error occurs, @var{errno} should be set to describe the
 type of the error.
@@ -1716,7 +1798,8 @@ the user provided the data buffer in non-copy mode, a copy will be
 made for this purpose.
 
 In case an error returns, or there is no suitable data buffer that can
-be returned to the user, the function will return @code{NULL}.
+be returned to the user, the function will return @code{NULL}.  In any
+case, the data object @var{dh} is destroyed.
 @end deftypefun
 
 
@@ -1769,7 +1852,7 @@ The function returns the number of bytes actually written, or -1 if an
 error occurs.  If an error occurs, @var{errno} is set.
 @end deftypefun
 
-@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t *@var{offset}}, @w{int @var{whence}})
+@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t @var{offset}}, @w{int @var{whence}})
 The function @code{gpgme_data_seek} changes the current read/write
 position.
 
@@ -1778,15 +1861,15 @@ interpreted.  It must be one of the following symbolic constants:
 
 @table @code
 @item SEEK_SET
-Specifies that @var{whence} is a count of characters from the
+Specifies that @var{offset} is a count of characters from the
 beginning of the data object.
 
 @item SEEK_CUR
-Specifies that @var{whence} is a count of characters from the current
+Specifies that @var{offset} is a count of characters from the current
 file position.  This count may be positive or negative.
 
 @item SEEK_END
-Specifies that @var{whence} is a count of characters from the end of
+Specifies that @var{offset} is a count of characters from the end of
 the data object.  A negative count specifies a position within the
 current extent of the data object; a positive count specifies a
 position past the current end.  If you set the position past the
@@ -1850,8 +1933,11 @@ enough memory is available.
 @deftp {Data type} {enum gpgme_data_encoding_t}
 @tindex gpgme_data_encoding_t
 The @code{gpgme_data_encoding_t} type specifies the encoding of a
-@code{gpgme_data_t} object.  This encoding is useful to give the backend
-a hint on the type of data.  The following data types are available:
+@code{gpgme_data_t} object.  For input data objects, the encoding is
+useful to give the backend a hint on the type of data.  For output
+data objects, the encoding can specify the output data format on
+certain operations.  Please note that not all backends support all
+encodings on all operations.  The following data types are available:
 
 @table @code
 @item GPGME_DATA_ENCODING_NONE
@@ -1870,6 +1956,19 @@ scheme as used by @acronym{MIME} and other protocols.
 @item GPGME_DATA_ENCODING_ARMOR
 This specifies that the data is encoded in an armored form as used by
 OpenPGP and PEM.
+
+@item GPGME_DATA_ENCODING_URL
+The data is a list of linefeed delimited URLs.  This is only useful with
+@code{gpgme_op_import}.
+
+@item GPGME_DATA_ENCODING_URL0
+The data is a list of binary zero delimited URLs.  This is only useful
+with @code{gpgme_op_import}.
+
+@item GPGME_DATA_ENCODING_URLESC
+The data is a list of linefeed delimited URLs with all control and space
+characters percent escaped.  This mode is is not yet implemented.
+
 @end table
 @end deftp
 
@@ -1908,6 +2007,7 @@ cryptographic operations.
 @menu
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
@@ -1927,7 +2027,11 @@ and returns a handle for it in @var{ctx}.
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 context was successfully created, @code{GPG_ERR_INV_VALUE} if
 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
-enough memory is available.
+enough memory is available.  Also, it returns
+@code{GPG_ERR_NOT_OPERATIONAL} if @code{gpgme_check_version} was not
+called to initialize GPGME, and @code{GPG_ERR_SELFTEST_FAILED} if a
+selftest failed.  Currently, the only selftest is for Windows MingW32
+targets to see if @code{-mms-bitfields} was used (as required).
 @end deftypefun
 
 
@@ -1941,6 +2045,38 @@ The function @code{gpgme_release} destroys the context with the handle
 @end deftypefun
 
 
+@node Result Management
+@section Result Management
+@cindex context, result of operation
+
+The detailed result of an operation is returned in operation-specific
+structures such as @code{gpgme_decrypt_result_t}.  The corresponding
+retrieval functions such as @code{gpgme_op_decrypt_result} provide
+static access to the results after an operation completes.  The
+following interfaces make it possible to detach a result structure
+from its associated context and give it a lifetime beyond that of the
+current operation or context.
+
+@deftypefun void gpgme_result_ref (@w{void *@var{result}})
+The function @code{gpgme_result_ref} acquires an additional reference
+for the result @var{result}, which may be of any type
+@code{gpgme_*_result_t}.  As long as the user holds a reference, the
+result structure is guaranteed to be valid and unmodified.
+@end deftypefun
+
+@deftypefun void gpgme_result_unref (@w{void *@var{result}})
+The function @code{gpgme_result_unref} releases a reference for the
+result @var{result}.  If this was the last reference, the result
+structure will be destroyed and all resources associated to it will be
+released.
+@end deftypefun
+
+Note that a context may hold its own references to result structures,
+typically until the context is destroyed or the next operation is
+started.  In fact, these references are accessed through the
+@code{gpgme_op_*_result} functions.
+
+
 @node Context Attributes
 @section Context Attributes
 @cindex context, attributes
@@ -2135,10 +2271,10 @@ is the default.
 
 @item GPGME_KEYLIST_MODE_EXTERN
 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
-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.
+source should be searched for keys in the keylisting operation.  The
+type of external source is dependant on the crypto engine used and
+whether it is combined with @code{GPGME_KEYLIST_MODE_LOCAL}.  For
+example, it can be a remote keyserver or LDAP certificate server.
 
 @item GPGME_KEYLIST_MODE_SIGS
 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
@@ -2150,6 +2286,10 @@ signature notations on key signatures should be included in the listed
 keys.  This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
 enabled.
 
+@item GPGME_KEYLIST_MODE_EPHEMERAL
+The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys
+flagged as ephemeral are included in the listing.
+
 @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
@@ -2163,7 +2303,7 @@ At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
 compatibility, you should get the current mode with
 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
-appropriate bits, and then using that calulcated value in the
+appropriate bits, and then using that calculated value in the
 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
 bits in the mode value intact (in particular those that are not used
 in the current version of the library).
@@ -2210,9 +2350,9 @@ previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
 will be 0.
 
 The user must write the passphrase, followed by a newline character,
-to the file descriptor @var{fd}.  If the user does not return 0
-indicating success, the user must at least write a newline character
-before returning from the callback.
+to the file descriptor @var{fd}.  If the user returns 0 indicating
+success, the user must at least write a newline character before
+returning from the callback.
 
 If an error occurs, return the corresponding @code{gpgme_error_t}
 value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
@@ -2610,6 +2750,8 @@ in the list is the main (or primary) user ID.
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Changing Passphrases::          Change the passphrase of a key.
+* Advanced Key Editing::          Advanced key edit operation.
 @end menu
 
 
@@ -2697,7 +2839,7 @@ The function returns the error code @code{GPG_ERR_INV_VALUE} if
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
-The function @code{gpgme_op_keylist_next} ends a pending key list
+The function @code{gpgme_op_keylist_end} ends a pending key list
 operation in the context @var{ctx}.
 
 After the operation completed successfully, the result of the key
@@ -2715,6 +2857,7 @@ and e-mail address of the main user ID:
 
 @example
 gpgme_ctx_t ctx;
+gpgme_key_t key;
 gpgme_error_t err = gpgme_new (&ctx);
 
 if (!err)
@@ -2725,15 +2868,19 @@ if (!err)
         err = gpgme_op_keylist_next (ctx, &key);
         if (err)
           break;
-        printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
+        printf ("%s:", key->subkeys->keyid);
+        if (key->uids && key->uids->name)
+          printf (" %s", key->uids->name);
+        if (key->uids && key->uids->email)
+          printf (" <%s>", key->uids->email);
+        putchar ('\n');
         gpgme_key_release (key);
       @}
     gpgme_release (ctx);
   @}
 if (gpg_err_code (err) != GPG_ERR_EOF)
   @{
-    fprintf (stderr, "%s: can not list keys: %s\n",
-             argv[0], gpgme_strerror (err));
+    fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
     exit (1);
   @}
 @end example
@@ -2773,7 +2920,7 @@ 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
+the error code @code{GPG_ERR_EOF} and *@var{r_key} will be set to
 @code{NULL}.
 
 The function returns the error code @code{GPG_ERR_INV_VALUE} if
@@ -3147,14 +3294,13 @@ used.  GpgSM does not make the fingerprint available.
 The argument @var{parms} specifies parameters for the key in an XML
 string.  The details about the format of @var{parms} are specific to
 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
-the crypto engine:
+the crypto engine (all parameters of OpenPGP key generation are
+documented in the GPG manual):
 
 @example
 <GnupgKeyParms format="internal">
-Key-Type: DSA
-Key-Length: 1024
-Subkey-Type: ELG-E
-Subkey-Length: 1024
+Key-Type: default
+Subkey-Type: default
 Name-Real: Joe Tester
 Name-Comment: with stupid passphrase
 Name-Email: joe@@foo.bar
@@ -3163,7 +3309,8 @@ Passphrase: abc
 </GnupgKeyParms>
 @end example
 
-Here is an example for GpgSM as the crypto engine:
+Here is an example for GpgSM as the crypto engine (all parameters of
+OpenPGP key generation are documented in the GPGSM manual):
 
 @example
 <GnupgKeyParms format="internal">
@@ -3241,17 +3388,42 @@ operation is started on the context.
 @cindex key, export
 @cindex key ring, export from
 
-@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+Exporting keys means the same as running @command{gpg} with the command
+@option{--export}.  However, a mode flag can be used to change the way
+the export works.  The available mode flags are described below, they
+may be or-ed together.
+
+@table @code
+
+@item GPGME_EXPORT_MODE_EXTERN
+If this bit is set, the output is send directly to the default
+keyserver. This is currently only allowed for OpenPGP keys.  It is good
+practise to not send more than a few dozens key to a keyserver at one
+time.  Using this flag requires that the @var{keydata} argument of the
+export function is set to @code{NULL}.
+
+@item GPGME_EXPORT_MODE_MINIMAL
+If this bit is set, the smallest possible key is exported.  For OpenPGP
+keys it removes all signatures except for the latest self-signatures.
+For X.509 keys it has no effect.
+
+
+@end table
+
+
+
+@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export} extracts public keys and returns
 them in the data buffer @var{keydata}.  The output format of the key
 data returned is determined by the @acronym{ASCII} armor attribute set
-for the context @var{ctx}.
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
 
 If @var{pattern} is @code{NULL}, all available keys are returned.
 Otherwise, @var{pattern} contains an engine specific expression that
 is used to limit the list to all keys matching the pattern.
 
-@var{reserved} is reserved for future use and must be @code{0}.
+@var{mode} is usually 0; other values are described above.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
@@ -3259,7 +3431,7 @@ operation completed successfully, @code{GPG_ERR_INV_VALUE} if
 errors that are reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export_start} initiates a
 @code{gpgme_op_export} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
@@ -3269,18 +3441,19 @@ operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
 if @var{keydata} is not a valid empty data buffer.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export} extracts public keys and returns
 them in the data buffer @var{keydata}.  The output format of the key
 data returned is determined by the @acronym{ASCII} armor attribute set
-for the context @var{ctx}.
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
 
 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
 array of strings that are used to limit the list to all keys matching
 at least one of the patterns verbatim.
 
-@var{reserved} is reserved for future use and must be @code{0}.
+@var{mode} is usually 0; other values are described above.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
@@ -3288,7 +3461,7 @@ operation completed successfully, @code{GPG_ERR_INV_VALUE} if
 errors that are reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export_ext_start} initiates a
 @code{gpgme_op_export_ext} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
@@ -3299,11 +3472,50 @@ if @var{keydata} is not a valid empty data buffer.
 @end deftypefun
 
 
+@deftypefun gpgme_error_t gpgme_op_export_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t keys[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_keys} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
+
+The keys to export are taken form the @code{NULL} terminated array
+@var{keys}.  Only keys of the the currently selected protocol of
+@var{ctx} which do have a fingerprint set are considered for export.
+Other keys specified by the @var{keys} are ignored.  In particular
+OpenPGP keys retrieved via an external key listing are not included.
+
+@var{mode} is usually 0; other values are described above.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA}
+if no useful keys are in @var{keys} and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{keys}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_keys_start} initiates a
+@code{gpgme_op_export_ext} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA}
+if no useful keys are in @var{keys} and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
+
+
 @node Importing Keys
 @subsection Importing Keys
 @cindex key, import
 @cindex key ring, import to
 
+Importing keys means the same as running @command{gpg} with the command
+@option{--import}. 
+
+
 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_import} adds the keys in the data buffer
 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
@@ -3330,6 +3542,44 @@ import could be started successfully, @code{GPG_ERR_INV_VALUE} if
 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
 @end deftypefun
 
+@deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
+The function @code{gpgme_op_import_keys} adds the keys described by the
+@code{NULL} terminated array @var{keys} to the key ring of the crypto
+engine used by @var{ctx}.  This function is the general interface to
+move a key from one crypto engine to another as long as they are
+compatible.  In particular it is used to actually import and make keys
+permanent which have been retrieved from an external source (i.e. using
+@code{GPGME_KEYLIST_MODE_EXTERN}).  @footnote{Thus it is a replacement
+for the usual workaround of exporting and then importing a key to make
+an X.509 key permanent.}
+
+Only keys of the the currently selected protocol of @var{ctx} are
+considered for import.  Other keys specified by the @var{keys} are
+ignored.  As of now all considered keys must have been retrieved using
+the same method, that is the used key listing mode must be identical.
+
+After the operation completed successfully, the result can be
+retrieved with @code{gpgme_op_import_result}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
+@code{GPG_ERR_NO_DATA} if no keys are considered for export.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
+The function @code{gpgme_op_import_keys_start} initiates a
+@code{gpgme_op_import_keys} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
+@code{GPG_ERR_NO_DATA} if no keys are considered for export.
+@end deftypefun
+
 @deftp {Data type} {gpgme_import_status_t}
 This is a pointer to a structure used to store a part of the result of
 a @code{gpgme_op_import} operation.  For each considered key one
@@ -3485,6 +3735,103 @@ operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
 @end deftypefun
 
 
+@node Changing Passphrases
+@subsection  Changing Passphrases
+@cindex passphrase, change
+
+@deftypefun gpgme_error_t gpgme_op_passwd      @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_passwd} changes the passphrase of the
+private key associated with @var{key}.  The only allowed value for
+@var{flags} is @code{0}.  The backend engine will usually popup a window
+to ask for the old and the new passphrase.  Thus this function is not
+useful in a server application (where passphrases are not required
+anyway).
+
+Note that old @code{gpg} engines (before version 2.0.15) do not support
+this command and will silently ignore it.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_passwd_start      @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_passwd_start} initiates a
+@code{gpgme_op_passwd} operation.    It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{0} if the operation was started successfully,
+and an error code if one of the arguments is not valid or the oepration
+could not be started.
+@end deftypefun
+
+
+@node Advanced Key Editing
+@subsection Advanced Key Editing
+@cindex key, edit
+
+@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
+@tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key edit operation is on-going.  The
+status code @var{status} and the argument line @var{args} are passed
+through by @acronym{GPGME} from the crypto engine.  The file
+descriptor @var{fd} is -1 for normal status messages.  If @var{status}
+indicates a command rather than a status message, the response to the
+command should be written to @var{fd}.  The @var{handle} is provided
+by the user at start of operation.
+
+The function should return @code{GPG_ERR_NO_ERROR} or an error value.
+@end deftp
+
+@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit} processes the key @var{KEY}
+interactively, using the edit callback function @var{FNC} with the
+handle @var{HANDLE}.  The callback is invoked for every status and
+command request from the crypto engine.  The output of the crypto
+engine is written to the data object @var{out}.
+
+Note that the protocol between the callback function and the crypto
+engine is specific to the crypto engine and no further support in
+implementing this protocol correctly is provided by @acronym{GPGME}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit_start} initiates a
+@code{gpgme_op_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit} is analogous to
+@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit_start} initiates a
+@code{gpgme_op_card_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
 @node Trust Item Management
 @section Trust Item Management
 @cindex trust item
@@ -3567,7 +3914,7 @@ there is not enough memory for the operation.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
-The function @code{gpgme_op_trustlist_next} ends a pending key list
+The function @code{gpgme_op_trustlist_end} ends a pending trust list
 operation in the context @var{ctx}.
 
 The function returns the error code @code{GPG_ERR_INV_VALUE} if
@@ -4001,6 +4348,16 @@ Values are:
 Depending on the configuration of the engine, this metric may also be
 reflected by the validity of the signature.
 
+@item unsigned int chain_model : 1
+This is true if the validity of the signature has been checked using the
+chain model.  In the chain model the time the signature has been created
+must be within the validity period of the certificate and the time the
+certificate itself has been created must be within the validity period
+of the issuing certificate.  In contrast the default validation model
+checks the validity of signature as well at the entire certificate chain
+at the current time.
+
+
 @item gpgme_validity_t validity
 The validity of the signature.
 
@@ -4399,7 +4756,8 @@ mode settings of the context are ignored.
 The function @code{gpgme_op_sign} creates a signature for the text in
 the data object @var{plain} and returns it in the data object
 @var{sig}.  The type of the signature created is determined by the
-@acronym{ASCII} armor and text mode attributes set for the context
+@acronym{ASCII} armor (or, if that is not set, by the encoding
+specified for @var{sig}), the text mode attributes set for the context
 @var{ctx} and the requested signature mode @var{mode}.
 
 After the operation completed successfully, the result can be
@@ -4483,7 +4841,7 @@ 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
+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
@@ -4559,11 +4917,12 @@ and then passed to the encryption operation.
 @subsubsection Encrypting a Plaintext
 
 @deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
-The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
-object @var{plain} for the recipients @var{recp} and stores the
+The function @code{gpgme_op_encrypt} encrypts the plaintext in the
+data object @var{plain} for the recipients @var{recp} and stores the
 ciphertext in the data object @var{cipher}.  The type of the
-ciphertext created is determined by the @acronym{ASCII} armor and text
-mode attributes set for the context @var{ctx}.
+ciphertext created is determined by the @acronym{ASCII} armor (or, if
+that is not set, by the encoding specified for @var{cipher}) and the
+text mode attributes set for the context @var{ctx}.
 
 @var{key} must be a @code{NULL}-terminated array of keys.  The user
 must keep references for all keys during the whole duration of the
@@ -4579,6 +4938,12 @@ The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
 recipients in @var{recp} should be trusted, even if the keys do not
 have a high enough validity in the keyring.  This flag should be used
 with care; in general it is not a good idea to use any untrusted keys.
+
+@item GPGME_ENCRYPT_NO_ENCRYPT_TO
+The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
+default or hidden default recipients as configured in the crypto
+backend should be included.  This can be useful for managing different
+user profiles.
 @end table
 
 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
@@ -4911,8 +5276,8 @@ callback handler.  It must be specified.
 
 @item gpgme_event_io_cb_t event
 This is the function called by @acronym{GPGME} to signal an event for
-an operation.  It is optional, but if you don't specify it, you can
-not retrieve the return value of the operation.
+an operation.  It must be specified, because at least the start event
+must be processed.
 
 @item void *event_data
 This is passed as the first argument to the @code{event} function when
@@ -4946,13 +5311,16 @@ monitor these file descriptors for activity and call the appropriate
 I/O callbacks.
 
 The following example illustrates how to do that.  The example uses
-locking to show in which way the the callbacks and the event loop can
+locking to show in which way the callbacks and the event loop can
 run concurrently.  For the event loop, we use a fixed array.  For a
 real-world implementation, you should use a dynamically sized
 structure because the number of file descriptors needed for a crypto
 operation in @acronym{GPGME} is not predictable.
 
 @example
+#include <assert.h>
+#include <errno.h>
+#include <stdlib.h>
 #include <pthread.h>
 #include <sys/types.h>
 #include <gpgme.h>
@@ -4972,6 +5340,7 @@ struct one_fd
   int dir;
   gpgme_io_cb_t fnc;
   void *fnc_data;
+  void *loop;
 @};
 
 struct event_loop
@@ -5003,6 +5372,7 @@ add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
          fds[i].dir = dir;
          fds[i].fnc = fnc;
          fds[i].fnc_data = fnc_data;
+         fds[i].loop = loop;
          break;
        @}
     @}
@@ -5017,6 +5387,7 @@ void
 remove_io_cb (void *tag)
 @{
   struct one_fd *fd = tag;
+  struct event_loop *loop = fd->loop;
 
   pthread_mutex_lock (&loop->lock);
   fd->fd = -1;
@@ -5048,11 +5419,12 @@ do_select (struct event_loop *loop)
   fd_set wfds;
   int i, n;
   int any = 0;
+  struct one_fd *fdlist = loop->fds;
 
   pthread_mutex_lock (&loop->lock);
   FD_ZERO (&rfds);
   FD_ZERO (&wfds);
-  for (i = 0; i < FDLIST_MAX; i++)
+  for (i = 0; i < MAX_FDS; i++)
     if (fdlist[i].fd != -1)
       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
   pthread_mutex_unlock (&loop->unlock);
@@ -5067,7 +5439,7 @@ do_select (struct event_loop *loop)
     return n;  /* Error or timeout.  */
 
   pthread_mutex_lock (&loop->lock);
-  for (i = 0; i < FDLIST_MAX && n; i++)
+  for (i = 0; i < MAX_FDS && n; i++)
     @{
       if (fdlist[i].fd != -1)
        @{
@@ -5098,7 +5470,6 @@ wait_for_op (struct event_loop *loop, struct op_result *result)
       ret = do_select (loop);
     @}
   while (ret >= 0 && !result->done);
-  return ret;
 @}
 @end example
 
@@ -5113,7 +5484,6 @@ main (int argc, char *argv[])
   gpgme_ctx_t ctx;
   gpgme_error_t err;
   gpgme_data_t sig, text;
-  gpgme_sig_stat_t status;
   int i;
   struct gpgme_io_cb_ts io_cbs =
   @{
@@ -5124,8 +5494,10 @@ main (int argc, char *argv[])
     &result
   @};
 
+  init_gpgme (void);
+
   /* Initialize the loop structure.  */
-  loop.lock = PTHREAD_MUTEX_INITIALIZER;
+  pthread_mutex_init (&loop.lock, NULL);
   for (i = 0; i < MAX_FDS; i++)
     loop->fds[i].fd = -1;
 
@@ -5140,7 +5512,7 @@ main (int argc, char *argv[])
   if (!err)
     @{
        gpgme_set_io_cbs (ctx, &io_cbs);
-       err = gpgme_op_verify_start (ctx, sig, text, &status);
+       err = gpgme_op_verify_start (ctx, sig, text, NULL);
     @}
   if (err)
     @{
@@ -5161,7 +5533,7 @@ main (int argc, char *argv[])
                gpgme_strsource (result.err), gpgme_strerror (result.err));
       exit (1);
     @}
-  /* Evaluate STATUS.  */
+  /* Evaluate verify result.  */
   @dots{}
   return 0;
 @}
@@ -5348,13 +5720,15 @@ private:
 @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.
+Sometimes you do not want to wait for an operation to finish.
+@acronym{GPGME} provides two different functions to achieve that.  The
+function @code{gpgme_cancel} takes effect immediately.  When it
+returns, the operation is effectively canceled.  However, it has some
+limitations and can not be used with synchronous operations.  In
+contrast, the function @code{gpgme_cancel_async} can be used with any
+context and from any thread, but it is not guaranteed to take effect
+immediately.  Instead, cancellation occurs at the next possible time
+(typically the next time I/O occurs in the target context).
 
 @deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_cancel} attempts to cancel a pending
@@ -5378,21 +5752,36 @@ case the state of @var{ctx} is not modified).
 @end deftypefun
 
 
-@include lesser.texi
+@deftypefun gpgme_ctx_t gpgme_cancel_async (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}.  This can be called by any thread
+at any time after starting an operation on the context, but will not
+take effect immediately.  The actual cancellation happens at the next
+time GPGME processes I/O in that context.
 
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
 
-@node Concept Index
-@unnumbered Concept Index
+@c **********************************************************
+@c *******************  Appendices  *************************
+@c **********************************************************
 
-@printindex cp
+@include uiserver.texi
+
+@include lesser.texi
 
+@include gpl.texi
 
 @node Function and Data Index
 @unnumbered Function and Data Index
 
 @printindex fn
 
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
 
-@summarycontents
-@contents
 @bye