Imported Upstream version 1.4.2upstream/1.4.2

1 files changed, 52 insertions, 21 deletions

diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1
index beb3286..2066b90 100644
--- a/doc/gpgme.info-1
+++ b/doc/gpgme.info-1
@@ -22,8 +22,8 @@ General Public License for more details.
 
    This file documents the GPGME library.
 
-   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.1.
+   This is Edition 1.4.2, last updated 28 May 2013, of `The `GnuPG Made
+Easy' Reference Manual', for Version 1.4.2.
 
    Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2012,
 2013 g10 Code GmbH.
@@ -45,8 +45,8 @@ File: gpgme.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Main Menu
 *********
 
-This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG Made
-Easy' Reference Manual', for Version 1.4.1 of the GPGME library.
+This is Edition 1.4.2, last updated 28 May 2013, of `The `GnuPG Made
+Easy' Reference Manual', for Version 1.4.2 of the GPGME library.
 
 * Menu:
 
@@ -444,18 +444,38 @@ support by default and just use that.  The compatibility modes (small
 file sizes or dual mode) can be considered an historic artefact, only
 useful to allow for a transitional period.
 
-   GPGME is compiled using largefile support by default.  This means
-that your application must do the same, at least as far as it is
-relevant for using the `gpgme.h' header file.  All types in this header
-files refer to their largefile counterparts, if they are different from
-any default types on the system.
-
-   You can enable largefile support, if it is different from the default
-on the system the application is compiled on, by using the Autoconf
-macro `AC_SYS_LARGEFILE'.  If you do this, then you don't need to worry
-about anything else: It will just work.  In this case you might also
-want to use `AC_FUNC_FSEEKO' to take advantage of some new interfaces,
-and `AC_TYPE_OFF_T' (just in case).
+   On POSIX platforms GPGME is compiled using largefile support by
+default.  This means that your application must do the same, at least
+as far as it is relevant for using the `gpgme.h' header file.  All
+types in this header files refer to their largefile counterparts, if
+they are different from any default types on the system.
+
+   On 32 and 64 bit Windows platforms `off_t' is declared as 32 bit
+signed integer.  There is no specific support for LFS in the C library.
+The recommendation from Microsoft is to use the native interface
+(`CreateFile' et al.) for large files.  Released binary versions of
+GPGME (libgpgme-11.dll) have always been build with a 32 bit `off_t'.
+To avoid an ABI break we stick to this convention for 32 bit Windows by
+using `long' there.  GPGME versions for 64 bit Windows have never been
+released and thus we are able to use `int64_t' instead of `off_t'
+there.  For easier migration the typedef `gpgme_off_t' has been
+defined.  The reason we cannot use `off_t' directly is that some
+toolchains (e.g. mingw64) introduce a POSIX compatible hack for
+`off_t'.  Some widely used toolkits make use of this hack and in turn
+GPGME would need to use it also.  However, this would introduce an ABI
+break and existing software making use of libgpgme might suffer from a
+severe break.  Thus with version 1.4.2 we redefined all functions using
+`off_t' to use `gpgme_off_t' which is defined as explained above.  This
+way we keep the ABI well defined and independent of any toolchain
+hacks.  The bottom line is that LFS support in GPGME is only available
+on 64 bit versions of Windows.
+
+   On POSIX platforms you can enable largefile support, if it is
+different from the default on the system the application is compiled
+on, by using the Autoconf macro `AC_SYS_LARGEFILE'.  If you do this,
+then you don't need to worry about anything else: It will just work.
+In this case you might also want to use `AC_FUNC_FSEEKO' to take
+advantage of some new interfaces, and `AC_TYPE_OFF_T' (just in case).
 
    If you do not use Autoconf, you can define the preprocessor symbol
 `_FILE_OFFSET_BITS' to 64 _before_ including any header files, for
@@ -1449,6 +1469,17 @@ 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.
 
+ -- Data type: gpgme_off_t
+     On POSIX platforms the `gpgme_off_t' type is an alias for `off_t';
+     it may be used interchangeable.  On Windows platforms
+     `gpgme_off_t' is defined as a long (i.e. 32 bit) for 32 bit
+     Windows and as a 64 bit signed integer for 64 bit Windows.
+
+ -- Data type: gpgme_ssize_t
+     The `gpgme_ssize_t' type is an alias for `ssize_t'.  It has only
+     been introduced to overcome portability problems pertaining to the
+     declaration of `ssize_t' by different toolchains.
+
 * Menu:
 
 * Creating Data Buffers::         Creating new data buffers.
@@ -2383,9 +2414,9 @@ are specified.  This is always done by specifying the respective keys
 that should be used for the operation.  The following section describes
 how such keys can be selected and manipulated.
 
- -- Data type: gpgme_sub_key_t
-     The `gpgme_sub_key_t' type is a pointer to a subkey structure.
-     Sub keys are one component of a `gpgme_key_t' object.  In fact,
+ -- Data type: gpgme_subkey_t
+     The `gpgme_subkey_t' type is a pointer to a subkey structure.  Sub
+     keys are one component of a `gpgme_key_t' object.  In fact,
      subkeys are those parts that contains the real information about
      the individual cryptographic keys that belong to the same key
      object.  One `gpgme_key_t' can contain several subkeys.  The first
@@ -2393,7 +2424,7 @@ how such keys can be selected and manipulated.
 
      The subkey structure has the following members:
 
-    `gpgme_sub_key_t next'
+    `gpgme_subkey_t next'
           This is a pointer to the next subkey structure in the linked
           list, or `NULL' if this is the last element.
 
@@ -2627,7 +2658,7 @@ how such keys can be selected and manipulated.
           If `protocol' is `GPGME_PROTOCOL_OpenPGP', then this is the
           owner trust.
 
-    `gpgme_sub_key_t subkeys'
+    `gpgme_subkey_t subkeys'
           This is a linked list with the subkeys of the key.  The first
           subkey in the list is the primary key and usually available.