Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

SQLITE3_MALLOC(3)          Library Functions Manual          SQLITE3_MALLOC(3)

NAME
     sqlite3_malloc, sqlite3_malloc64, sqlite3_realloc, sqlite3_realloc64,
     sqlite3_free, sqlite3_msize - Memory Allocation Subsystem

SYNOPSIS
     void *
     sqlite3_malloc(int);

     void *
     sqlite3_malloc64(sqlite3_uint64);

     void *
     sqlite3_realloc(void*, int);

     void *
     sqlite3_realloc64(void*, sqlite3_uint64);

     void
     sqlite3_free(void*);

     sqlite3_uint64
     sqlite3_msize(void*);

DESCRIPTION
     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.

     The sqlite3_malloc64(N) routine works just like sqlite3_malloc(N) except
     that N is an unsigned 64-bit integer instead of a signed 32-bit integer.

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

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

     The sqlite3_realloc64(X,N) interfaces works the same as
     sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
     of a 32-bit signed integer.

     If X is a memory allocation previously obtained from sqlite3_malloc(),
     sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
     sqlite3_msize(X) returns the size of that memory allocation in bytes.
     The value returned by sqlite3_msize(X) might be larger than the number of
     bytes requested when X was allocated.  If X is a NULL pointer then
     sqlite3_msize(X) returns zero.  If X points to something that is not the
     beginning of memory allocation, or if it points to a formerly valid
     memory allocation that has now been freed, then the behavior of
     sqlite3_msize(X) is undefined and possibly harmful.

     The memory returned by sqlite3_malloc(), sqlite3_realloc(),
     sqlite3_malloc64(), and sqlite3_realloc64() is always aligned to at least
     an 8 byte boundary, or to a 4 byte boundary if the
     SQLITE_4_BYTE_ALIGNED_MALLOC compile-time option is used.

     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.

     Prior to SQLite version 3.7.10, the Windows OS interface layer called 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 were
     detected, but they were reported back as SQLITE_CANTOPEN or SQLITE_IOERR
     rather than SQLITE_NOMEM.

     The pointer arguments to sqlite3_free() and sqlite3_realloc() must be
     either NULL or else pointers obtained from a prior invocation of
     sqlite3_malloc() or sqlite3_realloc() that have not yet been released.

     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
     sqlite3_malloc(3), SQLITE_OK(3)

NetBSD 9.99                    December 19, 2018                   NetBSD 9.99