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