.Dd January 24, 2024
.Dt SQLITE3_MALLOC 3
.Os
.Sh NAME
.Nm sqlite3_malloc ,
.Nm sqlite3_malloc64 ,
.Nm sqlite3_realloc ,
.Nm sqlite3_realloc64 ,
.Nm sqlite3_free ,
.Nm sqlite3_msize
.Nd memory allocation subsystem
.Sh SYNOPSIS
.In sqlite3.h
.Ft void *
.Fo sqlite3_malloc
.Fa "int"
.Fc
.Ft void *
.Fo sqlite3_malloc64
.Fa "sqlite3_uint64"
.Fc
.Ft void *
.Fo sqlite3_realloc
.Fa "void*"
.Fa "int"
.Fc
.Ft void *
.Fo sqlite3_realloc64
.Fa "void*"
.Fa "sqlite3_uint64"
.Fc
.Ft void
.Fo sqlite3_free
.Fa "void*"
.Fc
.Ft sqlite3_uint64
.Fo sqlite3_msize
.Fa "void*"
.Fc
.Sh DESCRIPTION
The SQLite core uses these three routines for all of its own internal
memory allocation needs.
"Core" in the previous sentence does not include operating-system specific
VFS implementation.
The Windows VFS uses native malloc() and free() for some operations.
.Pp
The sqlite3_malloc() routine returns a pointer to a block of memory
at least N bytes in length, where N is the parameter.
If sqlite3_malloc() is unable to obtain sufficient free memory, it
returns a NULL pointer.
If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc()
returns a NULL pointer.
.Pp
The sqlite3_malloc64(N) routine works just like sqlite3_malloc(N) except
that N is an unsigned 64-bit integer instead of a signed 32-bit integer.
.Pp
Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc()
or sqlite3_realloc() releases that memory so that it might be reused.
The sqlite3_free() routine is a no-op if is called with a NULL pointer.
Passing a NULL pointer to sqlite3_free() is harmless.
After being freed, memory should neither be read nor written.
Even reading previously freed memory might result in a segmentation
fault or other severe error.
Memory corruption, a segmentation fault, or other severe error might
result if sqlite3_free() is called with a non-NULL pointer that was
not obtained from sqlite3_malloc() or sqlite3_realloc().
.Pp
The sqlite3_realloc(X,N) interface attempts to resize a prior memory
allocation X to be at least N bytes.
If the X parameter to sqlite3_realloc(X,N) is a NULL pointer then its
behavior is identical to calling sqlite3_malloc(N).
If the N parameter to sqlite3_realloc(X,N) is zero or negative then
the behavior is exactly the same as calling sqlite3_free(X).
sqlite3_realloc(X,N) returns a pointer to a memory allocation of at
least N bytes in size or NULL if insufficient memory is available.
If M is the size of the prior allocation, then min(N,M) bytes of the
prior allocation are copied into the beginning of buffer returned by
sqlite3_realloc(X,N) and the prior allocation is freed.
If sqlite3_realloc(X,N) returns NULL and N is positive, then the prior
allocation is not freed.
.Pp
The sqlite3_realloc64(X,N) interfaces works the same as sqlite3_realloc(X,N)
except that N is a 64-bit unsigned integer instead of a 32-bit signed
integer.
.Pp
If X is a memory allocation previously obtained from sqlite3_malloc(),
sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
sqlite3_msize(X) returns the size of that memory allocation in bytes.
The value returned by sqlite3_msize(X) might be larger than the number
of bytes requested when X was allocated.
If X is a NULL pointer then sqlite3_msize(X) returns zero.
If X points to something that is not the beginning of memory allocation,
or if it points to a formerly valid memory allocation that has now
been freed, then the behavior of sqlite3_msize(X) is undefined and
possibly harmful.
.Pp
The memory returned by sqlite3_malloc(), sqlite3_realloc(), sqlite3_malloc64(),
and sqlite3_realloc64() is always aligned to at least an 8 byte boundary,
or to a 4 byte boundary if the SQLITE_4_BYTE_ALIGNED_MALLOC
compile-time option is used.
.Pp
The pointer arguments to
.Fn sqlite3_free
and
.Fn sqlite3_realloc
must be either NULL or else pointers obtained from a prior invocation
of
.Fn sqlite3_malloc
or
.Fn sqlite3_realloc
that have not yet been released.
.Pp
The application must not read or write any part of a block of memory
after it has been released using
.Fn sqlite3_free
or
.Fn sqlite3_realloc .
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 2993.
.Bd -literal
SQLITE_API void *sqlite3_malloc(int);
SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
SQLITE_API void *sqlite3_realloc(void*, int);
SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
SQLITE_API void sqlite3_free(void*);
SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
.Ed