I respectfully re-raise my issue. The "TLDR" is that the C API docs are critically lacking in specificity in a relatively wide range of areas, as exemplified below, making it difficult to write correct clients against the library.
Do the SQLite authors disagree with my below points about the API docs for sqlite3_step(), sqlite3_exec(), and sqlite3_prepare_v2()? I think the criticisms can be extended to other API calls. If the authors do not disagree then can we create a ticket against the docs? On Mon, Jun 30, 2014 at 2:47 PM, Eric Rubin-Smith <eas....@gmail.com> wrote: > I've been using the sqlite Tcl API for about 3 million years, with much > delight. I'm venturing now into the C API -- hoping to put sqlite into a > large monolithic "always on" C++ daemon. I would like to use the API in a > way perfectly in line with how the authors intended. > > But it's sort of hard to figure out exactly what the authors intended in > some cases. > > Consider the man page for sqlite3_step() ( > http://sqlite.org/c3ref/step.html): > > "With the "v2" interface, any of the other result codes > <http://sqlite.org/c3ref/c_abort.html> or extended result codes > <http://sqlite.org/c3ref/c_abort_rollback.html> might be returned as > well.... SQLITE_ERROR <http://sqlite.org/c3ref/c_abort.html> 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 sqlite3_errmsg() > <http://sqlite.org/c3ref/errcode.html>. With the legacy interface, a more > specific error code (for example, SQLITE_INTERRUPT > <http://sqlite.org/c3ref/c_abort.html>, SQLITE_SCHEMA > <http://sqlite.org/c3ref/c_abort.html>, SQLITE_CORRUPT > <http://sqlite.org/c3ref/c_abort.html>, and so forth) can be obtained by > calling sqlite3_reset() <http://sqlite.org/c3ref/reset.html> on the prepared > statement <http://sqlite.org/c3ref/stmt.html>. In the "v2" interface, the > more specific error code is returned directly by sqlite3_step()." > > I am a big fan generally of the clarity of the sqlite docs. But this page > could use another section detailing all the possible result codes' specific > semantics under sqlite3_step(), and in particular what the client should do > in those circumstances. Similar to how your normal linux system call man > page details such things. > > The page bites a bit of that off, as you see above. But consider e.g. > (from http://sqlite.org/c3ref/c_abort.html): > > #define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */ > > Am I supposed to look for that? What am I supposed to do with it if I get > it? How about SQLITE_CANTOPEN? Seems like that shouldn't be a possibility > by the time we hit sqlite3_step(), but the docs are silent on the matter. > So what am I to do? > > If I get SQLITE_IOERR, is that always permanent, or do I need to look for > things like SQLITE_IOERR_LOCK and if that bit is set then rollback and > retry? > > > sqlite3_exec() has the same issue: it's hard to say from reading the docs > exactly which of the error codes might be returned, and what the caller > should do in those cases. > > sqlite3_prepare_v2() again has the same issue: > > "On success, the sqlite3_prepare() family of routines return SQLITE_OK > <http://sqlite.org/c3ref/c_abort.html>; otherwise an error code > <http://sqlite.org/c3ref/c_abort.html> is returned." > > Again, can *any* of those error codes be returned? Which of them is > permanent and which are temporary in the case of prepare_v2()? > > And so on. > > Apologies if I have missed some of the docs. Any pointers, or especially > example C code that the SQLite devs consider perfectly robust and complete > API usage, are much appreciated. > > Eric > _______________________________________________ sqlite-users mailing list sqlite-users@sqlite.org http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users
