1.Dd $Mdocdate$ 2.Dt SQLITE3_MALLOC 3 3.Os 4.Sh NAME 5.Nm sqlite3_malloc , 6.Nm sqlite3_realloc , 7.Nm sqlite3_free 8.Nd Memory Allocation Subsystem 9.Sh SYNOPSIS 10.Ft void * 11.Fo sqlite3_malloc 12.Fa "int" 13.Fc 14.Ft void * 15.Fo sqlite3_realloc 16.Fa "void*" 17.Fa "int" 18.Fc 19.Ft void 20.Fo sqlite3_free 21.Fa "void*" 22.Fc 23.Sh DESCRIPTION 24The SQLite core uses these three routines for all of its own internal 25memory allocation needs. 26"Core" in the previous sentence does not include operating-system specific 27VFS implementation. 28The Windows VFS uses native malloc() and free() for some operations. 29.Pp 30The sqlite3_malloc() routine returns a pointer to a block of memory 31at least N bytes in length, where N is the parameter. 32If sqlite3_malloc() is unable to obtain sufficient free memory, it 33returns a NULL pointer. 34If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc() 35returns a NULL pointer. 36.Pp 37Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc() 38or sqlite3_realloc() releases that memory so that it might be reused. 39The sqlite3_free() routine is a no-op if is called with a NULL pointer. 40Passing a NULL pointer to sqlite3_free() is harmless. 41After being freed, memory should neither be read nor written. 42Even reading previously freed memory might result in a segmentation 43fault or other severe error. 44Memory corruption, a segmentation fault, or other severe error might 45result if sqlite3_free() is called with a non-NULL pointer that was 46not obtained from sqlite3_malloc() or sqlite3_realloc(). 47.Pp 48The sqlite3_realloc() interface attempts to resize a prior memory allocation 49to be at least N bytes, where N is the second parameter. 50The memory allocation to be resized is the first parameter. 51If the first parameter to sqlite3_realloc() is a NULL pointer then 52its behavior is identical to calling sqlite3_malloc(N) where N is the 53second parameter to sqlite3_realloc(). 54If the second parameter to sqlite3_realloc() is zero or negative then 55the behavior is exactly the same as calling sqlite3_free(P) where P 56is the first parameter to sqlite3_realloc(). 57sqlite3_realloc() returns a pointer to a memory allocation of at least 58N bytes in size or NULL if sufficient memory is unavailable. 59If M is the size of the prior allocation, then min(N,M) bytes of the 60prior allocation are copied into the beginning of buffer returned by 61sqlite3_realloc() and the prior allocation is freed. 62If sqlite3_realloc() returns NULL, then the prior allocation is not 63freed. 64.Pp 65The memory returned by sqlite3_malloc() and sqlite3_realloc() is always 66aligned to at least an 8 byte boundary, or to a 4 byte boundary if 67the SQLITE_4_BYTE_ALIGNED_MALLOC compile-time 68option is used. 69.Pp 70In SQLite version 3.5.0 and 3.5.1, it was possible to define the SQLITE_OMIT_MEMORY_ALLOCATION 71which would cause the built-in implementation of these routines to 72be omitted. 73That capability is no longer provided. 74Only built-in memory allocators can be used. 75.Pp 76Prior to SQLite version 3.7.10, the Windows OS interface layer called 77the system malloc() and free() directly when converting filenames between 78the UTF-8 encoding used by SQLite and whatever filename encoding is 79used by the particular Windows installation. 80Memory allocation errors were detected, but they were reported back 81as SQLITE_CANTOPEN or SQLITE_IOERR rather 82than SQLITE_NOMEM. 83.Pp 84The pointer arguments to sqlite3_free() and sqlite3_realloc() 85must be either NULL or else pointers obtained from a prior invocation 86of sqlite3_malloc() or sqlite3_realloc() 87that have not yet been released. 88.Pp 89The application must not read or write any part of a block of memory 90after it has been released using sqlite3_free() or sqlite3_realloc(). 91.Sh SEE ALSO 92.Xr sqlite3_malloc 3 , 93.Xr SQLITE_OK 3 94