2003-06-09 Moritz Schulte <moritz@g10code.com>

	* gcrypt.texi (Version Check): Changed description of
	gcry_check_version; the user now *must* call the function to
	initialize the library.

2003-06-08  Moritz Schulte  <moritz@g10code.com>

	* gcrypt.texi: Change for libgpg-error.

2 files changed, 322 insertions, 149 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 822313ee..ba5325bd 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,13 @@
+2003-06-09  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Version Check): Changed description of
+	gcry_check_version; the user now *must* call the function to
+	initialize the library.
+
+2003-06-08  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Change for libgpg-error.
+
 2003-05-22  Moritz Schulte  <moritz@g10code.com>
 
 	* gcrypt.texi (Public Key Functions): Fixed typo.
diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
index 148f2820..0184d7e9 100644
--- a/doc/gcrypt.texi
+++ b/doc/gcrypt.texi
@@ -121,8 +121,9 @@ Indices
 @node Getting Started
 @section Getting Started
 
-This manual documents the `Libgcrypt' library programming interface.
-All functions and data types provided by the library are explained.
+This manual documents the `Libgcrypt' library application programming
+interface (API).  All functions and data types provided by the library
+are explained.
 
 The reader is assumed to possess basic knowledge about applied
 cryptography.
@@ -169,6 +170,8 @@ The `Libgcrypt' library is thread-safe.  Well, we hope so ;-).  Frankly,
 be.  Libgcrypt automagically detects whether an applications uses no
 threading, pthreads or GNU Pth.
 
+Libgcrypt depends on the library `libgpg-error' [FIXME: REF], which
+contains common error handling code for GnuPG components.
 
 @c **********************************************************
 @c *******************  Preparation  ************************
@@ -201,10 +204,14 @@ like this:
 #include <gcrypt.h>
 @end example
 
-The name space of `Libgcrypt' is @code{gcry_*} for function names,
-@code{Gcry*} for data types and @code{GCRY_*} for other symbols.  In
-addition the same name prefixes with one prepended underscore are
-reserved for internal use and should never be used by an application.
+The name space of `Libgcrypt' is @code{gcry_*} for function and type
+names and @code{GCRY*} for other symbols.  In addition the same name
+prefixes with one prepended underscore are reserved for internal use
+and should never be used by an application.  Furthermore
+`libgpg-error' defines functions prefixed with `gpg_' and preprocessor
+symbols prefixed with `GPG_'.  Note that libgcrypt uses libgpg-error,
+which uses @code{gpg_err_*} as name space for function and type names
+and @code{GPG_ERR_*} for other symbols, including all the error codes.
 
 @node Version Check
 @section Version Check
@@ -217,14 +224,12 @@ check that the version is okay right after program startup.
 
 @deftypefun const char *gcry_check_version (const char *@var{req_version})
 
-Check that the the version of the library is at minimum the one given as
-a string in @var{req_version} and return the actual version string of
-the library; return NULL if the condition is not met.  If @code{NULL} is
-passed to this function no check is done and only the version string is
-returned.  It is a pretty good idea to run this function as soon as
-possible, because it may also initializes some subsystems.  In a
-multi-threaded environment if should be called before any more threads
-are created.
+The function @code{gcry_check_version} has three 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 of Libgcrypt.
 @end deftypefun
 
 @node Building the source
@@ -289,14 +294,16 @@ blocks provided by Libgcrypt.
 To use a cipher algorithm, you must first allocate an handle for
 this.  This can is to be done using the open function:
 
-@deftypefun GcryCipherHd gcry_cipher_open (int @var{algo}, int @var{mode}, unsigned int @var{flags})
+@deftypefun gpg_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd},
+int @var{algo}, int @var{mode}, unsigned int @var{flags})
 
-This function creates the context required for most of the other cipher
-functions and returns a handle to it.  In case of an error @code{NULL}
-is returned.  You must tell this function which algorithm and what mode
-you want to use.  The function @code{gcry_cipher_map_name} may be used to
-get the a value for the @var{algo} from a textual name or one of the
-predefined constants can be used:
+This function creates the context required for most of the other
+cipher functions and returns a handle to it in `hd'.  In case of an
+error, an according error code is returned.  You must tell this
+function which algorithm and what mode you want to use.  The function
+@code{gcry_cipher_map_name} may be used to get the a value for the
+@var{algo} from a textual name or one of the predefined constants can
+be used:
 
 @c begin cipher algorithm constants
 @table @code
@@ -351,15 +358,15 @@ avoid a couple of weaknesses.
 @item  GCRY_CIPHER_DES       
 Standard DES with a 56 bit key. You need to pass 64 bit but the high
 bits of each byte are ignored.  Note, that this is a weak algorithm
-which is can be broken in reasonable time using a brute force approach.
+which can be broken in reasonable time using a brute force approach.
 
 @end table
 @c end cipher algorithm constants
 
 @c begin cipher modes constants
-The second argument is @var{mode} which describes the mode the algorithm
-is to be used in.  Note, that some modes don't work together with
-all algorithms. The following modes are available:
+The second argument is @var{mode} which describes the mode the
+algorithm is to be used in.  Note, that some modes do not work
+together with all algorithms. The following modes are available:
 
 @table @code
 @item GCRY_CIPHER_MODE_NONE
@@ -413,7 +420,7 @@ GCRY_CIPHER_CBC_CTS.
 To release the context allocated with this function,
 @code{gcry_cipher_close} should be used:
 
-@deftypefun void gcry_cipher_close (GcryCipherHd @var{h})
+@deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})
 
 This function releases the context created by @code{gcry_cipher_open}.
 @end deftypefun
@@ -421,7 +428,7 @@ This function releases the context created by @code{gcry_cipher_open}.
 Now that a context has been allocated, the key to be used for decryption
 or encryption must be set.  This is done with the following function:
 
-@deftypefun int gcry_cipher_setkey (GcryCipherHd @var{h}, void *@var{k}, size_t @var{l})
+@deftypefun gpg_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
 
 Set the key @var{k} used for encryption or decryption in the context
 denoted by the handle @var{h}.  The length @var{l} of the key @var{k}
@@ -439,7 +446,7 @@ usually is a non-secret random string acting as a kind of salt value.
 The CTR mode requires a counter, which is also similar to a salt
 value.  To set the IV or CTR, use these functions:
 
-@deftypefun int gcry_cipher_setiv (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
+@deftypefun gpg_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
 
 Set the initialization vector used for encryption or decryption. The
 vector is passed as the buffer @var{K} of length @var{l} and copied to
@@ -448,7 +455,7 @@ requirement of the selected algorithm and mode.  Note, that this is
 implemented as a macro.
 @end deftypefun
 
-@deftypefun int gcry_cipher_setctr (GCRY_CIPHER_HD @var{h}, void *@var{c}, size_t @var{l})
+@deftypefun gpg_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})
 
 Set the counter vector used for encryption or decryption. The counter
 is passed as the buffer @var{c} of length @var{l} and copied to
@@ -458,7 +465,7 @@ the same size as the block size).  Note, that this is implemented as a
 macro.
 @end deftypefun
 
-@deftypefun int gcry_cipher_reset (GCRY_CIPHER_HD @var{h})
+@deftypefun gpg_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
 
 Set the given handle's context back to the state it had after the last
 call to gcry_cipher_setkey and clear the initialization vector.
@@ -470,7 +477,7 @@ The actual encryption and decryption is done by using one of the
 following functions.  They may be used as often as required to process
 all the data.
 
-@deftypefun int gcry_cipher_encrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+@deftypefun gpg_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
 
 @code{gcry_cipher_encrypt} is used to encrypt the data.  This function
 can either work in place or with two buffers.  It uses the cipher
@@ -490,7 +497,7 @@ The function returns @code{0} on success or an error code.
 @end deftypefun
 
 
-@deftypefun int gcry_cipher_decrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+@deftypefun gpg_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
 
 @code{gcry_cipher_decrypt} is used to decrypt the data.  This function
 can either work in place or with two buffers.  It uses the cipher
@@ -513,7 +520,7 @@ The function returns @code{0} on success or an error code.
 OpenPGP (as defined in RFC-2440) requires a special sync operation in
 some places, the following function is used for this:
 
-@deftypefun int gcry_cipher_sync (GCRY_CIPHER_HD @var{h})
+@deftypefun gpg_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
 
 Perform the OpenPGP sync operation on context @var{h}. Note, that this
 is a no-op unless the context was created with the flag
@@ -524,7 +531,7 @@ Some of the described functions are implemented as macros utilizing a
 catch-all control function.  This control function is rarely used
 directly but there is nothing which would inhibit it:
 
-@deftypefun int gcry_cipher_ctl (GCRY_CIPHER_HD @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
+@deftypefun gpg_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
 
 @code{gcry_cipher_ctl} controls various aspects of the cipher module and
 specific cipher contexts.  Usually some more specialized functions or
@@ -543,7 +550,7 @@ To work with the algorithms, several functions are available to map
 algorithm names to the internal identifiers, as well as ways to retrieve
 information about an algorithm or the current cipher context.
 
-@deftypefun int gcry_cipher_info (GCRY_CIPHER_HD @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+@deftypefun gpg_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
 
 @code{gcry_cipher_info} is used to retrieve various
 information about a cipher context or the cipher module in general.
@@ -552,7 +559,7 @@ Currently no information is available.
 @end deftypefun
 
 
-@deftypefun int gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+@deftypefun gpg_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
 
 This function is used to retrieve information on a specific algorithm.
 You pass the cipher algorithm ID as @var{algo} and the type of
@@ -562,9 +569,6 @@ whose allocated length must be available in an integer variable with the
 address passed in @var{nbytes}.  This variable will also receive the
 actual used length of the buffer. 
 
-The function returns @code{-1} on error;  @code{gcry_errno} may be used
-to get the actual error code.
-
 Here is a list of supported codes for @var{what}:
 
 @c begin constants for gcry_cipher_algo_info
@@ -631,12 +635,13 @@ are also supported.
 To use most of these function it is necessary to create a context;  this
 is done using:
 
-@deftypefun GcryMDHd gcry_md_open (int @var{algo}, unsigned int @var{flags})
+@deftypefun gpg_error_t gcry_md_open (gcry_md_hd_t *hd, int @var{algo},
+unsigned int @var{flags})
 
 Create a message digest object for algorithm @var{algo}.  @var{flags}
-may be given as an bitwise OR of constants described below.  @var{algo}
-may be given as @code{0} if the algorithms to use are later set using
-@code{gcry_md_enable}.
+may be given as an bitwise OR of constants described below.
+@var{algo} may be given as @code{0} if the algorithms to use are later
+set using @code{gcry_md_enable}.
 
 The following algorithms are supported:
 
@@ -721,7 +726,7 @@ If you want CBC message authenentication codes based on a cipher, see
 If you want to calculate several hash algorithms at the same time, you
 have to use the following function right after the @code{gcry_md_open}:
 
-@deftypefun int gcry_md_enable (GcryMDHd @var{h}, int @var{algo})
+@deftypefun gpg_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
 
 Add the message digest algorithm @var{algo} to the digest object
 described by handle @var{h}.  Duplicated enabling of algorithms is
@@ -731,7 +736,7 @@ detected and ignored.
 If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
 be set using the function:
 
-@deftypefun int gcry_md_setkey (GcryMDHd @var{h}, const void *@var{key},
+@deftypefun gpg_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key},
 size_t @var{keylen})
 
 For use with the HMAC feature, set the MAC key to the value of @var{key}
@@ -742,7 +747,7 @@ of length @var{keylen}.
 After you are done with the hash calculation, you should release the
 resources by using:
 
-@deftypefun void gcry_md_close (GcryMDHd @var{h})
+@deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
 
 Release all resources of hash context @var{h}.  @var{h} should not be
 used after a call to this function.  A @code{NULL} passed as @var{h} is
@@ -754,7 +759,7 @@ Often you have to do several hash operations using the same algorithm.
 To avoid the overhead of creating and releasing context, a reset function
 is provided:
 
-@deftypefun void gcry_md_reset (GcryMDHd @var{h})
+@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
 
 Reset the current context to its initial state.  This is effectively
 identical to a close followed by an open and enabling all currently
@@ -768,11 +773,12 @@ might not even be possible if the data is received from a pipe), a
 snapshot of the current hash context can be taken and turned into a new
 context:
 
-@deftypefun GcryMDHd gcry_md_copy (GcryMDHd @var{h})
+@deftypefun gpg_error_t gcry_md_copy (gcry_md_hd_t @var{h}, gcry_md_hd_t *@var{h2})
 
 Create a new digest object as an exact copy of the object described by
-handle @var{h}.  The context is not reset and you can continue to hash
-data using this context and independently using the original context.
+handle @var{h} and store it in @var{h2}.  The context is not reset and
+you can continue to hash data using this context and independently
+using the original context.
 @end deftypefun
 
 
@@ -781,14 +787,14 @@ see how it is actually done.  There are 2  ways for this, one to
 update the hash with a block of memory and one macro to update the hash
 by just one character.  Both may be used intermixed.
 
-@deftypefun void gcry_md_write (GcryMDHd @var{h}, const void *@var{buffer}, size_t @var{length})
+@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
 
 Pass @var{length} bytes of the data in @var{buffer} to the digest object
 with handle @var{h} to update the digest values. This
 function should be used for large blocks of data.
 @end deftypefun
 
-@deftypefun void gcry_md_putc (GcryMDHd @var{h}, int @var{c})
+@deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
 
 Pass the byte in @var{c} to the digest object with handle @var{h} to
 update the digest value.  This is an efficient function, implemented as
@@ -800,7 +806,7 @@ message digests because the calculation must be finalized fist.  This
 finalization may for example include the number of bytes hashed in the
 message digest.  
 
-@deftypefun void gcry_md_final (GcryMDHd @var{h})
+@deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
 
 Finalize the message digest calculation.  This is not really needed
 because @code{gcry_md_read} does this implicitly.  After this has been
@@ -812,7 +818,7 @@ has an effect. It is implemented as a macro.
 The way to read out the calculated message digest is by using the
 function:
 
-@deftypefun unsigned char *gcry_md_read (GcryMDHd @var{h}, int @var{algo})
+@deftypefun unsigned char *gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
 
 @code{gcry_md_read} returns the message digest after finalizing the
 calculation.  This function may be used as often as required but it will
@@ -870,22 +876,24 @@ or "@code{OID.}".  For a list of supported OIDs, see the source code at
 availability of an algorithm.
 @end deftypefun
 
-@deftypefun int gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
+@deftypefun gpg_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
+
+Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
+user allocated @var{buffer}. @var{length} must point to variable with
+the available size of @var{buffer} and receives after return the
+actual size of the returned OID.  The returned error code may be
+@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
+the OID; it is possible to call the function with @code{NULL} for
+@var{buffer} to have it only return the required size.  The function
+returns 0 on success.
 
-Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the user
-allocated @var{buffer}. @var{length} must point to variable with the
-available size of @var{buffer} and receives after return the actual size
-of the returned OID.  The return value may be @code{GCRYERR_TOO_SHORT}
-if the provided buffer is to short to receive the OID; it is possible to
-call the function with @code{NULL} for @var{buffer} to have it only
-return the required size.  The function returns 0 on success. 
 @end deftypefun
 
 
 To test whether an algorithm is actually available for use, the
 following macro should be used:
 
-@deftypefun int gcry_md_test_algo (int @var{algo}) 
+@deftypefun gpg_error_t gcry_md_test_algo (int @var{algo}) 
 
 The macro returns 0 if the algorithm @var{algo} is available for use.
 @end deftypefun
@@ -905,7 +913,7 @@ In some situations it might be hard to remember the algorithm used for
 the ongoing hashing. The following function might be used to get that
 information:
 
-@deftypefun int gcry_md_get_algo (GcryMDHd @var{h})
+@deftypefun gpg_error_t gcry_md_get_algo (gcry_md_hd_t @var{h}, int *@var{algo})
 
 Retrieve the algorithm used with the handle @var{h}. Note, that this
 does not work reliable if more than one algorithm is enabled in @var{h}.
@@ -913,7 +921,7 @@ does not work reliable if more than one algorithm is enabled in @var{h}.
 
 The following macro might also be useful:
 
-@deftypefun int gcry_md_is_secure (GcryMDHd @var{h})
+@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
 
 This macro return true when the digest object @var{h} is allocated in "secure
 memory"; i.e. @var{h} was created with the @code{GCRY_MD_FLAG_SECURE}.
@@ -926,7 +934,7 @@ provides an easy way to avoid this.  The actual data hashed can be
 written to files on request.  The following 2 macros should be used to
 implement such a debugging facility:
 
-@deftypefun void gcry_md_start_debug (GcryMDHd @var{h}, const char *@var{suffix})
+@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
 
 Enable debugging for the digest object with handle @var{h}.  This
 creates create files named @file{dbgmd-<n>.<string>} while doing the
@@ -937,7 +945,7 @@ file is the raw data as passed to @code{gcry_md_write} or
 @end deftypefun
 
 
-@deftypefun void gcry_md_stop_debug (GcryMDHd @var{h}, int @var{reserved})
+@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved})
 
 Stop debugging on handle @var{h}.  @var{reserved} should be specified as
 0.  This function is usually not required because @code{gcry_md_close}
@@ -1049,7 +1057,7 @@ encrypt and decrypt data.  In almost all cases the data is a random
 session key which is in turn used for the actual encryption of the real
 data.  There are 2 functions to do this:
 
-@deftypefun int gcry_pk_encrypt (@w{GcrySexp *@var{r_ciph},} @w{GcrySexp @var{data},} @w{GcrySexp @var{pkey}})
+@deftypefun gpg_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
 
 Obviously a public key must be provided for encryption.  It is expected
 as an appropriate S-expression (see above) in @var{pkey}.  The data to
@@ -1059,7 +1067,7 @@ complex S-expression which also allows to specify padding rules.
 
 @noindent
 If you don't want to let Libgcrypt handle the padding, you must pass an
-appropriate MPI using the this expression for @var{data}:
+appropriate MPI using this expression for @var{data}:
 
 @example 
 (data
@@ -1119,7 +1127,7 @@ ElGamal encryption operation.
 @end deftypefun
 @c end gcry_pk_encrypt
 
-@deftypefun int gcry_pk_decrypt (@w{GcrySexp *@var{r_plain},} @w{GcrySexp @var{data},} @w{GcrySexp @var{skey}})
+@deftypefun gpg_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
 
 Obviously a private key must be provided for decryption.  It is expected
 as an appropriate S-expression (see above) in @var{skey}.  The data to
@@ -1160,7 +1168,7 @@ encryption because digital signature are an important instrument for key
 management.  Libgcrypt support digital signatures using 2 functions,
 similar to the encryption functions:
 
-@deftypefun int gcry_pk_sign (@w{GcrySexp *@var{r_sig},} @w{GcrySexp @var{data},} @w{GcrySexp @var{skey}})
+@deftypefun gpg_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
 
 This function creates a digital signature for @var{data} using the
 private key @var{skey} and place it into the variable at the address of
@@ -1228,7 +1236,7 @@ used with "elg" replacing "dsa".
 The operation most commonly used is definitely the verification of a
 signature.  Libgcrypt provides this function:
 
-@deftypefun int gcry_pk_verify (@w{GcrySexp @var{sig}}, @w{GcrySexp @var{data}}, @w{GcrySexp @var{pkey}})
+@deftypefun gpg_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
 
 This is used to check whether the signature @var{sig} matches the
 @var{data}.  The public key @var{pkey} must be provided to perform this
@@ -1267,16 +1275,17 @@ the algorithm name is not known.
 @deftypefun int gcry_pk_test_algo (int @var{algo})
 
 Return 0 if the public key algorithm @var{algo} is available for use.
+Note, that this is implemented as a macro.
 @end deftypefun
 
 
-@deftypefun {unsigned int} gcry_pk_get_nbits (GcrySexp @var{key})
+@deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})
 
 Return what is commonly referred as the key length for the given
 public or private in @var{key}.
 @end deftypefun
 
-@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{GcrySexp @var{key}}, @w{unsigned char *@var{array}})
+@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})
 
 Return the so called "keygrip" which is the SHA-1 hash of the public key
 parameters expressed in a way depended on the algorithm.  @var{array}
@@ -1288,7 +1297,7 @@ algorithm or one where a "keygrip" has not yet been defined.
 The function accepts public or secret keys in @var{key}.
 @end deftypefun
 
-@deftypefun int gcry_pk_testkey (GcrySexp @var{key})
+@deftypefun gpg_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
 
 Return 0 if @var{key} (either private or public) is sane.  NOTE: at
 the moment only the checking of secret keys is supported.
@@ -1350,7 +1359,7 @@ Please note that parameters not required should be passed as @code{NULL}.
 @c end gcry_pk_algo_info
 
 
-@deftypefun int gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
+@deftypefun gpg_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
 
 This is a general purpose function to perform certain control
 operations.  @var{cmd} controls what is to be done. The return value is
@@ -1370,7 +1379,7 @@ and @var{buflen} must have the value @code{sizeof (int)}.
 @noindent
 Libgcrypt also provides a function to generate public key pairs:
 
-@deftypefun int gcry_pk_genkey (@w{GcrySexp *@var{r_key}}, @w{GcrySexp @var{parms}})
+@deftypefun gpg_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
 
 This function create a new public key pair using information given in
 the S-expression @var{parms} and stores the private and the public key
@@ -1500,8 +1509,8 @@ to parse and construct them.  For detailed information, see
 @cite{Ron Rivest, code and description of S-expressions,
 @uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
 
-@deftp {Data type} GcrySexp
-The @code{GcrySexp} type describes an object with the Libgcrypt internal
+@deftp {Data type} gcry_sexp_t
+The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal
 representation of an S-expression.
 @end deftp
 
@@ -1512,7 +1521,7 @@ also a function to convert the internal representation back into one of
 the external formats:
 
 
-@deftypefun int gcry_sexp_new (@w{GcrySexp *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
+@deftypefun gpg_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
 
 This is the generic function to create an new S-expression object from
 its external representation in @var{buffer} of @var{length} bytes.  On
@@ -1526,7 +1535,7 @@ Note, that the caller is responsible for releasing the newly allocated
 S-expression using @code{gcry_sexp_release}.
 @end deftypefun
 
-@deftypefun int gcry_sexp_create (@w{GcrySexp *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
+@deftypefun gpg_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
 
 This function is identical to @code{gcry_sexp_new} but has an extra
 argument @var{freefnc}, which, when not set to @code{NULL}, is expected
@@ -1538,14 +1547,14 @@ might decide to directly use the provided buffer and thus avoid extra
 copying.
 @end deftypefun
 
-@deftypefun int gcry_sexp_sscan (@w{GcrySexp *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
+@deftypefun gpg_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
 
 This is another variant of the above functions.  It behaves nearly
 identical but provides an @var{erroff} argument which will receive the
 offset into the buffer where the parsing stopped on error.
 @end deftypefun
 
-@deftypefun int gcry_sexp_build (@w{GcrySexp *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
+@deftypefun gpg_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
 
 This function creates an internal S-expression from the string template
 @var{format} and stores it at the address of @var{r_sexp}. If there is a
@@ -1557,7 +1566,7 @@ expects arguments for some of these escape sequences right after
 
 @table @samp
 @item %m
-The next argument is expected to be of type @code{GcryMPI} and a copy of
+The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
 its value is inserted into the resulting S-expression.
 @item %s
 The next argument is expected to be of type @code{char *} and that
@@ -1573,7 +1582,7 @@ that the format character @samp{%%} does not exists, because a percent
 sign is not a valid character in an S-expression.
 @end deftypefun
 
-@deftypefun void gcry_sexp_release (@w{GcrySexp @var{sexp}})
+@deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}})
 
 Release the S-expression object @var{sexp}.
 @end deftypefun
@@ -1584,7 +1593,7 @@ The next 2 functions are used to convert the internal representation
 back into a regular external S-expression format and to show the
 structure for debugging.
 
-@deftypefun size_t gcry_sexp_sprint (@w{GcrySexp @var{sexp}}, @w{int @var{mode}}, @w{char *@var{buffer}}, @w{size_t @var{maxlength}})
+@deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{char *@var{buffer}}, @w{size_t @var{maxlength}})
 
 Copies the S-expression object @var{sexp} into @var{buffer} using the
 format specified in @var{mode}.  @var{maxlength} must be set to the
@@ -1612,7 +1621,7 @@ Returns the S-expression in advanced format.
 @end table
 @end deftypefun
 
-@deftypefun void gcry_sexp_dump (@w{GcrySexp @var{sexp}})
+@deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
 
 Dumps @var{sexp} in a format suitable for debugging to Libgcrypt's
 logging stream.
@@ -1632,11 +1641,6 @@ length to scan is given; this can be used for syntax checks of
 data passed from outside.  @var{errcode} and @var{erroff} may both be
 passed as @code{NULL}.
 
-@noindent
-@strong{Warning:} For historical reasons the error codes returned in
-@var{errcode} are negative numbers and don't match the regular error
-codes.  To convert to regular error codes, use the simple formula
-@code{rc = 200 - errcode}.
 @end deftypefun
 
 
@@ -1644,7 +1648,7 @@ codes.  To convert to regular error codes, use the simple formula
 There are a couple of functions to parse S-expressions and retrieve
 elements:
 
-@deftypefun GcrySexp gcry_sexp_find_token (@w{const GcrySexp @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})
+@deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})
 
 Scan the S-expression for a sublist with a type (the car of the list)
 matching the string @var{token}.  If @var{toklen} is not 0, the token is
@@ -1654,28 +1658,28 @@ when not found.
 @end deftypefun
 
 
-@deftypefun int gcry_sexp_length (@w{const GcrySexp @var{list}})
+@deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}})
 
 Return the length of the @var{list}.  For a valid S-expression this
 should be at least 1.
 @end deftypefun
 
 
-@deftypefun GcrySexp gcry_sexp_nth (@w{const GcrySexp @var{list}}, @w{int @var{number}})
+@deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}})
 
 Create and return a new S-expression from the element with index @var{number} in
 @var{list}.  Note that the first element has the index 0.  If there is
 no such element, @code{NULL} is returned.
 @end deftypefun
 
-@deftypefun GcrySexp gcry_sexp_car (@w{const GcrySexp @var{list}})
+@deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}})
 
 Create and return a new S-expression from the first element in
 @var{list}; this called the "type" and should always exist and be a
 string. @code{NULL} is returned in case of a problem.
 @end deftypefun
 
-@deftypefun GcrySexp gcry_sexp_cdr (@w{const GcrySexp @var{list}})
+@deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})
 
 Create and return a new list form all elements except for the first one.
 Note, that this function may return an invalid S-expression because it
@@ -1685,7 +1689,7 @@ lists.  Returns @code{NULL} on error.
 @end deftypefun
 
 
-@deftypefun {const char *} gcry_sexp_nth_data (@w{const GcrySexp @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}})
+@deftypefun {const char *} gcry_sexp_nth_data (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}})
 
 This function is used to get data from a @var{list}.  A pointer to the
 actual data with index @var{number} is returned and the length of this
@@ -1707,7 +1711,7 @@ printf ("my name is %.*s\n", (int)len, name);
 @end example
 @end deftypefun
 
-@deftypefun GcryMPI gcry_sexp_nth_mpi (@w{GcrySexp @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}})
+@deftypefun gcry_mpi_t gcry_sexp_nth_mpi (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}})
 
 This function is used to get and convert data from a @var{list}. This
 data is assumed to be an MPI stored in the format described by
@@ -1738,8 +1742,8 @@ better performance than with the standard C implementation.
 In the context of Libgcrypt and in most other applications, these large
 numbers are called MPIs (multi-precision-integers).
 
-@deftp {Data type} GcryMPI
-The @code{GcryMPI} type represents an object to hold an MPI.
+@deftp {Data type} gcry_mpi_t
+The @code{gcry_mpi_t} type represents an object to hold an MPI.
 @end deftp
 
 @noindent
@@ -1747,7 +1751,7 @@ To work with MPIs, storage must be allocated and released for the
 numbers.  This can be done with one of these functions:
 
 
-@deftypefun GcryMPI gcry_mpi_new (@w{unsigned int @var{nbits}})
+@deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}})
 
 Allocate a new MPI object, initialize it to 0 and initially allocate
 enough memory for a number of at least @var{nbits}.  This pre-allocation is
@@ -1755,7 +1759,7 @@ only a small performance issue and not actually necessary because
 Libgcrypt automatically re-allocates the required memory.
 @end deftypefun
 
-@deftypefun GcryMPI gcry_mpi_snew (@w{unsigned int @var{nbits}})
+@deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})
 
 This is identical to @code{gcry_mpi_new} but allocates the MPI in the so
 called "secure memory" which in turn will take care that all derived
@@ -1763,13 +1767,13 @@ values will also be stored in this "secure memory".  Use this for highly
 confidential data like private key parameters.
 @end deftypefun
 
-@deftypefun GcryMPI gcry_mpi_copy (@w{const GcryMPI @var{a}})
+@deftypefun gcry_mpi_t gcry_mpi_copy (@w{const gcry_mpi_t @var{a}})
 
 Create a new MPI as the exact copy of @var{a}.
 @end deftypefun
 
 
-@deftypefun void gcry_mpi_release (@w{GcryMPI @var{a}})
+@deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}})
 
 Release the MPI @var{a} and free all associated resources.  Passing
 @code{NULL} is allowed and ignored.  When a MPI stored in the "secure
@@ -1779,14 +1783,14 @@ memory" is released, that memory gets wiped out immediately.
 @noindent
 The simplest operations are used to assign a new value to an MPI:
 
-@deftypefun GcryMPI gcry_mpi_set (@w{GcryMPI @var{w}}, @w{const GcryMPI @var{u}})
+@deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}})
 
 Assign the value of @var{u} to @var{w} and return @var{w}.  If
 @code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
 value of @var{u} and returned.
 @end deftypefun
 
-@deftypefun GcryMPI gcry_mpi_set_ui (@w{GcryMPI @var{w}}, @w{unsigned long @var{u}})
+@deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}})
 
 Assign the value of @var{u} to @var{w} and return @var{w}.  If
 @code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
@@ -1795,7 +1799,7 @@ int} as type for @var{u} and thus it is only possible to set @var{w} to
 small values (usually up to the word size of the CPU).
 @end deftypefun
 
-@deftypefun void gcry_mpi_swap (@w{GcryMPI @var{a}}, @w{GcryMPI @var{b}})
+@deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
 
 Swap the values of @var{a} and @var{b}.
 @end deftypefun
@@ -1804,7 +1808,7 @@ Swap the values of @var{a} and @var{b}.
 The following functions are used to convert between an external
 representation of an MPI and the internal one of Libgcrypt.
 
-@deftypefun int gcry_mpi_scan (@w{GcryMPI *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const char *@var{buffer}}, @w{size_t *@var{nbytes}})
+@deftypefun int gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const char *@var{buffer}}, @w{size_t *@var{nbytes}})
 
 Convert the external representation of an integer stored in @var{buffer}
 with a length stored at the address of @var{nbytes} into a newly created
@@ -1840,7 +1844,7 @@ format (MSB first).
 @end deftypefun
 
 
-@deftypefun int gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{char *@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const GcryMPI @var{a}})
+@deftypefun int gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{char *@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}})
 
 Convert the MPI @var{a} into an external representation described by
 @var{format} (see above) and store it in the provided @var{buffer} which
@@ -1849,7 +1853,7 @@ variable @var{nbytes} points to; this variable will receive the actual
 number of bytes stored after a successful operation.
 @end deftypefun
 
-@deftypefun int gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{void **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const GcryMPI @var{a}})
+@deftypefun int gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{void **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}})
 
 Convert the MPI @var{a} into an external representation described by
 @var{format} (see above) and store it in a newly allocated buffer which
@@ -1861,85 +1865,85 @@ number of bytes stored in this buffer will be stored in the variable
 @noindent
 Basic arithmetic operations:
 
-@deftypefun void gcry_mpi_add (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{GcryMPI @var{v}})
+@deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
 
 @math{@var{w} = @var{u} + @var{v}}.
 @end deftypefun
 
 
-@deftypefun void gcry_mpi_add_ui (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{unsigned long @var{v}})
+@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
 
 @math{@var{w} = @var{u} + @var{v}}.  Note, that @var{v} is an unsigned integer.
 @end deftypefun
 
 
-@deftypefun void gcry_mpi_addm (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{GcryMPI @var{v}}, @w{GcryMPI @var{m}})
+@deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
 
 @math{var{w} = @var{u} + @var{v} \bmod @var{m}}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_sub (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{GcryMPI @var{v}})
+@deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
 
 @math{@var{w} = @var{u} - @var{v}}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_sub_ui (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{unsigned long @var{v}})
+@deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
 
 @math{@var{w} = @var{u} - @var{v}}.  @var{v} is an unsigned integer.
 @end deftypefun
 
-@deftypefun void gcry_mpi_subm (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{GcryMPI @var{v}}, @w{GcryMPI @var{m}})
+@deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
 
 @math{@var{w} = @var{u} - @var{v} \bmod @var{m}}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_mul (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{GcryMPI @var{v}})
+@deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
 
 @math{@var{w} = @var{u} * @var{v}}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_mul_ui (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{unsigned long @var{v}})
+@deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
 
 @math{@var{w} = @var{u} * @var{v}}.  @var{v} is an unsigned integer.
 @end deftypefun
 
-@deftypefun void gcry_mpi_mulm (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{GcryMPI @var{v}}, @w{GcryMPI @var{m}})
+@deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
 
 @math{@var{w} = @var{u} * @var{v} \bmod @var{m}}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_mul_2exp (@w{GcryMPI @var{w}}, @w{GcryMPI @var{u}}, @w{unsigned long @var{e}})
+@deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}})
 
 @c FIXME: I am in need for a real TeX{info} guru:
 @c I don't know why TeX can grok @var{e} here.
 @math{@var{w} = @var{u} * 2^e}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_div (@w{GcryMPI @var{q}}, @w{GcryMPI @var{r}}, @w{GcryMPI @var{dividend}}, @w{GcryMPI @var{divisor}}, @w{int @var{round}})
+@deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}})
 
 @math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} =
 @var{dividend} \bmod @var{divisor}}.  @var{q} and @var{r} may be passed
 as @code{NULL}.  @var{round} should be negative or 0.
 @end deftypefun
 
-@deftypefun void gcry_mpi_mod (@w{GcryMPI @var{r}}, @w{GcryMPI @var{dividend}}, @w{GcryMPI @var{divisor}})
+@deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}})
 
 @math{@var{r} = @var{dividend} \bmod @var{divisor}}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_powm (@w{GcryMPI @var{w}}, @w{const GcryMPI @var{b}}, @w{const GcryMPI @var{e}}, @w{const GcryMPI @var{m}})
+@deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}})
 
 @c I don't know why TeX can grok @var{e} here.
 @math{@var{w} = @var{b}^e \bmod @var{m}}.
 @end deftypefun
 
-@deftypefun int gcry_mpi_gcd (@w{GcryMPI @var{g}}, @w{GcryMPI @var{a}}, @w{GcryMPI @var{b}})
+@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
 
 Set @var{g} to the greatest common divisor of @var{a} and @var{b}.  
 Return true if the @var{g} is 1.
 @end deftypefun
 
-@deftypefun int gcry_mpi_invm (@w{GcryMPI @var{x}}, @w{GcryMPI @var{a}}, @w{GcryMPI @var{m}})
+@deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}})
 
 Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}.
 Return true if the inverse exists.
@@ -1951,14 +1955,14 @@ Return true if the inverse exists.
 The next 2 functions are used to compare MPIs:
 
 
-@deftypefun int gcry_mpi_cmp (@w{const GcryMPI @var{u}}, @w{const GcryMPI @var{v}})
+@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}})
 
 Compare the big integer number @var{u} and @var{v} returning 0 for
 equality, a positive value for @var{u} > @var{v} and a negative for
 @var{u} < @var{v}.
 @end deftypefun
 
-@deftypefun int gcry_mpi_cmp_ui (@w{const GcryMPI @var{u}}, @w{unsigned long @var{v}})
+@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
 
 Compare the big integer number @var{u} with the unsigned integer @var{v}
 returning 0 for equality, a positive value for @var{u} > @var{v} and a
@@ -1971,37 +1975,37 @@ There are a couple of functions to get information on arbitrary bits
 in an MPI and to set or clear them:
 
 
-@deftypefun {unsigned int} gcry_mpi_get_nbits (@w{GcryMPI @var{a}})
+@deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}})
 
 Return the number of bits required to represent @var{a}.
 @end deftypefun
 
-@deftypefun int gcry_mpi_test_bit (@w{GcryMPI @var{a}}, @w{unsigned int @var{n}})
+@deftypefun int gcry_mpi_test_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
 
 Return true if bit number @var{n} (counting from 0) is set in @var{a}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_set_bit (@w{GcryMPI @var{a}}, @w{unsigned int @var{n}})
+@deftypefun void gcry_mpi_set_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
 
 Set bit number @var{n} in @var{a}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_clear_bit (@w{GcryMPI @var{a}}, @w{unsigned int @var{n}})
+@deftypefun void gcry_mpi_clear_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
 
 Clear bit number @var{n} in @var{a}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_set_highbit (@w{GcryMPI @var{a}}, @w{unsigned int @var{n}})
+@deftypefun void gcry_mpi_set_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
 
 Set bit number @var{n} in @var{a} and clear all bits greater than @var{n}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_clear_highbit (@w{GcryMPI @var{a}}, @w{unsigned int @var{n}})
+@deftypefun void gcry_mpi_clear_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
 
 Clear bit number @var{n} in @var{a} and all bits greater than @var{n}.
 @end deftypefun
 
-@deftypefun void gcry_mpi_rshift (@w{GcryMPI @var{x}}, @w{GcryMPI @var{a}}, @w{unsigned int @var{n}})
+@deftypefun void gcry_mpi_rshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
 
 Shift the value of @var{a} by @var{n} bits to the right and store the
 result in @var{x}.
@@ -2012,7 +2016,7 @@ result in @var{x}.
 The remaining MPI functions take care of very special properties of the
 implementation:
 
-@deftypefun GcryMPI gcry_mpi_set_opaque (@w{GcryMPI @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}})
+@deftypefun gcry_mpi_t gcry_mpi_set_opaque (@w{gcry_mpi_t @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}})
 
 Store @var{nbits} of the value @var{p} points to in @var{a} and mark
 @var{a} as an opaque value (i.e. an value that can't be used for any
@@ -2020,7 +2024,7 @@ math calculation and is only used to store an arbitrary bit pattern in
 @var{a}.
 @end deftypefun
 
-@deftypefun {void *} gcry_mpi_get_opaque (@w{GcryMPI @var{a}}, @w{unsigned int *@var{nbits}})
+@deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}})
 
 Return a pointer to an opaque value stored in @var{a} and return its
 size in @var{nbits}.  Note, that the returned pointer is still owned by
@@ -2028,20 +2032,20 @@ size in @var{nbits}.  Note, that the returned pointer is still owned by
 MPI.
 @end deftypefun
 
-@deftypefun void gcry_mpi_set_flag (@w{GcryMPI @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
+@deftypefun void gcry_mpi_set_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
 
 Set the @var{flag} for the MPI @var{a}.  Currently only the flag
 @code{GCRYMPI_FLAG_SECURE} is allowed to convert @var{a} into an MPI
 stored in "secure memory".
 @end deftypefun
 
-@deftypefun void gcry_mpi_clear_flag (@w{GcryMPI @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
+@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
 
 Clear @var{flag} for the big integer @var{a}.  Note, that this function is
 currently useless as no flags are allowed.
 @end deftypefun
 
-@deftypefun int gcry_mpi_get_flag (@w{GcryMPI @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
+@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
 
 Return true when the @var{flag} is set for @var{a}.
 @end deftypefun
@@ -2289,8 +2293,8 @@ Helper functions.
 @node Error Handling
 @chapter Error Handling
 
-Most functions in Libgcrypt are returning an error if they fail.  For
-this reason, the application should always catch the error condition and
+Most functions in Libgcrypt 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 canceling the operation.
@@ -2298,6 +2302,10 @@ message to the user and canceling 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.
 
+GnuPG components, including libgcrypt, use an extra library named
+libgpg-error to provide a common error handling scheme.  For more
+information on libgpg-error, see the according manual.
+
 @menu
 * Error values::                A list of all error values used.
 * Error strings::               How to get a descriptive string from a value.
@@ -2306,9 +2314,145 @@ operation, but the result of an operation that failed properly.
 @node Error values
 @section Error values
 
-Errors are return as an @code{int} 
-Except for the EOF and No_Error cases an application should always
-use the constants.  Possible values are:
+The type of error values is @code{gpg_error_t}.  A value of this type
+contains two information: an `error code' of type
+@code{gpg_err_code_t} and an `error source' of type
+@code{gpg_err_source_t}.  These values can be extracted with the
+functions @code{gpg_err_code} and @code{gpg_err_source}.
+
+@table @code
+
+@item GPG_ERR_NO_ERROR
+This value indicates success.  The value of this error code is
+guaranteed to be @code{0}.
+
+@item GPG_ERR_GENERAL
+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.
+
+@item GPG_ERR_EOF
+This value indicates the end of a list, buffer or file.
+
+@item GPG_ERR_PUBKEY_ALGO
+Invalid public key algorithm.
+
+@item GPG_ERR_DIGEST_ALGO
+Invalid message digest algorithm.
+
+@item GPG_ERR_BAD_PUBKEY
+Bad public key.
+
+@item GPG_ERR_BAD_SECKEY
+Bad secret key.
+
+@item GPG_ERR_BAD_SIGNATURE
+Bad signature.
+
+@item GPG_ERR_CIPHER_ALGO
+Invalid cipher algorithm.
+
+@item GPG_ERR_BAD_MPI
+Problem with an MPI's value.
+
+@item GPG_ERR_WRONG_PUBKEY_ALGO
+Wrong public key algorithm.
+
+@item GPG_ERR_WEAK_KEY
+Weak encryption key detected.
+
+@item GPG_ERR_INV_KEYLEN
+Invalid length of a key.
+
+@item GPG_ERR_INV_ARG
+Invalid argument.
+
+@item GPG_ERR_SELFTEST_FAILED
+A self test failed.
+
+@item GPG_ERR_INV_OP
+Invalid operation code or control command.
+
+@item GPG_ERR_OUT_OF_CORE
+Out of core; not enough memory available to perform operation.
+
+@item GPG_ERR_INTERNAL
+Internal error.  This is most likely a bug in Libgcrypt or due to an
+incomplete build or installation.
+
+@item GPG_ERR_EOF = 64 FIXME
+End-of-file condition.
+
+@item GPG_ERR_INV_OBJ
+An object is not valid.
+
+@item GPG_ERR_TOO_SHORT
+Provided buffer or object too short.
+
+@item GPG_ERR_TOO_LARGE
+Object is too large.
+
+@item GPG_ERR_NO_OBJ
+Missing item in an object.
+
+@item GPG_ERR_NOT_IMPLEMENTED
+Not implemented.
+
+@item GPG_ERR_CONFLICT
+Conflicting use of function or values.
+
+@item GPG_ERR_INV_CIPHER_MODE
+Invalid or unsupported cipher mode.
+
+@item GPG_ERR_INV_FLAG
+Invalid flag.
+
+@item GPG_ERR_SEXP_INV_LEN_SPEC
+The S-expression has an invalid length specification.
+
+@item GPG_ERR_SEXP_STRING_TOO_LONG
+The encoded length of an S-expression is longer than the entire object.
+
+@item GPG_ERR_SEXP_UNMATCHED_PAREN
+There are unmatched parenthesis in the S-expression.
+
+@item GPG_ERR_SEXP_NOT_CANONICAL
+Not a canonical encoded S-expression.
+
+@item GPG_ERR_SEXP_BAD_CHARACTER
+Bad character detected in an S-expression. 
+
+@item GPG_ERR_SEXP_BAD_QUOTATION
+Bad quotation in an S-expression.  Might also indicate an invalid hex or
+octal value.
+
+@item GPG_ERR_SEXP_ZERO_PREFIX
+The length field of an S-expression element is prefixed with a 0.
+
+@item GPG_ERR_SEXP_NESTED_DH
+Nested display hints found in an S-expression.
+
+@item GPG_ERR_SEXP_UNMATCHED_DH
+Unmatched display hint found in an S-expression.
+
+@item GPG_ERR_SEXP_UNEXPECTED_PUNC
+Unexpected reserved punctuation found in an S-expression.
+
+@item GPG_ERR_SEXP_BAD_HEX_CHAR
+A bad hexadecimal character was found in an S-expression
+
+@item GPG_ERR_SEXP_ODD_HEX_NUMBERS
+An odd number of hexadecimal characters was found in an S-expression.
+
+@item GPG_ERR_SEXP_BAD_OCT_CHAR
+A bad octal character was found in an S-expression.
+
+@end table
+
+@strong{Note:} In order to provide temporary API compatibility with
+the old error handling scheme, the following @strong{deprecated}
+constants are still supported.  They are mapped to the new
+libgpg-error values and are therefore ABI compatible.
 
 @table @code
 @item GCRYERR_EOF
@@ -2405,7 +2549,7 @@ The S-expression has an invalid length specification.
 @item GCRYERR_SEXP_STRING_TOO_LONG
 The encoded length of an S-expression is longer than the entire object.
 
-@item GCRYERR_SEXP_UNMATCHED_PAREN
+v@item GCRYERR_SEXP_UNMATCHED_PAREN
 There are unmatched parenthesis in the S-expression.
 
 @item GCRYERR_SEXP_NOT_CANONICAL
@@ -2445,6 +2589,28 @@ A bad octal character was found in an S-expression.
 @node Error strings
 @section Error strings
 
+libgpg-error contains the following functions for converting error
+codes and error sources into their human-readable string
+representation:
+
+@deftypefun {const char *} gpg_strerror (@w{gpg_error_t @var{err}})
+
+This function returns a pointer to a statically allocated string
+containing a description of the error code in the error value ERR.
+
+@end deftypefun
+
+@deftypefun {const char *} gpg_strsource (@w{gpg_error_t @var{err}})
+
+This function returns a pointer to a statically allocated string
+containing a description of the error source in the error value ERR.
+
+@end deftypefun
+
+@strong{Note:} In order to provide temporary API compatibility with
+the old error handling scheme, the following @strong{deprecated}
+function is still supported.
+
 @deftypefun {const char *} gcry_strerror (@w{int @var{err}})
 
 The function @code{gcry_strerror} returns a pointer to a statically
@@ -2453,9 +2619,6 @@ value @var{err}.  This string can be used to output a diagnostic
 message to the user.
 @end deftypefun
 
-
-
-
 @c **********************************************************
 @c *******************  Appendices  *************************
 @c **********************************************************