1.Dd January 24, 2024 2.Dt SQLITE3_GET_TABLE 3 3.Os 4.Sh NAME 5.Nm sqlite3_get_table , 6.Nm sqlite3_free_table 7.Nd convenience routines for running queries 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft int 11.Fo sqlite3_get_table 12.Fa "sqlite3 *db" 13.Fa "const char *zSql" 14.Fa "char ***pazResult" 15.Fa "int *pnRow" 16.Fa "int *pnColumn" 17.Fa "char **pzErrmsg" 18.Fc 19.Ft void 20.Fo sqlite3_free_table 21.Fa "char **result" 22.Fc 23.Sh DESCRIPTION 24This is a legacy interface that is preserved for backwards compatibility. 25Use of this interface is not recommended. 26.Pp 27Definition: A \fBresult table\fP is memory data structure created by the 28.Fn sqlite3_get_table 29interface. 30A result table records the complete query results from one or more 31queries. 32.Pp 33The table conceptually has a number of rows and columns. 34But these numbers are not part of the result table itself. 35These numbers are obtained separately. 36Let N be the number of rows and M be the number of columns. 37.Pp 38A result table is an array of pointers to zero-terminated UTF-8 strings. 39There are (N+1)*M elements in the array. 40The first M pointers point to zero-terminated strings that contain 41the names of the columns. 42The remaining entries all point to query results. 43NULL values result in NULL pointers. 44All other values are in their UTF-8 zero-terminated string representation 45as returned by 46.Fn sqlite3_column_text . 47A result table might consist of one or more memory allocations. 48It is not safe to pass a result table directly to 49.Fn sqlite3_free . 50A result table should be deallocated using 51.Fn sqlite3_free_table . 52As an example of the result table format, suppose a query result is 53as follows: 54.Bd -ragged 55.Bd -literal 56Name | Age ----------------------- Alice | 43 Bob 57| 28 Cindy | 21 58.Ed 59.Pp 60.Ed 61.Pp 62There are two columns (M==2) and three rows (N==3). 63Thus the result table has 8 entries. 64Suppose the result table is stored in an array named azResult. 65Then azResult holds this content: 66.Bd -ragged 67.Bd -literal 68azResult[0] = "Name"; azResult[1] = "Age"; azResult[2] = "Alice"; azResult[3] 69= "43"; azResult[4] = "Bob"; azResult[5] = "28"; azResult[6] = "Cindy"; 70azResult[7] = "21"; 71.Ed 72.Pp 73.Ed 74.Pp 75The sqlite3_get_table() function evaluates one or more semicolon-separated 76SQL statements in the zero-terminated UTF-8 string of its 2nd parameter 77and returns a result table to the pointer given in its 3rd parameter. 78.Pp 79After the application has finished with the result from sqlite3_get_table(), 80it must pass the result table pointer to sqlite3_free_table() in order 81to release the memory that was malloced. 82Because of the way the 83.Fn sqlite3_malloc 84happens within sqlite3_get_table(), the calling function must not try 85to call 86.Fn sqlite3_free 87directly. 88Only 89.Fn sqlite3_free_table 90is able to release the memory properly and safely. 91.Pp 92The sqlite3_get_table() interface is implemented as a wrapper around 93.Fn sqlite3_exec . 94The sqlite3_get_table() routine does not have access to any internal 95data structures of SQLite. 96It uses only the public interface defined here. 97As a consequence, errors that occur in the wrapper layer outside of 98the internal 99.Fn sqlite3_exec 100call are not reflected in subsequent calls to 101.Fn sqlite3_errcode 102or 103.Fn sqlite3_errmsg . 104.Sh IMPLEMENTATION NOTES 105These declarations were extracted from the 106interface documentation at line 2865. 107.Bd -literal 108SQLITE_API int sqlite3_get_table( 109 sqlite3 *db, /* An open database */ 110 const char *zSql, /* SQL to be evaluated */ 111 char ***pazResult, /* Results of the query */ 112 int *pnRow, /* Number of result rows written here */ 113 int *pnColumn, /* Number of result columns written here */ 114 char **pzErrmsg /* Error msg written here */ 115); 116SQLITE_API void sqlite3_free_table(char **result); 117.Ed 118.Sh SEE ALSO 119.Xr sqlite3_column_blob 3 , 120.Xr sqlite3_errcode 3 , 121.Xr sqlite3_exec 3 , 122.Xr sqlite3_malloc 3 123