.Dd January 24, 2024
.Dt SQLITE3_GET_TABLE 3
.Os
.Sh NAME
.Nm sqlite3_get_table ,
.Nm sqlite3_free_table
.Nd convenience routines for running queries
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_get_table
.Fa "sqlite3 *db"
.Fa "const char *zSql"
.Fa "char ***pazResult"
.Fa "int *pnRow"
.Fa "int *pnColumn"
.Fa "char **pzErrmsg"
.Fc
.Ft void
.Fo sqlite3_free_table
.Fa "char **result"
.Fc
.Sh DESCRIPTION
This is a legacy interface that is preserved for backwards compatibility.
Use of this interface is not recommended.
.Pp
Definition: A \fBresult table\fP is memory data structure created by the
.Fn sqlite3_get_table
interface.
A result table records the complete query results from one or more
queries.
.Pp
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.
.Pp
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
.Fn 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
.Fn sqlite3_free .
A result table should be deallocated using
.Fn sqlite3_free_table .
As an example of the result table format, suppose a query result is
as follows:
.Bd -ragged
.Bd -literal
Name        | Age ----------------------- Alice       | 43 Bob    
| 28 Cindy       | 21
.Ed
.Pp
.Ed
.Pp
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:
.Bd -ragged
.Bd -literal
azResult[0] = "Name"; azResult[1] = "Age"; azResult[2] = "Alice"; azResult[3]
= "43"; azResult[4] = "Bob"; azResult[5] = "28"; azResult[6] = "Cindy";
azResult[7] = "21";
.Ed
.Pp
.Ed
.Pp
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.
.Pp
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
.Fn sqlite3_malloc
happens within sqlite3_get_table(), the calling function must not try
to call
.Fn sqlite3_free
directly.
Only
.Fn sqlite3_free_table
is able to release the memory properly and safely.
.Pp
The sqlite3_get_table() interface is implemented as a wrapper around
.Fn 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
.Fn sqlite3_exec
call are not reflected in subsequent calls to
.Fn sqlite3_errcode
or
.Fn sqlite3_errmsg .
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 2865.
.Bd -literal
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);
.Ed
.Sh SEE ALSO
.Xr sqlite3_column_blob 3 ,
.Xr sqlite3_errcode 3 ,
.Xr sqlite3_exec 3 ,
.Xr sqlite3_malloc 3