Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

SQLITE3_ERRCODE(3)         Library Functions Manual         SQLITE3_ERRCODE(3)

NAME
     sqlite3_errcode, sqlite3_extended_errcode, sqlite3_errmsg,
     sqlite3_errmsg16, sqlite3_errstr, sqlite3_error_offset - error codes and
     messages

SYNOPSIS
     #include <sqlite3.h>

     int
     sqlite3_errcode(sqlite3 *db);

     int
     sqlite3_extended_errcode(sqlite3 *db);

     const char *
     sqlite3_errmsg(sqlite3*);

     const void *
     sqlite3_errmsg16(sqlite3*);

     const char *
     sqlite3_errstr(int);

     int
     sqlite3_error_offset(sqlite3 *db);

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.

     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:

     ⊕   sqlite3_errcode()

     ⊕   sqlite3_extended_errcode()

     ⊕   sqlite3_errmsg()

     ⊕   sqlite3_errmsg16()

     ⊕   sqlite3_error_offset()

     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.

     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.

     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.

     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.

     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.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 3930.

     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);

SEE ALSO
     sqlite3(3), sqlite3_db_mutex(3), sqlite3_mutex_alloc(3)

NetBSD 11.99                   January 24, 2024                   NetBSD 11.99