Memory Allocation Subsystem

内存分配子系统

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*

SQLite 内核使用这三个例程来满足其自己的内部内存分配需求。前一句中的“核心”不包括特定于操作系统的 VFS 实现。Windows VFS 对某些操作使用原生 malloc（）和 free（）。

sqlite3_malloc（）例程返回一个指向至少有 N 个字节长度的内存块的指针，其中 N 是参数。如果 sqlite3_malloc（）无法获得足够的空闲内存，它将返回一个 NULL 指针。如果参数 N 到 sqlite3_malloc（）为零或负数，则 sqlite3_malloc（）返回一个 NULL 指针。

sqlite3_malloc64（N）例程的工作方式与 sqlite3_malloc（N）类似，但 N 是一个无符号的64位整数，而不是有符号的32位整数。

用以前由 sqlite3_malloc（）或 sqlite3_realloc（）返回的指针调用 sqlite3_free（）会释放该内存，以便可以重用它。如果用 NULL 指针调用 sqlite3_free（）例程是一个无操作。将 NULL 指针传递给 sqlite3_free（）是无害的。释放后，内存不应该被读取或写入。即使读取以前释放的内存也可能导致分段错误或其他严重错误。如果 sqlite3_free（）使用不是从 sqlite3_malloc（）或 sqlite3_realloc（）获取的非 NULL 指针调用，则可能导致内存损坏，分段错误或其他严重错误。

sqlite3_realloc（X，N）接口尝试将先前的内存分配 X 调整为至少 N 个字节。如果 sqlite3_realloc（X，N）的 X 参数是一个 NULL 指针，那么它的行为与调用 sqlite3_malloc（N）相同。如果 sqlite3_realloc（X，N）的 N 参数为零或负值，那么该行为与调用 sqlite3_free（X）完全相同。sqlite3_realloc（X，N）返回一个指向至少 N 个字节大小的内存分配的指针，如果内存不足，则返回 NULL。如果 M 是先前分配的大小，则先前分配的 min（N，M）个字节被复制到由 sqlite3_realloc（X，N）返回的缓冲区的开始处，并且先前的分配被释放。如果 sqlite3_realloc（X，N）返回 NULL 并且 N 是正数，那么先前的分配不会被释放。

sqlite3_realloc64（X，N）接口的工作方式与 sqlite3_realloc（X，N）相同，但 N 是64位无符号整数而不是32位有符号整数。

如果 X 是以前从 sqlite3_malloc（），sqlite3_malloc64（），sqlite3_realloc（）或 sqlite3_realloc64（）获得的内存分配，那么 sqlite3_msize（X）返回内存分配的大小（以字节为单位）。sqlite3_msize（X）返回的值可能大于分配 X 时请求的字节数。如果 X 是一个 NULL 指针，则 sqlite3_msize（X）将返回零。如果 X 指向的内容不是内存分配的开始，或者指向之前已释放的有效内存分配，则 sqlite3_msize（X）的行为是未定义的，可能有害。

sqlite3_malloc（），sqlite3_realloc（），sqlite3_malloc64（）和 sqlite3_realloc64（）返回的内存始终与至少8字节边界对齐，如果使用 SQLITE_4_BYTE_ALIGNED_MALLOC 编译时选项，则返回4字节边界。

在 SQLite 版本3.5.0和3.5.1中，可以定义 SQLITE_OMIT_MEMORY_ALLOCATION，这会导致这些例程的内置实现被省略。这种能力不再提供。只能使用内置的内存分配器。

在 SQLite 版本3.7.10之前，Windows 操作系统接口层在 SQLite 使用的 UTF-8 编码和特定 Windows 安装使用的任何文件名编码之间转换文件名时直接调用系统 malloc（）和 free（）。检测到内存分配错误，但将它们报告为 SQLITE_CANTOPEN 或 SQLITE_IOERR，而不是 SQLITE_NOMEM。

sqlite3_free（）和 sqlite3_realloc（）的指针参数必须为 NULL，否则指针从先前调用尚未发布的 sqlite3_malloc（）或 sqlite3_realloc（）中获取。

应用程序在使用 sqlite3_free（）或 sqlite3_realloc（）释放后，不得读取或写入任何内存块部分。