NAME

       odbx_lo_read - Reads content from a large object

SYNOPSIS

       #include <opendbx/api.h>

       ssize_t odbx_lo_read (odbx_lo_t* lo, void* buffer, size_t buflen);

DESCRIPTION

       To  get  the  content  of  a large object, odbx_lo_read() fetches the data in one or more pieces from the
       server and stores it into the user supplied buffer. After opening the large object using  odbx_lo_open(),
       the first call to odbx_lo_read() will return the bytes from the beginning. The second and all other calls
       will store subsequent parts of the large object content into the buffer until the  end  of  the  data  is
       reached.  To  reread  the  content a second time, you have to close the large object handle and reopen it
       again as some databases provide no way to reposition the internal file position indicator for the stream.

       The lo parameter has to be the large object handle created and returned by odbx_lo_open() via its  second
       parameter.  It  becomes invalid after it was supplied to odbx_lo_close() and this function will return an
       error in this case. The large object content fetched from the server is stored  into  the  user  supplied
       buffer up to buflen bytes.

RETURN VALUE

       odbx_lo_read()  returns  the  number of bytes placed into buffer, which may be up to buflen bytes. If the
       end of the content is reached and no more data is available, the return value will be 0. On error, a code
       whose  value  is  less than zero is returned if one of the operations couldn't be completed successfully.
       Possible error codes are listed  in  the  error  section  and  they  can  be  feed  to  odbx_error()  and
       odbx_error_type() to get further details.

ERRORS

       -ODBX_ERR_BACKEND
              The native database library couldn't read from the large object

       -ODBX_ERR_HANDLE
              lo is NULL or the supplied large object handle is invalid

SEE ALSO

       odbx_lo_open(), odbx_lo_close()

                                                  3 April 2024                                   odbx_lo_read(3)