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