125 lines
4.7 KiB
Groff
125 lines
4.7 KiB
Groff
.Dd March 11, 2017
|
|
.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
|
|
.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
|
|
In SQLite version 3.5.0 and 3.5.1, it was possible to define the SQLITE_OMIT_MEMORY_ALLOCATION
|
|
which would cause the built-in implementation of these routines to
|
|
be omitted.
|
|
That capability is no longer provided.
|
|
Only built-in memory allocators can be used.
|
|
.Pp
|
|
Prior to SQLite version 3.7.10, the Windows OS interface layer called
|
|
the system malloc() and free() directly when converting filenames between
|
|
the UTF-8 encoding used by SQLite and whatever filename encoding is
|
|
used by the particular Windows installation.
|
|
Memory allocation errors were detected, but they were reported back
|
|
as SQLITE_CANTOPEN or SQLITE_IOERR rather
|
|
than SQLITE_NOMEM.
|
|
.Pp
|
|
The pointer arguments to sqlite3_free() and sqlite3_realloc()
|
|
must be either NULL or else pointers obtained from a prior invocation
|
|
of sqlite3_malloc() or 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 sqlite3_free() or sqlite3_realloc().
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3_malloc 3 ,
|
|
.Xr SQLITE_OK 3
|