1.Dd December 19, 2018 2.Dt SQLITE3_SERIALIZE 3 3.Os 4.Sh NAME 5.Nm sqlite3_serialize 6.Nd Serialize a database 7.Sh SYNOPSIS 8.Ft unsigned char * 9.Fo sqlite3_serialize 10.Fa "sqlite3 *db" 11.Fa "const char *zSchema" 12.Fa "sqlite3_int64 *piSize" 13.Fa "unsigned int mFlags " 14.Fc 15.Sh DESCRIPTION 16The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory 17that is a serialization of the S database on database connection 18D. 19If P is not a NULL pointer, then the size of the database in bytes 20is written into *P. 21.Pp 22For an ordinary on-disk database file, the serialization is just a 23copy of the disk file. 24For an in-memory database or a "TEMP" database, the serialization is 25the same sequence of bytes which would be written to disk if that database 26where backed up to disk. 27.Pp 28The usual case is that sqlite3_serialize() copies the serialization 29of the database into memory obtained from sqlite3_malloc64() 30and returns a pointer to that memory. 31The caller is responsible for freeing the returned value to avoid a 32memory leak. 33However, if the F argument contains the SQLITE_SERIALIZE_NOCOPY bit, 34then no memory allocations are made, and the sqlite3_serialize() function 35will return a pointer to the contiguous memory representation of the 36database that SQLite is currently using for that database, or NULL 37if the no such contiguous memory representation of the database exists. 38A contiguous memory representation of the database will usually only 39exist if there has been a prior call to sqlite3_deserialize(D,S,...) 40with the same values of D and S. 41The size of the database is written into *P even if the SQLITE_SERIALIZE_NOCOPY 42bit is set but no contiguous copy of the database exists. 43.Pp 44A call to sqlite3_serialize(D,S,P,F) might return NULL even if the 45SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory 46allocation error occurs. 47.Pp 48This interface is only available if SQLite is compiled with the SQLITE_ENABLE_DESERIALIZE 49option. 50.Sh SEE ALSO 51.Xr sqlite3 3 , 52.Xr sqlite3_malloc 3 53