Next: , Up: Manipulating Data Buffers


6.3.1 Data Buffer I/O Operations

— Function: ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t length)

The function gpgme_data_read reads up to length bytes from the data object with the handle dh into the space starting at buffer.

If no error occurs, the actual amount read is returned. If the end of the data object is reached, the function returns 0.

In all other cases, the function returns -1 and sets errno.

— Function: ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size)

The function gpgme_data_write writes up to size bytes starting from buffer into the data object with the handle dh at the current write position.

The function returns the number of bytes actually written, or -1 if an error occurs. If an error occurs, errno is set.

— Function: off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence)

The function gpgme_data_seek changes the current read/write position.

The whence argument specifies how the offset should be interpreted. It must be one of the following symbolic constants:

SEEK_SET
Specifies that offset is a count of characters from the beginning of the data object.
SEEK_CUR
Specifies that offset is a count of characters from the current file position. This count may be positive or negative.
SEEK_END
Specifies that offset is a count of characters from the end of the data object. A negative count specifies a position within the current extent of the data object; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the data object with zeros up to that position.

If successful, the function returns the resulting file position, measured in bytes from the beginning of the data object. You can use this feature together with SEEK_CUR to read the current read/write position.

If the function fails, -1 is returned and errno is set.

The following function is deprecated and should not be used. It will be removed in a future version of GPGME.

— Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t dh)

The function gpgme_data_rewind is equivalent to:

            return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
              ? gpgme_error_from_errno (errno) : 0;