1.Dd January 24, 2024 2.Dt SQLITE3_ERRCODE 3 3.Os 4.Sh NAME 5.Nm sqlite3_errcode , 6.Nm sqlite3_extended_errcode , 7.Nm sqlite3_errmsg , 8.Nm sqlite3_errmsg16 , 9.Nm sqlite3_errstr , 10.Nm sqlite3_error_offset 11.Nd error codes and messages 12.Sh SYNOPSIS 13.In sqlite3.h 14.Ft int 15.Fo sqlite3_errcode 16.Fa "sqlite3 *db" 17.Fc 18.Ft int 19.Fo sqlite3_extended_errcode 20.Fa "sqlite3 *db" 21.Fc 22.Ft const char * 23.Fo sqlite3_errmsg 24.Fa "sqlite3*" 25.Fc 26.Ft const void * 27.Fo sqlite3_errmsg16 28.Fa "sqlite3*" 29.Fc 30.Ft const char * 31.Fo sqlite3_errstr 32.Fa "int" 33.Fc 34.Ft int 35.Fo sqlite3_error_offset 36.Fa "sqlite3 *db" 37.Fc 38.Sh DESCRIPTION 39If the most recent sqlite3_* API call associated with database connection 40D failed, then the sqlite3_errcode(D) interface returns the numeric 41result code or extended result code 42for that API call. 43The sqlite3_extended_errcode() interface is the same except that it 44always returns the extended result code even when 45extended result codes are disabled. 46.Pp 47The values returned by sqlite3_errcode() and/or sqlite3_extended_errcode() 48might change with each API call. 49Except, there are some interfaces that are guaranteed to never change 50the value of the error code. 51The error-code preserving interfaces include the following: 52.Bl -bullet 53.It 54sqlite3_errcode() 55.It 56sqlite3_extended_errcode() 57.It 58sqlite3_errmsg() 59.It 60sqlite3_errmsg16() 61.It 62sqlite3_error_offset() 63.El 64.Pp 65The sqlite3_errmsg() and sqlite3_errmsg16() return English-language 66text that describes the error, as either UTF-8 or UTF-16 respectively, 67or NULL if no error message is available. 68(See how SQLite handles invalid UTF for exceptions to this 69rule.) Memory to hold the error message string is managed internally. 70The application does not need to worry about freeing the result. 71However, the error string might be overwritten or deallocated by subsequent 72calls to other SQLite interface functions. 73.Pp 74The sqlite3_errstr(E) interface returns the English-language text that 75describes the result code E, as UTF-8, or NULL if E is not 76an result code for which a text error message is available. 77Memory to hold the error message string is managed internally and must 78not be freed by the application. 79.Pp 80If the most recent error references a specific token in the input SQL, 81the sqlite3_error_offset() interface returns the byte offset of the 82start of that token. 83The byte offset returned by sqlite3_error_offset() assumes that the 84input SQL is UTF8. 85If the most recent error does not reference a specific token in the 86input SQL, then the sqlite3_error_offset() function returns -1. 87.Pp 88When the serialized threading mode is in use, it might 89be the case that a second error occurs on a separate thread in between 90the time of the first error and the call to these interfaces. 91When that happens, the second error will be reported since these interfaces 92always report the most recent result. 93To avoid this, each thread can obtain exclusive use of the database connection 94D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) 95before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) 96after all calls to the interfaces listed here are completed. 97.Pp 98If an interface fails with SQLITE_MISUSE, that means the interface 99was invoked incorrectly by the application. 100In that case, the error code and message may or may not be set. 101.Sh IMPLEMENTATION NOTES 102These declarations were extracted from the 103interface documentation at line 3930. 104.Bd -literal 105SQLITE_API int sqlite3_errcode(sqlite3 *db); 106SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); 107SQLITE_API const char *sqlite3_errmsg(sqlite3*); 108SQLITE_API const void *sqlite3_errmsg16(sqlite3*); 109SQLITE_API const char *sqlite3_errstr(int); 110SQLITE_API int sqlite3_error_offset(sqlite3 *db); 111.Ed 112.Sh SEE ALSO 113.Xr sqlite3 3 , 114.Xr sqlite3_db_mutex 3 , 115.Xr sqlite3_mutex_alloc 3 116