.Dd January 24, 2024
.Dt SQLITE3_BLOB_READ 3
.Os
.Sh NAME
.Nm sqlite3_blob_read
.Nd read data from a BLOB incrementally
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_blob_read
.Fa "sqlite3_blob *"
.Fa "void *Z"
.Fa "int N"
.Fa "int iOffset"
.Fc
.Sh DESCRIPTION
This function is used to read data from an open BLOB handle
into a caller-supplied buffer.
N bytes of data are copied into buffer Z from the open BLOB, starting
at offset iOffset.
.Pp
If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR
is returned and no data is read.
If N or iOffset is less than zero, SQLITE_ERROR is returned
and no data is read.
The size of the blob (and hence the maximum value of N+iOffset) can
be determined using the
.Fn sqlite3_blob_bytes
interface.
.Pp
An attempt to read from an expired BLOB handle fails with
an error code of SQLITE_ABORT.
.Pp
On success, sqlite3_blob_read() returns SQLITE_OK.
Otherwise, an error code or an extended error code
is returned.
.Pp
This routine only works on a BLOB handle which has been
created by a prior successful call to
.Fn sqlite3_blob_open
and which has not been closed by
.Fn sqlite3_blob_close .
Passing any other pointer in to this routine results in undefined and
probably undesirable behavior.
.Pp
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 7840.
.Bd -literal
SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
.Ed
.Sh SEE ALSO
.Xr sqlite3_blob 3 ,
.Xr sqlite3_blob_bytes 3 ,
.Xr sqlite3_blob_close 3 ,
.Xr sqlite3_blob_open 3 ,
.Xr sqlite3_blob_write 3 ,
.Xr SQLITE_OK 3