1.Dd January 24, 2024 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.In sqlite3.h 14.Ft void * 15.Fo sqlite3_malloc 16.Fa "int" 17.Fc 18.Ft void * 19.Fo sqlite3_malloc64 20.Fa "sqlite3_uint64" 21.Fc 22.Ft void * 23.Fo sqlite3_realloc 24.Fa "void*" 25.Fa "int" 26.Fc 27.Ft void * 28.Fo sqlite3_realloc64 29.Fa "void*" 30.Fa "sqlite3_uint64" 31.Fc 32.Ft void 33.Fo sqlite3_free 34.Fa "void*" 35.Fc 36.Ft sqlite3_uint64 37.Fo sqlite3_msize 38.Fa "void*" 39.Fc 40.Sh DESCRIPTION 41The SQLite core uses these three routines for all of its own internal 42memory allocation needs. 43"Core" in the previous sentence does not include operating-system specific 44VFS implementation. 45The Windows VFS uses native malloc() and free() for some operations. 46.Pp 47The sqlite3_malloc() routine returns a pointer to a block of memory 48at least N bytes in length, where N is the parameter. 49If sqlite3_malloc() is unable to obtain sufficient free memory, it 50returns a NULL pointer. 51If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc() 52returns a NULL pointer. 53.Pp 54The sqlite3_malloc64(N) routine works just like sqlite3_malloc(N) except 55that N is an unsigned 64-bit integer instead of a signed 32-bit integer. 56.Pp 57Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc() 58or sqlite3_realloc() releases that memory so that it might be reused. 59The sqlite3_free() routine is a no-op if is called with a NULL pointer. 60Passing a NULL pointer to sqlite3_free() is harmless. 61After being freed, memory should neither be read nor written. 62Even reading previously freed memory might result in a segmentation 63fault or other severe error. 64Memory corruption, a segmentation fault, or other severe error might 65result if sqlite3_free() is called with a non-NULL pointer that was 66not obtained from sqlite3_malloc() or sqlite3_realloc(). 67.Pp 68The sqlite3_realloc(X,N) interface attempts to resize a prior memory 69allocation X to be at least N bytes. 70If the X parameter to sqlite3_realloc(X,N) is a NULL pointer then its 71behavior is identical to calling sqlite3_malloc(N). 72If the N parameter to sqlite3_realloc(X,N) is zero or negative then 73the behavior is exactly the same as calling sqlite3_free(X). 74sqlite3_realloc(X,N) returns a pointer to a memory allocation of at 75least N bytes in size or NULL if insufficient memory is available. 76If M is the size of the prior allocation, then min(N,M) bytes of the 77prior allocation are copied into the beginning of buffer returned by 78sqlite3_realloc(X,N) and the prior allocation is freed. 79If sqlite3_realloc(X,N) returns NULL and N is positive, then the prior 80allocation is not freed. 81.Pp 82The sqlite3_realloc64(X,N) interfaces works the same as sqlite3_realloc(X,N) 83except that N is a 64-bit unsigned integer instead of a 32-bit signed 84integer. 85.Pp 86If X is a memory allocation previously obtained from sqlite3_malloc(), 87sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then 88sqlite3_msize(X) returns the size of that memory allocation in bytes. 89The value returned by sqlite3_msize(X) might be larger than the number 90of bytes requested when X was allocated. 91If X is a NULL pointer then sqlite3_msize(X) returns zero. 92If X points to something that is not the beginning of memory allocation, 93or if it points to a formerly valid memory allocation that has now 94been freed, then the behavior of sqlite3_msize(X) is undefined and 95possibly harmful. 96.Pp 97The memory returned by sqlite3_malloc(), sqlite3_realloc(), sqlite3_malloc64(), 98and sqlite3_realloc64() is always aligned to at least an 8 byte boundary, 99or to a 4 byte boundary if the SQLITE_4_BYTE_ALIGNED_MALLOC 100compile-time option is used. 101.Pp 102The pointer arguments to 103.Fn sqlite3_free 104and 105.Fn sqlite3_realloc 106must be either NULL or else pointers obtained from a prior invocation 107of 108.Fn sqlite3_malloc 109or 110.Fn sqlite3_realloc 111that have not yet been released. 112.Pp 113The application must not read or write any part of a block of memory 114after it has been released using 115.Fn sqlite3_free 116or 117.Fn sqlite3_realloc . 118.Sh IMPLEMENTATION NOTES 119These declarations were extracted from the 120interface documentation at line 2993. 121.Bd -literal 122SQLITE_API void *sqlite3_malloc(int); 123SQLITE_API void *sqlite3_malloc64(sqlite3_uint64); 124SQLITE_API void *sqlite3_realloc(void*, int); 125SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64); 126SQLITE_API void sqlite3_free(void*); 127SQLITE_API sqlite3_uint64 sqlite3_msize(void*); 128.Ed 129