1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
.Dd January 24, 2024
.Dt SQLITE3_BLOB_WRITE 3
.Os
.Sh NAME
.Nm sqlite3_blob_write
.Nd write data into a BLOB incrementally
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_blob_write
.Fa "sqlite3_blob *"
.Fa "const void *z"
.Fa "int n"
.Fa "int iOffset"
.Fc
.Sh DESCRIPTION
This function is used to write data into an open BLOB handle
from a caller-supplied buffer.
N bytes of data are copied from the buffer Z into the open BLOB, starting
at offset iOffset.
.Pp
On success, sqlite3_blob_write() returns SQLITE_OK.
Otherwise, an error code or an extended error code
is returned.
Unless SQLITE_MISUSE is returned, this function sets the database connection
error code and message accessible via
.Fn sqlite3_errcode
and
.Fn sqlite3_errmsg
and related functions.
.Pp
If the BLOB handle passed as the first argument was not
opened for writing (the flags parameter to
.Fn sqlite3_blob_open
was zero), this function returns SQLITE_READONLY.
.Pp
This function may only modify the contents of the BLOB; it is not possible
to increase the size of a BLOB using this API.
If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR
is returned and no data is written.
The size of the BLOB (and hence the maximum value of N+iOffset) can
be determined using the
.Fn sqlite3_blob_bytes
interface.
If N or iOffset are less than zero SQLITE_ERROR is returned
and no data is written.
.Pp
An attempt to write to an expired BLOB handle fails with
an error code of SQLITE_ABORT.
Writes to the BLOB that occurred before the BLOB handle
expired are not rolled back by the expiration of the handle, though
of course those changes might have been overwritten by the statement
that expired the BLOB handle or by other independent statements.
.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 7869.
.Bd -literal
SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_blob 3 ,
.Xr sqlite3_blob_bytes 3 ,
.Xr sqlite3_blob_close 3 ,
.Xr sqlite3_blob_open 3 ,
.Xr sqlite3_blob_read 3 ,
.Xr sqlite3_errcode 3 ,
.Xr SQLITE_OK 3
|
