1.Dd January 24, 2024 2.Dt SQLITE3_SERIALIZE 3 3.Os 4.Sh NAME 5.Nm sqlite3_serialize 6.Nd serialize a database 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft unsigned char * 10.Fo sqlite3_serialize 11.Fa "sqlite3 *db" 12.Fa "const char *zSchema" 13.Fa "sqlite3_int64 *piSize" 14.Fa "unsigned int mFlags" 15.Fc 16.Sh DESCRIPTION 17The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory 18that is a serialization of the S database on database connection 19D. 20If P is not a NULL pointer, then the size of the database in bytes 21is written into *P. 22.Pp 23For an ordinary on-disk database file, the serialization is just a 24copy of the disk file. 25For an in-memory database or a "TEMP" database, the serialization is 26the same sequence of bytes which would be written to disk if that database 27where backed up to disk. 28.Pp 29The usual case is that sqlite3_serialize() copies the serialization 30of the database into memory obtained from 31.Fn sqlite3_malloc64 32and returns a pointer to that memory. 33The caller is responsible for freeing the returned value to avoid a 34memory leak. 35However, if the F argument contains the SQLITE_SERIALIZE_NOCOPY bit, 36then no memory allocations are made, and the sqlite3_serialize() function 37will return a pointer to the contiguous memory representation of the 38database that SQLite is currently using for that database, or NULL 39if the no such contiguous memory representation of the database exists. 40A contiguous memory representation of the database will usually only 41exist if there has been a prior call to sqlite3_deserialize(D,S,...) 42with the same values of D and S. 43The size of the database is written into *P even if the SQLITE_SERIALIZE_NOCOPY 44bit is set but no contiguous copy of the database exists. 45.Pp 46After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set, the 47returned buffer content will remain accessible and unchanged until 48either the next write operation on the connection or when the connection 49is closed, and applications must not modify the buffer. 50If the bit had been clear, the returned buffer will not be accessed 51by SQLite after the call. 52.Pp 53A call to sqlite3_serialize(D,S,P,F) might return NULL even if the 54SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory 55allocation error occurs. 56.Pp 57This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE 58option. 59.Sh IMPLEMENTATION NOTES 60These declarations were extracted from the 61interface documentation at line 10636. 62.Bd -literal 63SQLITE_API unsigned char *sqlite3_serialize( 64 sqlite3 *db, /* The database connection */ 65 const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */ 66 sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */ 67 unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */ 68); 69.Ed 70.Sh SEE ALSO 71.Xr sqlite3 3 , 72.Xr sqlite3_malloc 3 73