Stephan Beal wrote:
> While i do fundamentally agree with your points, in practice it's not
> as difficult as you seem to be making it out to be. The rule is really
> simple: any non-0 code is an error unless the APIs specify otherwise,
> and the step() API does indeed document 2 non-error, non-0 error codes
> (SQLITE_STEP and SQLITE_DONE). Anywhere else in the API, non-0 means Bad
> News. There are relatively few cases (locking comes to mind) where an
> error returned due to something other than a misuse of the API should be
> considered recoverable (IMO).
I don't think that answer is satisfactory. Some errors are recoverable by
restarting the transaction. Others may be recoverable by creating a new
connection. Others may be recoverable by blowing away the database file
and starting over (because the database file is corrupt).
SQLite makes an attempt to detect a great variety of such cases and
return errors when they do happen. I would like to know in which cases
they will return such errors, and to which API calls, so that I can know
how to handle those cases.
I am not asking more of SQLite than I would ask of a Linux syscall man
page. In fact, I'm asking less -- I just want a ticket opened. Beggars
can't be choosers :-) and I don't have any claim on the devs' time.
E.g. from open(2):
ERRORS
EACCES The requested access to the file is not allowed, or search per-
mission is denied for one of the directories in the path prefix
of pathname, or the file did not exist yet and write access to
the parent directory is not allowed. (See also path_resolu-
tion(7).)
EEXIST pathname already exists and O_CREAT and O_EXCL were used.
EFAULT pathname points outside your accessible address space.
EFBIG See EOVERFLOW.
EINTR While blocked waiting to complete an open of a slow device
(e.g., a FIFO; see fifo(7)), the call was interrupted by a sig-
nal handler; see signal(7).
{etc}
Analogous listings in the SQLite function API pages would cure the issue
completely.
> The fact that (literally) millions of applications get written despite
> any perceived shortcomings in the documentation suggests that the docs are
> at least "adequate," if not "perfect."
Your argument is analogous to an argument that the Earth is the center
of the universe because lots of people think so. Nevermind what we
actually observe with our own eyes.
The docs are *not* adequate afaict for the purpose of determining in which
situations certain error codes will be raised, or what the SQLite authors
believe is appropriate subsequent client behavior.
A vague citation to a million anonymous programs of unknown quality is
not a convincing reason to think otherwise. And you and I both know
that a random sample of 1 million programs will contain roughly 999000
crappy ones. :-)
--
Eric A. Rubin-Smith
_______________________________________________
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users
