Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
SQLITE3_GET_TABLE(3) Library Functions Manual SQLITE3_GET_TABLE(3) NAME sqlite3_get_table, sqlite3_free_table - convenience routines for running queries SYNOPSIS #include <sqlite3.h> int sqlite3_get_table(sqlite3 *db, const char *zSql, char ***pazResult, int *pnRow, int *pnColumn, char **pzErrmsg); void sqlite3_free_table(char **result); DESCRIPTION This is a legacy interface that is preserved for backwards compatibility. Use of this interface is not recommended. Definition: A result table is memory data structure created by the sqlite3_get_table() interface. A result table records the complete query results from one or more queries. The table conceptually has a number of rows and columns. But these numbers are not part of the result table itself. These numbers are obtained separately. Let N be the number of rows and M be the number of columns. A result table is an array of pointers to zero-terminated UTF-8 strings. There are (N+1)*M elements in the array. The first M pointers point to zero-terminated strings that contain the names of the columns. The remaining entries all point to query results. NULL values result in NULL pointers. All other values are in their UTF-8 zero-terminated string representation as returned by sqlite3_column_text(). A result table might consist of one or more memory allocations. It is not safe to pass a result table directly to sqlite3_free(). A result table should be deallocated using sqlite3_free_table(). As an example of the result table format, suppose a query result is as follows: Name | Age ----------------------- Alice | 43 Bob | 28 Cindy | 21 There are two columns (M==2) and three rows (N==3). Thus the result table has 8 entries. Suppose the result table is stored in an array named azResult. Then azResult holds this content: azResult[0] = "Name"; azResult[1] = "Age"; azResult[2] = "Alice"; azResult[3] = "43"; azResult[4] = "Bob"; azResult[5] = "28"; azResult[6] = "Cindy"; azResult[7] = "21"; The sqlite3_get_table() function evaluates one or more semicolon- separated SQL statements in the zero-terminated UTF-8 string of its 2nd parameter and returns a result table to the pointer given in its 3rd parameter. After the application has finished with the result from sqlite3_get_table(), it must pass the result table pointer to sqlite3_free_table() in order to release the memory that was malloced. Because of the way the sqlite3_malloc() happens within sqlite3_get_table(), the calling function must not try to call sqlite3_free() directly. Only sqlite3_free_table() is able to release the memory properly and safely. The sqlite3_get_table() interface is implemented as a wrapper around sqlite3_exec(). The sqlite3_get_table() routine does not have access to any internal data structures of SQLite. It uses only the public interface defined here. As a consequence, errors that occur in the wrapper layer outside of the internal sqlite3_exec() call are not reflected in subsequent calls to sqlite3_errcode() or sqlite3_errmsg(). IMPLEMENTATION NOTES These declarations were extracted from the interface documentation at line 2865. SQLITE_API int sqlite3_get_table( sqlite3 *db, /* An open database */ const char *zSql, /* SQL to be evaluated */ char ***pazResult, /* Results of the query */ int *pnRow, /* Number of result rows written here */ int *pnColumn, /* Number of result columns written here */ char **pzErrmsg /* Error msg written here */ ); SQLITE_API void sqlite3_free_table(char **result); SEE ALSO sqlite3_column_blob(3), sqlite3_errcode(3), sqlite3_exec(3), sqlite3_malloc(3) NetBSD 10.99 August 24, 2023 NetBSD 10.99