Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

### Memory Allocation Subsystem

>     void *sqlite3_malloc(int);
>     void *sqlite3_realloc(void*, int);
>     void sqlite3_free(void*);

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.

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.

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_free().

The sqlite3_realloc() interface attempts to resize a prior memory allocation to be at least N bytes, where N is the second parameter. The memory allocation to be resized is the first parameter. If the first parameter to sqlite3_realloc() is a NULL pointer then its behavior is identical to calling sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). If the second parameter to sqlite3_realloc() is zero or negative then the behavior is exactly the same as calling sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). Sqlite3_realloc() returns a pointer to a memory allocation of at least N bytes in size or NULL if sufficient memory is unavailable. 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() and the prior allocation is freed. If sqlite3_realloc() returns NULL, then the prior allocation is not freed.

The memory returned by sqlite3_malloc() and sqlite3_realloc() is always aligned to at least an 8 byte boundary.

The default implementation of the memory allocation subsystem uses the malloc(), realloc() and free() provided by the standard C library. However, if SQLite is compiled with the following C preprocessor macro

> SQLITE_MEMORY_SIZE=NNN

where NNN is an integer, then SQLite create a static array of at least NNN bytes in size and use that array for all of its dynamic memory allocation needs. Additional memory allocator options may be added in future releases.

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.

The windows OS interface layer calls 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 are detected, but they are reported back as SQLITE_CANTOPEN or SQLITE_IOERR rather than SQLITE_NOMEM.

See also lists of Objects, Constants, and Functions.

This page last modified 2007/12/14 14:37:57 UTC