/ Check-in [428c581e]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documentation updates: clarify the behavior of sqlite3_column and sqlite3_value interfaces following an OOM error.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 428c581e4bed1d140cfb670633c9c61b36be7bb30a862d2e1ae7eaee26dccb4f
User & Date: drh 2018-06-12 19:22:30
Context
2018-06-12
19:35
Documentation update: clarify that sqlite3_errcode() and related interfaces do not themselves modify the error code. check-in: 858fc52b user: drh tags: trunk
19:22
Documentation updates: clarify the behavior of sqlite3_column and sqlite3_value interfaces following an OOM error. check-in: 428c581e user: drh tags: trunk
13:52
Improvements to SCopy correctness tracking when SQLITE_DEBUG is enabled. check-in: b2973f23 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  4510   4510   ** ^The pointers returned are valid until a type conversion occurs as
  4511   4511   ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  4512   4512   ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
  4513   4513   ** and BLOBs is freed automatically.  Do not pass the pointers returned
  4514   4514   ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  4515   4515   ** [sqlite3_free()].
  4516   4516   **
  4517         -** ^(If a memory allocation error occurs during the evaluation of any
  4518         -** of these routines, a default value is returned.  The default value
  4519         -** is either the integer 0, the floating point number 0.0, or a NULL
  4520         -** pointer.  Subsequent calls to [sqlite3_errcode()] will return
  4521         -** [SQLITE_NOMEM].)^
         4517  +** As long as the input parameters are correct, these routines will only
         4518  +** fail if an out-of-memory error occurs during a format conversion.
         4519  +** Only the following subset of interfaces are subject to out-of-memory
         4520  +** errors:
         4521  +**
         4522  +** <ul>
         4523  +** <li> sqlite3_column_blob()
         4524  +** <li> sqlite3_column_text()
         4525  +** <li> sqlite3_column_text16()
         4526  +** <li> sqlite3_column_bytes()
         4527  +** <li> sqlite3_column_bytes16()
         4528  +** </ul>
         4529  +**
         4530  +** If an out-of-memory error occurs, then the return value from these
         4531  +** routines is the same as if the column had contained an SQL NULL value.
         4532  +** Valid SQL NULL returns can be distinguished from out-of-memory errors
         4533  +** by invoking the [sqlite3_errcode()] immediately after the suspect
         4534  +** return value is obtained and before any
         4535  +** other SQLite interface is called on the same [database connection].
  4522   4536   */
  4523   4537   const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  4524   4538   double sqlite3_column_double(sqlite3_stmt*, int iCol);
  4525   4539   int sqlite3_column_int(sqlite3_stmt*, int iCol);
  4526   4540   sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  4527   4541   const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  4528   4542   const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
................................................................................
  4853   4867   ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
  4854   4868   ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  4855   4869   ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  4856   4870   ** or [sqlite3_value_text16()].
  4857   4871   **
  4858   4872   ** These routines must be called from the same thread as
  4859   4873   ** the SQL function that supplied the [sqlite3_value*] parameters.
         4874  +**
         4875  +** As long as the input parameter is correct, these routines can only
         4876  +** fail if an out-of-memory error occurs during a format conversion.
         4877  +** Only the following subset of interfaces are subject to out-of-memory
         4878  +** errors:
         4879  +**
         4880  +** <ul>
         4881  +** <li> sqlite3_value_blob()
         4882  +** <li> sqlite3_value_text()
         4883  +** <li> sqlite3_value_text16()
         4884  +** <li> sqlite3_value_text16le()
         4885  +** <li> sqlite3_value_text16be()
         4886  +** <li> sqlite3_value_bytes()
         4887  +** <li> sqlite3_value_bytes16()
         4888  +** </ul>
         4889  +**
         4890  +** If an out-of-memory error occurs, then the return value from these
         4891  +** routines is the same as if the column had contained an SQL NULL value.
         4892  +** Valid SQL NULL returns can be distinguished from out-of-memory errors
         4893  +** by invoking the [sqlite3_errcode()] immediately after the suspect
         4894  +** return value is obtained and before any
         4895  +** other SQLite interface is called on the same [database connection].
  4860   4896   */
  4861   4897   const void *sqlite3_value_blob(sqlite3_value*);
  4862   4898   double sqlite3_value_double(sqlite3_value*);
  4863   4899   int sqlite3_value_int(sqlite3_value*);
  4864   4900   sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
  4865   4901   void *sqlite3_value_pointer(sqlite3_value*, const char*);
  4866   4902   const unsigned char *sqlite3_value_text(sqlite3_value*);