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()

                                         17 October 2021                          odbx_lo_read(3)