sqlite.h


Subsistema de asignación de memoria

void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
void sqlite3_free(void*);

El núclero de SQLite usa estas tres funciones para todas sus necesidades de asignación interna de memoria. "Núcleo" en la frase anterior no incluye la implementación del VFS específico del sistema operativo. El VFS de Windows usa las funciones nativas malloc() y free() para algunas operaciones.

La función sqlite3_malloc() retorna un puntero a un bloque de memoria de al menos N bytes de longitud, donde N es el parámetro. Si sqlite3_malloc() es incapaz de obtener suficiente memoria libre, retorna un puntero NULL. Si el parámetro N para sqlite3_malloc() es cero o negativo, sqlite3_malloc() retorna un puntero NULL.

Llamando a sqlite3_free() con un puntero previamente obtenido por sqlite3_malloc() o sqlite3_realloc() libera esa memoria de modo que pueda ser reutilizada. La función sqlite3_free() no hace nada cuando es invocada con un puntero NULL. Pasar un puntero NULL a sqlite3_free() es inofensivo. Después de haber sido liberada, la memoria no debe ser nunca leída o escrita. Incluso la lectura de una memoria previamente liberada puede provocar un fallo de segmentación u otro error grave. Si sqlite3_free() es invocada con un puntero no nulo que no fue obtenido de sqlite3_malloc() o sqlite3_realloc(), se puede producir corrupción de memoria, fallos de segmentación u otro error grave.

La función sqlite3_realloc() intenta redimensionar una asignación de memoria previa para que contenga al menos N bytes, donde N es el segundo parámetro. La memoria a redimensionar es el primer parámetro. Si el primer parámetro para sqlite3_realloc() es un puntero NULL su comportamiento es idéntico que una llamada a sqlite3_malloc(N) donde N es el segundo parámetro de sqlite3_realloc(). Si el segundo parámetro para sqlite3_realloc() es cero o negativo, el comportamiento es exactamente el mismo que llamar a sqlite3_free(P) donde P es el primer parámetro a sqlite3_realloc(). sqlite3_realloc() retorna un puntero a un bloque de memoria de al menos N bytes de tamaño o NULL si no hay suficiente memoria disponible. Si M es el tamaño de la asignación anterior, entonce min(N,M) bytes de la asignación anterior se copian al comienzo del buffer retornado por sqlite3_realloc() y la asignación anterior se libera. Si sqlite3_realloc() retorna NULL, la asignación anterior no se libera.

La memoria devuelta por sqlite3_malloc() y sqlite3_realloc() siempre está alineada en al menos de 8 bytes de espacio, o a 4 bytes si se usó la opción de compilación SQLITE_4_BYTE_ALIGNED_MALLOC.

Si la versiones 3.5.0 y 3.5.1 de SQLite, era posible definir SQLITE_OMIT_MEMORY_ALLOCATION de modo que la implementación incorporada de estas funciones fuera omitida. Esta capacidad ya no está disponible. Sólo se pueden usar asignaciones de memoria internas.

La capa de interfaz del sistema operativo Windows llama a funciones del sistema malloc() y free() directamente cuando convierte nombres de fichero entre codificaciones UTF-8 usadas por SQLite y cualquier codificación de nombre de fichero usado por la instalación particular de Windows. Los errores de asignación de memoria son detectados, pero son reportados como SQLITE_CANTOPEN o SQLITE_IOERR en lugar de SQLITE_NOMEM.

Los punteros usados como argumentos para sqlite3_free() y sqlite3_realloc() deben ser NULL o punteros obtenidos de una llamada previa a sqlite3_malloc() o sqlite3_realloc() que no hayan sido liberados ya.

La aplicación no debe leer o escribir ninguna parte de un bloque de memoria después de que haya sido liberado usando sqlite3_free() o sqlite3_realloc().