2004-01-31 Marcus Brinkmann <marcus@g10code.de>

* configure.ac: Add invocation of AC_SYS_LARGEFILE, AC_TYPE_OFF_T
	and AC_FUNC_FSEEKO.

doc/
2004-02-01  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.texi (Largefile Support): New section.

gpgme/
2004-02-01  Marcus Brinkmann  <marcus@g10code.de>

	* data-compat.c (gpgme_data_new_from_filepart): Call fseeko if
	available.
	* data-stream.c (stream_seek): Likewise.

ChangeLog

@@ -1,3 +1,8 @@
+2004-01-31  Marcus Brinkmann  <marcus@g10code.de>
+
+	* configure.ac: Add invocation of AC_SYS_LARGEFILE, AC_TYPE_OFF_T
+	and AC_FUNC_FSEEKO.
+
 2004-01-12  Werner Koch  <wk@gnupg.org>
 
 	Released 0.4.4.
@@ -435,7 +440,7 @@
 	* autogen.sh: Added option --build-w32.
 
 
- Copyright 2001, 2002 g10 Code GmbH
+ Copyright 2001, 2002, 2003, 2004 g10 Code GmbH
 
  This file is free software; as a special exception the author gives
  unlimited permission to copy and/or distribute it, with or without

NEWS

@@ -1,3 +1,66 @@
+Noteworthy changes in version 0.4.5 (unreleased)
+------------------------------------------------
+
+ * GPGME is now compiled with LFS (large file support) by default.
+   This means that _all_ programs using GPGME must be compiled with
+   LFS support enabled by default.  You can do this easily with
+   autoconf, by using the AC_SYS_LARGEFILE macro.  Or you can do this
+   without autoconf by defining the preprocessor symbol
+   _FILE_OFFSET_BITS to 64 (by passing the -D_FILE_OFFSET_BITS=64 to
+   the C compiler command line, or by defining this preprocessor
+   symbol before including any system header files).  For more
+   details, read the section on LFS in the manual.
+
+   Up to now, it was undocumented that GPGME was not using LFS.
+   But the public interfaces use off_t, and file descriptors are
+   exchanged between the application and GPGME.  This was an oversight,
+   and bound to cause troubles in the future.
+
+   Writing GPGME as a dual mode library that seamlessly supports LFS
+   while keeping backwards compatibility is possible, but does not
+   solve the problem: Many applications already expect GPGME to have
+   LFS (they are compiled with off_t being a 64bit value).  This is true
+   in particular for the popular Gtk+ and Qt programs.
+
+   So, although this is an ABI (but not an API) break, we will not
+   change the library version to reflect that.  Because the interfaces
+   affected are probably not used yet in any GPGME 0.4 based
+   application, we don't expect any real failures from this change.
+   In fact, applications already using LFS will have some subtle bugs
+   fixed.
+
+   However, if you encounter an application using GPGME 0.4.x that
+   does _not_ use LFS by default (off_t is a 32bit value), _and_
+   uses at least one of the functions gpgme_data_seek,
+   gpgme_data_new_from_filepart, or a gpgme_data_seek_cb_t with
+   gpgme_data_new_from_cbs, then indeed this library will be ABI
+   incompatible with the program.  As said above, we don't believe
+   such a program exists.  If we are in error, then you have two
+   options: As a quick hack, you can configure GPGME with the
+   --disable-largefile option.  This will revert the change, and GPGME
+   will not use LFS.  However, GPGME will be incompatible with
+   programs that expect GPGME to use LFS.  All applications are
+   required to use LFS when using GPGME, so this is only good as a
+   temporary local work-around.
+
+   The other option is to change the versioning of the library and
+   recompile all applications.  We have reserved a special version of
+   the library for that, so you can do that without expecting a
+   version clash in the future.  Furthermore, everyone who does this
+   will agree on the version to use (this is important for
+   distribution makers).  Read the comment in configure.ac (before
+   LIBGPGME_LT_AGE) if you want to do this.  Please don't do this
+   blindly: As stated above, we think it is unlikely this measure is
+   needed.  Still, it is there if necessary.  If in doubt, contact us
+   and we will give our advise for your specific situation.
+
+ * Interface changes relative to the 0.4.4 release:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+gpgme_data_seek_cb_t		CHANGED: off_t is now a largefile type.
+gpgme_data_seek			CHANGED: off_t is now a largefile type.
+gpgme_data_new_from_filepart	CHANGED: off_t is now a largefile type.
+
+
 Noteworthy changes in version 0.4.4 (2004-01-12)
 ------------------------------------------------
 
@@ -868,7 +931,7 @@ Noteworthy changes in version 0.2.1 (2001-04-02)
  * Made the W32 support more robust.
 
 
- Copyright 2001, 2002, 2003 g10 Code GmbH
+ Copyright 2001, 2002, 2003, 2004 g10 Code GmbH
 
  This file is free software; as a special exception the author gives
  unlimited permission to copy and/or distribute it, with or without

configure.ac

@@ -1,6 +1,6 @@
 # configure.in for GPGME
 # Copyright (C) 2000 Werner Koch (dd9jn)
-# Copyright (C) 2001, 2002, 2003 g10 Code GmbH
+# Copyright (C) 2001, 2002, 2003, 2004 g10 Code GmbH
 # 
 # This file is part of GPGME.
 # 
@@ -29,11 +29,13 @@ AC_INIT(gpgme, 0.4.4, [bug-gpgme@gnupg.org])
 #   (Code changed:			REVISION++)
 #   (Interfaces added/removed/changed:	CURRENT++, REVISION=0)
 #   (Interfaces added:			AGE++)
-#   (Interfaces removed:		AGE=0)
+#   (Interfaces removed/changed:	AGE=0)
 #
-LIBGPGME_LT_CURRENT=12
+LIBGPGME_LT_CURRENT=13
-LIBGPGME_LT_AGE=1
+# Subtract 2 from this value if you want to make the LFS transition an
-LIBGPGME_LT_REVISION=1
+# ABI break.  [Note to self: Remove this comment with the next regular break.]
+LIBGPGME_LT_AGE=2
+LIBGPGME_LT_REVISION=0
 NEED_GPG_VERSION=1.2.2
 NEED_GPGSM_VERSION=1.9.3
 ##############################################
@@ -144,7 +146,8 @@ AC_CHECK_HEADERS(sys/select.h)
 
 # Type checks.
 AC_CHECK_SIZEOF(unsigned int)
-
+AC_SYS_LARGEFILE
+AC_TYPE_OFF_T
 
 # Checks for compiler features.
 if test "$GCC" = yes; then
@@ -153,6 +156,8 @@ fi
 
 
 # Checks for library functions.
+AC_FUNC_FSEEKO
+
 AC_REPLACE_FUNCS(stpcpy)
 
 AC_REPLACE_FUNCS(vasprintf)

doc/ChangeLog

@@ -1,3 +1,7 @@
+2004-02-01  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gpgme.texi (Largefile Support): New section.
+
 2004-01-13  Marcus Brinkmann  <marcus@g10code.de>
 
 	* gpgme.texi (Key Management): Fix exportable field.
@@ -560,7 +564,7 @@
 	* Makefile.am (info_TEXINFOS): New variable.
 	(gpgme_TEXINFOS): Likewise.
 
- Copyright 2002 g10 Code GmbH
+ Copyright 2002, 2003, 2004 g10 Code GmbH
 
  This file is free software; as a special exception the author gives
  unlimited permission to copy and/or distribute it, with or without

doc/gpgme.texi

@@ -20,7 +20,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
 @value{VERSION}.
 
-Copyright @copyright{} 2002, 2003 g10 Code GmbH.
+Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -104,6 +104,7 @@ Preparation
 
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support::             How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
 * Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
@@ -407,6 +408,82 @@ Supported thread packages are @option{--thread=pth} and
 @option{--thread=pthread}.
 
 
+@node Largefile Support
+@section Largefile Support (LFS)
+@cindex largfile support
+@cindex LFS
+
+@acronym{GPGME} is compiled with largfile support by default, if it is
+available on the system.  This means that GPGME supports files larger
+than two gigabyte in size, if the underlying operating system can.  On
+some systems, largefile support is already the default.  On such
+systems, nothing special is required.  However, some systems provide
+only support for files up to two gigabyte in size by default.  Support
+for larger file sizes has to be specifically enabled.
+
+To make a difficult situation even more complex, such systems provide
+two different types of largefile support.  You can either get all
+relevant functions replaced with alternatives that are largefile
+capable, or you can get new functions and data types for largefile
+support added.  Those new functions have the same name as their
+smallfile counterparts, but with a suffix of 64.
+
+An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC
+systems.  To address offsets in large files, you can either enable
+largefile support add-on.  Then a new data type @code{off64_t} is
+provided, which is 64 bit wide.  Or you can replace the existing
+@code{off_t} data type with its 64 bit wide counterpart.  All
+occurences of @code{off_t} are then automagically replaced.
+
+As if matters were not complex enough, there are also two different
+types of file descriptors in such systems.  This is important because
+if file descriptors are exchanged between programs that use a
+different maximum file size, certain errors must be produced on some
+file descriptors to prevent subtle overflow bugs from occuring.
+
+As you can see, supporting two different maximum file sizes at the
+same time is not at all an easy task.  However, the maximum file size
+does matter for @acronym{GPGME}, because some data types it uses in
+its interfaces are affected by that.  For example, the @code{off_t}
+data type is used in the @code{gpgme_data_seek} function, to match its
+@acronym{POSIX} counterpart.  This affects the call-frame of the
+function, and thus the ABI of the library.  Furthermore, file
+descriptors can be exchanged between GPGME and the application.
+
+For you as the user of the library, this means that your program must
+be compiled in the same file size mode as the library.  Luckily, there
+is absolutely no valid reason for new programs to not enable largefile
+support by default and just use that.  The compatibility modes (small
+file sizes or dual mode) can be considered an historic artefact, only
+useful to allow for a transitional period.
+
+@acronym{GPGME} is compiled using the largfile support by default.
+This means that your application must do the same, at least as far as
+it is relevant for using the @file{gpgme.h} header file.  All types in
+this header files refer to their largefile counterparts, if they are
+different from any default types on the system.
+
+You can enable largefile support, if it is different from the default
+on the system the application is compiled on, by using the Autoconf
+macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
+worry about anything else: It will just work.  In this case you might
+also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
+interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+
+If you do not use Autoconf, you can define the preprocessor symbol
+@code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
+files, for example by specifying the option
+@code{-D_FILE_OFFSET_BITS=64} on the compiler command line.  You will
+also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to
+1 in this case, to take advantage of some new interfaces.
+
+If you do not want to do either of the above, you probably know enough
+about the issue to invent your own solution.  Just keep in mind that
+the @acronym{GPGME} header file expects that largefile support is
+enabled, if it is available.  In particular, we do not support dual
+mode (@code{_LARGEFILE64_SOURCE}).
+
+
 @node Using Automake
 @section Using Automake
 @cindex automake

gpgme/ChangeLog

@@ -1,3 +1,9 @@
+2004-02-01  Marcus Brinkmann  <marcus@g10code.de>
+
+	* data-compat.c (gpgme_data_new_from_filepart): Call fseeko if
+	available.
+	* data-stream.c (stream_seek): Likewise.
+
 2004-01-16  Werner Koch  <wk@gnupg.org>
 
 	* conversion.c (_gpgme_map_gnupg_error): Handle numerical codes as
@@ -4313,7 +4319,7 @@
 	* data.c (gpgme_data_rewind): Allow to rewind data_type_none.
 
 
- Copyright 2001, 2002 g10 Code GmbH
+ Copyright 2001, 2002, 2003, 2004 g10 Code GmbH
 
  This file is free software; as a special exception the author gives
  unlimited permission to copy and/or distribute it, with or without

gpgme/data-compat.c

@@ -1,5 +1,5 @@
 /* data-compat.c - Compatibility interfaces for data objects.
-   Copyright (C) 2002, 2003 g10 Code GmbH
+   Copyright (C) 2002, 2003, 2004 g10 Code GmbH
  
    This file is part of GPGME.
  
@@ -39,6 +39,7 @@ gpgme_data_new_from_filepart (gpgme_data_t *dh, const char *fname,
 {
   gpgme_error_t err;
   char *buf = NULL;
+  int res;
 
   if (stream && fname)
     return gpg_error (GPG_ERR_INV_VALUE);
@@ -48,7 +49,14 @@ gpgme_data_new_from_filepart (gpgme_data_t *dh, const char *fname,
   if (!stream)
     return gpg_error_from_errno (errno);
 
-  if (fseek (stream, offset, SEEK_SET))
+#ifdef HAVE_FSEEKO
+  res = fseeko (stream, offset, SEEK_SET);
+#else
+  /* FIXME: Check for overflow, or at least bail at compilation.  */
+  res = fseek (stream, offset, SEEK_SET);
+#endif
+
+  if (res)
     {
       int saved_errno = errno;
       if (fname)

gpgme/data-stream.c

@@ -1,5 +1,5 @@
 /* data-stream.c - A stream based data object.
-   Copyright (C) 2002 g10 Code GmbH
+   Copyright (C) 2002, 2004 g10 Code GmbH
  
    This file is part of GPGME.
  
@@ -50,7 +50,12 @@ stream_write (gpgme_data_t dh, const void *buffer, size_t size)
 static off_t
 stream_seek (gpgme_data_t dh, off_t offset, int whence)
 {
+#ifdef HAVE_FSEEKO
+  return fseeko (dh->data.stream, offset, whence);
+#else
+  /* FIXME: Check for overflow, or at least bail at compilation.  */
   return fseek (dh->data.stream, offset, whence);
+#endif
 }