.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