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.

### Invariants:

F17303 | The sqlite3_malloc(N) interface returns either a pointer to newly checked-out block of at least N bytes of memory that is 8-byte aligned, or it returns NULL if it is unable to fulfill the request.
F17304 | The sqlite3_malloc(N) interface returns a NULL pointer if N is less than or equal to zero.
F17305 | The sqlite3_free(P) interface releases memory previously returned from sqlite3_malloc() or sqlite3_realloc(), making it available for reuse.
F17306 | A call to sqlite3_free(NULL) is a harmless no-op.
F17310 | A call to sqlite3_realloc(0,N) is equivalent to a call to sqlite3_malloc(N).
F17312 | A call to sqlite3_realloc(P,0) is equivalent to a call to sqlite3_free(P).
F17315 | The SQLite core uses sqlite3_malloc(), sqlite3_realloc(), and sqlite3_free() for all of its memory allocation and deallocation needs.
F17318 | The sqlite3_realloc(P,N) interface returns either a pointer to a block of checked-out memory of at least N bytes in size that is 8-byte aligned, or a NULL pointer.
F17321 | When sqlite3_realloc(P,N) returns a non-NULL pointer, it first copies the first K bytes of content from P into the newly allocated where K is the lessor of N and the size of the buffer P.
F17322 | When sqlite3_realloc(P,N) returns a non-NULL pointer, it first releases the buffer P.
F17323 | When sqlite3_realloc(P,N) returns NULL, the buffer P is not modified or released.

### Limitations:

U17350 | The pointer arguments to sqlite3_free() and sqlite3_realloc() must be either NULL or else a pointer obtained from a prior invocation of sqlite3_malloc() or sqlite3_realloc() that has not been released.
U17351 | 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().

See also lists of Objects, Constants, and Functions.

This page last modified 2008/01/31 20:37:13 UTC