.Dd August 24, 2023
.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
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 10524.
.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