diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gpgme.texi | 24 |
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. |