100 lines
3.3 KiB
Groff
100 lines
3.3 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_GET_TABLE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_get_table ,
|
|
.Nm sqlite3_free_table
|
|
.Nd Convenience Routines For Running Queries
|
|
.Sh SYNOPSIS
|
|
.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
|
|
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 sqlite3_column_text().
|
|
.Pp
|
|
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().
|
|
.Pp
|
|
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 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:
|
|
.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 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.
|
|
.Pp
|
|
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().
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3_column_blob 3 ,
|
|
.Xr sqlite3_errcode 3 ,
|
|
.Xr sqlite3_exec 3 ,
|
|
.Xr sqlite3_malloc 3 ,
|
|
.Xr sqlite3_get_table 3 ,
|
|
.Xr sqlite3_malloc 3
|