doc/

2008-03-11  Marcus Brinkmann  <[email protected]>

	* gpgme.texi (File Based Data Buffers): Document the need for
	blocking operations.
	(Callback Based Data Buffers): Likewise.

gpgme/
2008-03-11  Marcus Brinkmann  <[email protected]>

	* data.c (gpgme_data_read, gpgme_data_write): Retry on EINTR.

2 files changed, 30 insertions, 0 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 38e53a68..04ce809d 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2008-03-11  Marcus Brinkmann  <[email protected]>
+
+	* gpgme.texi (File Based Data Buffers): Document the need for
+	blocking operations.
+	(Callback Based Data Buffers): Likewise.
+
 2008-03-05  Marcus Brinkmann  <[email protected]>
 
 	* gpgme.texi (Library Version Check): Rename snippet function to
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index d854f98c..1f1a8a6c 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -1464,6 +1464,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.
@@ -1575,6 +1583,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.
@@ -1590,6 +1602,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.
@@ -1611,6 +1627,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.
@@ -1624,6 +1644,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.