.Dd January 24, 2024
.Dt SQLITE3_SERIALIZE 3
.Os
.Sh NAME
.Nm sqlite3_serialize
.Nd serialize a database
.Sh SYNOPSIS
.In sqlite3.h
.Ft unsigned char *
.Fo sqlite3_serialize
.Fa "sqlite3 *db"
.Fa "const char *zSchema"
.Fa "sqlite3_int64 *piSize"
.Fa "unsigned int mFlags"
.Fc
.Sh DESCRIPTION
The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
that is a serialization of the S database on database connection
D.
If P is not a NULL pointer, then the size of the database in bytes
is written into *P.
.Pp
For an ordinary on-disk database file, the serialization is just a
copy of the disk file.
For an in-memory database or a "TEMP" database, the serialization is
the same sequence of bytes which would be written to disk if that database
where backed up to disk.
.Pp
The usual case is that sqlite3_serialize() copies the serialization
of the database into memory obtained from
.Fn sqlite3_malloc64
and returns a pointer to that memory.
The caller is responsible for freeing the returned value to avoid a
memory leak.
However, if the F argument contains the SQLITE_SERIALIZE_NOCOPY bit,
then no memory allocations are made, and the sqlite3_serialize() function
will return a pointer to the contiguous memory representation of the
database that SQLite is currently using for that database, or NULL
if the no such contiguous memory representation of the database exists.
A contiguous memory representation of the database will usually only
exist if there has been a prior call to sqlite3_deserialize(D,S,...)
with the same values of D and S.
The size of the database is written into *P even if the SQLITE_SERIALIZE_NOCOPY
bit is set but no contiguous copy of the database exists.
.Pp
After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set, the
returned buffer content will remain accessible and unchanged until
either the next write operation on the connection or when the connection
is closed, and applications must not modify the buffer.
If the bit had been clear, the returned buffer will not be accessed
by SQLite after the call.
.Pp
A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
allocation error occurs.
.Pp
This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE
option.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 10636.
.Bd -literal
SQLITE_API unsigned char *sqlite3_serialize(
  sqlite3 *db,           /* The database connection */
  const char *zSchema,   /* Which DB to serialize. ex: "main", "temp", ... */
  sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
  unsigned int mFlags    /* Zero or more SQLITE_SERIALIZE_* flags */
);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_malloc 3