diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_step.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_step.3 | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_step.3 b/static/netbsd/man3/sqlite3_step.3 new file mode 100644 index 00000000..73b2e35c --- /dev/null +++ b/static/netbsd/man3/sqlite3_step.3 @@ -0,0 +1,142 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STEP 3 +.Os +.Sh NAME +.Nm sqlite3_step +.Nd evaluate an SQL statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_step +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +After a prepared statement has been prepared using +any of +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_prepare_v3 , +.Fn sqlite3_prepare16_v2 , +or +.Fn sqlite3_prepare16_v3 +or one of the legacy interfaces +.Fn sqlite3_prepare +or +.Fn sqlite3_prepare16 , +this function must be called one or more times to evaluate the statement. +.Pp +The details of the behavior of the sqlite3_step() interface depend +on whether the statement was prepared using the newer "vX" interfaces +.Fn sqlite3_prepare_v3 , +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_prepare16_v3 , +.Fn sqlite3_prepare16_v2 +or the older legacy interfaces +.Fn sqlite3_prepare +and +.Fn sqlite3_prepare16 . +The use of the new "vX" interface is recommended for new applications +but the legacy interface will continue to be supported. +.Pp +In the legacy interface, the return value will be either SQLITE_BUSY, +SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, +or SQLITE_MISUSE. +With the "v2" interface, any of the other result codes +or extended result codes might be returned as +well. +.Pp +SQLITE_BUSY means that the database engine was unable to +acquire the database locks it needs to do its job. +If the statement is a COMMIT or occurs outside of an explicit +transaction, then you can retry the statement. +If the statement is not a COMMIT and occurs within an explicit +transaction then you should rollback the transaction before continuing. +.Pp +SQLITE_DONE means that the statement has finished executing +successfully. +sqlite3_step() should not be called again on this virtual machine without +first calling +.Fn sqlite3_reset +to reset the virtual machine back to its initial state. +.Pp +If the SQL statement being executed returns any data, then SQLITE_ROW +is returned each time a new row of data is ready for processing by +the caller. +The values may be accessed using the column access functions. +sqlite3_step() is called again to retrieve the next row of data. +.Pp +SQLITE_ERROR means that a run-time error (such as a constraint +violation) has occurred. +sqlite3_step() should not be called again on the VM. +More information may be found by calling +.Fn sqlite3_errmsg . +With the legacy interface, a more specific error code (for example, +SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, +and so forth) can be obtained by calling +.Fn sqlite3_reset +on the prepared statement. +In the "v2" interface, the more specific error code is returned directly +by sqlite3_step(). +.Pp +SQLITE_MISUSE means that the this routine was called inappropriately. +Perhaps it was called on a prepared statement that +has already been finalized or on one that had previously returned +SQLITE_ERROR or SQLITE_DONE. +Or it could be the case that the same database connection is being +used by two or more threads at the same moment in time. +.Pp +For all versions of SQLite up to and including 3.6.23.1, a call to +.Fn sqlite3_reset +was required after sqlite3_step() returned anything other than SQLITE_ROW +before any subsequent invocation of sqlite3_step(). +Failure to reset the prepared statement using +.Fn sqlite3_reset +would result in an SQLITE_MISUSE return from sqlite3_step(). +But after version 3.6.23.1 (dateof:3.6.23.1, +sqlite3_step() began calling +.Fn sqlite3_reset +automatically in this circumstance rather than returning SQLITE_MISUSE. +This is not considered a compatibility break because any application +that ever receives an SQLITE_MISUSE error is broken by definition. +The SQLITE_OMIT_AUTORESET compile-time option +can be used to restore the legacy behavior. +.Pp +\fBGoofy Interface Alert:\fP In the legacy interface, the sqlite3_step() +API always returns a generic error code, SQLITE_ERROR, +following any error other than SQLITE_BUSY and SQLITE_MISUSE. +You must call +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +in order to find one of the specific error codes that better +describes the error. +We admit that this is a goofy design. +The problem has been fixed with the "v2" interface. +If you prepare all of your SQL statements using +.Fn sqlite3_prepare_v3 +or +.Fn sqlite3_prepare_v2 +or +.Fn sqlite3_prepare16_v2 +or +.Fn sqlite3_prepare16_v3 +instead of the legacy +.Fn sqlite3_prepare +and +.Fn sqlite3_prepare16 +interfaces, then the more specific error codes are returned +directly by sqlite3_step(). +The use of the "vX" interfaces is recommended. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4904. +.Bd -literal +SQLITE_API int sqlite3_step(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 |