diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_errcode.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_errcode.3 | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_errcode.3 b/static/netbsd/man3/sqlite3_errcode.3 new file mode 100644 index 00000000..8afc1d90 --- /dev/null +++ b/static/netbsd/man3/sqlite3_errcode.3 @@ -0,0 +1,115 @@ +.Dd January 24, 2024 +.Dt SQLITE3_ERRCODE 3 +.Os +.Sh NAME +.Nm sqlite3_errcode , +.Nm sqlite3_extended_errcode , +.Nm sqlite3_errmsg , +.Nm sqlite3_errmsg16 , +.Nm sqlite3_errstr , +.Nm sqlite3_error_offset +.Nd error codes and messages +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_errcode +.Fa "sqlite3 *db" +.Fc +.Ft int +.Fo sqlite3_extended_errcode +.Fa "sqlite3 *db" +.Fc +.Ft const char * +.Fo sqlite3_errmsg +.Fa "sqlite3*" +.Fc +.Ft const void * +.Fo sqlite3_errmsg16 +.Fa "sqlite3*" +.Fc +.Ft const char * +.Fo sqlite3_errstr +.Fa "int" +.Fc +.Ft int +.Fo sqlite3_error_offset +.Fa "sqlite3 *db" +.Fc +.Sh DESCRIPTION +If the most recent sqlite3_* API call associated with database connection +D failed, then the sqlite3_errcode(D) interface returns the numeric +result code or extended result code +for that API call. +The sqlite3_extended_errcode() interface is the same except that it +always returns the extended result code even when +extended result codes are disabled. +.Pp +The values returned by sqlite3_errcode() and/or sqlite3_extended_errcode() +might change with each API call. +Except, there are some interfaces that are guaranteed to never change +the value of the error code. +The error-code preserving interfaces include the following: +.Bl -bullet +.It +sqlite3_errcode() +.It +sqlite3_extended_errcode() +.It +sqlite3_errmsg() +.It +sqlite3_errmsg16() +.It +sqlite3_error_offset() +.El +.Pp +The sqlite3_errmsg() and sqlite3_errmsg16() return English-language +text that describes the error, as either UTF-8 or UTF-16 respectively, +or NULL if no error message is available. +(See how SQLite handles invalid UTF for exceptions to this +rule.) Memory to hold the error message string is managed internally. +The application does not need to worry about freeing the result. +However, the error string might be overwritten or deallocated by subsequent +calls to other SQLite interface functions. +.Pp +The sqlite3_errstr(E) interface returns the English-language text that +describes the result code E, as UTF-8, or NULL if E is not +an result code for which a text error message is available. +Memory to hold the error message string is managed internally and must +not be freed by the application. +.Pp +If the most recent error references a specific token in the input SQL, +the sqlite3_error_offset() interface returns the byte offset of the +start of that token. +The byte offset returned by sqlite3_error_offset() assumes that the +input SQL is UTF8. +If the most recent error does not reference a specific token in the +input SQL, then the sqlite3_error_offset() function returns -1. +.Pp +When the serialized threading mode is in use, it might +be the case that a second error occurs on a separate thread in between +the time of the first error and the call to these interfaces. +When that happens, the second error will be reported since these interfaces +always report the most recent result. +To avoid this, each thread can obtain exclusive use of the database connection +D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) +before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) +after all calls to the interfaces listed here are completed. +.Pp +If an interface fails with SQLITE_MISUSE, that means the interface +was invoked incorrectly by the application. +In that case, the error code and message may or may not be set. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3930. +.Bd -literal +SQLITE_API int sqlite3_errcode(sqlite3 *db); +SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); +SQLITE_API const char *sqlite3_errmsg(sqlite3*); +SQLITE_API const void *sqlite3_errmsg16(sqlite3*); +SQLITE_API const char *sqlite3_errstr(int); +SQLITE_API int sqlite3_error_offset(sqlite3 *db); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_db_mutex 3 , +.Xr sqlite3_mutex_alloc 3 |