diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_aggregate_context.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_aggregate_context.3 | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_aggregate_context.3 b/static/netbsd/man3/sqlite3_aggregate_context.3 new file mode 100644 index 00000000..436ed5f0 --- /dev/null +++ b/static/netbsd/man3/sqlite3_aggregate_context.3 @@ -0,0 +1,61 @@ +.Dd January 24, 2024 +.Dt SQLITE3_AGGREGATE_CONTEXT 3 +.Os +.Sh NAME +.Nm sqlite3_aggregate_context +.Nd obtain aggregate function context +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_aggregate_context +.Fa "sqlite3_context*" +.Fa "int nBytes" +.Fc +.Sh DESCRIPTION +Implementations of aggregate SQL functions use this routine to allocate +memory for storing their state. +.Pp +The first time the sqlite3_aggregate_context(C,N) routine is called +for a particular aggregate function, SQLite allocates N bytes of memory, +zeroes out that memory, and returns a pointer to the new memory. +On second and subsequent calls to sqlite3_aggregate_context() for the +same aggregate function instance, the same buffer is returned. +Sqlite3_aggregate_context() is normally called once for each invocation +of the xStep callback and then one last time when the xFinal callback +is invoked. +When no rows match an aggregate query, the xStep() callback of the +aggregate function implementation is never called and xFinal() is called +exactly once. +In those cases, sqlite3_aggregate_context() might be called for the +first time from within xFinal(). +.Pp +The sqlite3_aggregate_context(C,N) routine returns a NULL pointer when +first called if N is less than or equal to zero or if a memory allocation +error occurs. +.Pp +The amount of space allocated by sqlite3_aggregate_context(C,N) is +determined by the N parameter on first successful call. +Changing the value of N in any subsequent call to sqlite3_aggregate_context() +within the same aggregate function instance will not resize the memory +allocation. +Within the xFinal callback, it is customary to set N=0 in calls to +sqlite3_aggregate_context(C,N) so that no pointless memory allocations +occur. +.Pp +SQLite automatically frees the memory allocated by sqlite3_aggregate_context() +when the aggregate query concludes. +.Pp +The first parameter must be a copy of the SQL function context +that is the first parameter to the xStep or xFinal callback routine +that implements the aggregate function. +.Pp +This routine must be called from the same thread in which the aggregate +SQL function is running. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5831. +.Bd -literal +SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); +.Ed +.Sh SEE ALSO +.Xr sqlite3_context 3 |