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