Updated: 2021/Apr/14

SQLITE3_GET_TABLE(3)       Library Functions Manual       SQLITE3_GET_TABLE(3)

     sqlite3_get_table, sqlite3_free_table - Convenience Routines For Running

     sqlite3_get_table(sqlite3 *db, const char *zSql, char ***pazResult,
         int *pnRow, int *pnColumn, char **pzErrmsg       );

     sqlite3_free_table(char **result);

     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

     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

     Name        | Age ----------------------- Alice       | 43 Bob
     | 28 Cindy       | 21

     There are two column (M==2) and three rows (N==3).  Thus the result table
     has 8 entries.  Suppose the result table is stored in an array names
     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

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

     sqlite3_column_blob(3), sqlite3_errcode(3), sqlite3_exec(3),
     sqlite3_malloc(3), sqlite3_get_table(3), sqlite3_malloc(3)

NetBSD 9.99                    December 19, 2018                   NetBSD 9.99