diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_get_table.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_get_table.3 | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_get_table.3 b/static/netbsd/man3/sqlite3_get_table.3 new file mode 100644 index 00000000..6e3a30f9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_get_table.3 @@ -0,0 +1,122 @@ +.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 |