1.Dd $Mdocdate$ 2.Dt SQLITE3_BLOB_OPEN 3 3.Os 4.Sh NAME 5.Nm sqlite3_blob_open 6.Nd Open A BLOB For Incremental I/O 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3_blob_open 10.Fa "sqlite3*" 11.Fa "const char *zDb" 12.Fa "const char *zTable" 13.Fa "const char *zColumn" 14.Fa "sqlite3_int64 iRow" 15.Fa "int flags" 16.Fa "sqlite3_blob **ppBlob " 17.Fc 18.Sh DESCRIPTION 19This interfaces opens a handle to the BLOB located in row iRow, 20column zColumn, table zTable in database zDb; in other words, the same 21BLOB that would be selected by: 22.Bd -literal 23SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; 24.Ed 25.Pp 26If the flags parameter is non-zero, then the BLOB is opened for read 27and write access. 28If it is zero, the BLOB is opened for read access. 29It is not possible to open a column that is part of an index or primary 30key for writing. 31If foreign key constraints are enabled, it is 32not possible to open a column that is part of a child key 33for writing. 34.Pp 35Note that the database name is not the filename that contains the database 36but rather the symbolic name of the database that appears after the 37AS keyword when the database is connected using ATTACH. 38For the main database file, the database name is "main". 39For TEMP tables, the database name is "temp". 40.Pp 41On success, SQLITE_OK is returned and the new BLOB handle 42is written to *ppBlob. 43Otherwise an error code is returned and *ppBlob is set to 44be a null pointer. 45This function sets the database connection error 46code and message accessible via sqlite3_errcode() 47and sqlite3_errmsg() and related functions. 48Note that the *ppBlob variable is always initialized in a way that 49makes it safe to invoke sqlite3_blob_close() on 50*ppBlob regardless of the success or failure of this routine. 51.Pp 52If the row that a BLOB handle points to is modified by an UPDATE, 53DELETE, or by ON CONFLICT side-effects then the BLOB 54handle is marked as "expired". 55This is true if any column of the row is changed, even a column other 56than the one the BLOB handle is open on. 57Calls to sqlite3_blob_read() and sqlite3_blob_write() 58for an expired BLOB handle fail with a return code of SQLITE_ABORT. 59Changes written into a BLOB prior to the BLOB expiring are not rolled 60back by the expiration of the BLOB. 61Such changes will eventually commit if the transaction continues to 62completion. 63.Pp 64Use the sqlite3_blob_bytes() interface to determine 65the size of the opened blob. 66The size of a blob may not be changed by this interface. 67Use the UPDATE SQL command to change the size of a blob. 68.Pp 69The sqlite3_blob_open() interface will fail for 70a WITHOUT ROWID table. 71Incremental BLOB I/O is not possible on WITHOUT ROWID 72tables. 73.Pp 74The sqlite3_bind_zeroblob() and sqlite3_result_zeroblob() 75interfaces and the built-in zeroblob SQL function can be used, 76if desired, to create an empty, zero-filled blob in which to read or 77write using this interface. 78.Pp 79To avoid a resource leak, every open BLOB handle should 80eventually be released by a call to sqlite3_blob_close(). 81.Sh SEE ALSO 82.Xr sqlite3_blob 3 , 83.Xr sqlite3 3 , 84.Xr SQLITE_OK 3 , 85.Xr sqlite3_bind_blob 3 , 86.Xr sqlite3_blob_bytes 3 , 87.Xr sqlite3_blob_close 3 , 88.Xr sqlite3_blob_open 3 , 89.Xr sqlite3_blob_read 3 , 90.Xr sqlite3_blob_write 3 , 91.Xr sqlite3_errcode 3 , 92.Xr sqlite3_result_blob 3 , 93.Xr SQLITE_OK 3 94