From: drh Date: Tue, 18 Mar 2008 13:47:20 +0000 (+0000) Subject: Update the documentation to distinguish between protected and unprotected X-Git-Tag: version-3.6.10~1298 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=aa28e1478abe8a6edd4fee5217258c740d30b95a;p=thirdparty%2Fsqlite.git Update the documentation to distinguish between protected and unprotected sqlite3_value objects. (CVS 4879) FossilOrigin-Name: 074ee55ffd1f0b7bb120a440d8bcf19e249ada96 --- diff --git a/manifest b/manifest index 56020fdf3f..d286b8594c 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Test\sscript\schanges\sthat\sgo\swith\sthe\scoverage\senhancements\sof\sthe\nprevious\scheck-in.\s(CVS\s4878) -D 2008-03-18T13:46:53 +C Update\sthe\sdocumentation\sto\sdistinguish\sbetween\sprotected\sand\sunprotected\nsqlite3_value\sobjects.\s(CVS\s4879) +D 2008-03-18T13:47:21 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7 F Makefile.in 5be94fea84f1599672e5041de03b97990baca593 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -139,7 +139,7 @@ F src/random.c 02ef38b469237482f1ea14a78b2087cfbaec48bd F src/select.c d0a1e01a2a6c05bd60324e843c7e4581d3605950 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96 F src/shell.c 22297fffa6f00a6c6d44020fa13b1184a1bb372d -F src/sqlite.h.in 1cf531c45f20cedf0786f4dc5dedc8dcc33b5df3 +F src/sqlite.h.in 34368f76fb43122dffb97188c2a5166aa11ad8e5 F src/sqlite3ext.h 50c70a894ffe8e6ada5948c89b91db0a80a6b2a7 F src/sqliteInt.h 2726f01ca494e518542732ee57a490806f92bace F src/sqliteLimit.h ee4430f88f69bf63527967bb35ca52af7b0ccb1e @@ -623,7 +623,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5 -P edd207b9a9df5d73ec34474a4e90fcb592f06cf1 -R 4c32224dd22a5f74d7f84201633ed292 +P f87ddf83a5d1340652f222972a7d75f4fdbe776b +R 4eff51fa0e2146019ac3cf43f90b51e7 U drh -Z 6ec7b57f051cece6980e6912c8801c48 +Z eaeb575bf3bebac1f6b6f099c0feb83e diff --git a/manifest.uuid b/manifest.uuid index d7beb7e35a..a5ae2854ff 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -f87ddf83a5d1340652f222972a7d75f4fdbe776b \ No newline at end of file +074ee55ffd1f0b7bb120a440d8bcf19e249ada96 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 7fc8be2a9d..c351d8bee1 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.291 2008/03/08 12:37:31 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.292 2008/03/18 13:47:21 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -2294,12 +2294,39 @@ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* ** CAPI3REF: Dynamically Typed Value Object {F15000} +** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} ** ** SQLite uses the sqlite3_value object to represent all values -** that are or can be stored in a database table. +** that can be stored in a database table. ** SQLite uses dynamic typing for the values it stores. ** Values stored in sqlite3_value objects can be ** be integers, floating point values, strings, BLOBs, or NULL. +** +** An sqlite3_value object may be either "protected" or "unprotected". +** Some interfaces require a protected sqlite3_value. Other interfaces +** will accept either a protected or an unprotected sqlite3_value. +** Every interface that accepts sqlite3_value arguments specifies +** whether or not it requires a protected sqlite3_value. +** +** The terms "protected" and "unprotected" refer to whether or not +** a mutex is held. A internal mutex is held for a protected +** sqlite3_value object but no mutex is held for an unprotected +** sqlite3_value object. If SQLite is compiled to be single-threaded +** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0) +** then there is no distinction between +** protected and unprotected sqlite3_value objects and they can be +** used interchangable. However, for maximum code portability it +** is recommended that applications make the distinction between +** between protected and unprotected sqlite3_value objects even if +** they are single threaded. +** +** The sqlite3_value objects that are passed as parameters into the +** implementation of application-defined SQL functions are protected. +** The sqlite3_value object returned by +** [sqlite3_column_value()] is unprotected. +** Unprotected sqlite3_value objects may only be used with +** [sqlite3_result_value()] and [sqlite3_bind_value()]. All other +** interfaces that use sqlite3_value require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; @@ -2461,6 +2488,10 @@ typedef struct sqlite3_context sqlite3_context; ** ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound ** is a blob of L bytes, or a zero-length blob if L is negative. +** +** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may +** be either a [protected sqlite3_value] object or an +** [unprotected sqlite3_value] object. */ int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); @@ -3019,6 +3050,15 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** but leaves the result in UTF-16 in native byte order instead of UTF-8. ** The zero terminator is not included in this count. ** +** The object returned by [sqlite3_column_value()] is an +** [unprotected sqlite3_value] object. An unprotected sqlite3_value object +** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. +** If the [unprotected sqlite3_value] object returned by +** [sqlite3_column_value()] is used in any other way, including calls +** to routines like +** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()], +** then the behavior is undefined. +** ** These routines attempt to convert the value where appropriate. For ** example, if the internal representation is FLOAT and a text result ** is requested, [sqlite3_snprintf()] is used internally to do the conversion @@ -3160,7 +3200,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** [prepared statement] S. ** ** {F13830} The [sqlite3_column_value(S,N)] interface returns a -** pointer to the [sqlite3_value] object that for the +** pointer to an [unprotected sqlite3_value] object for the ** Nth column in the current row of the result set for ** [prepared statement] S. */ @@ -3350,6 +3390,12 @@ int sqlite3_reset(sqlite3_stmt *pStmt); ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer ** function L will always be invoked exactly once if the ** step function S is called one or more times. +** +** {F16142} When SQLite invokes either the xFunc or xStep function of +** an application-defined SQL function or aggregate created +** by [sqlite3_create_function()] or [sqlite3_create_function16()], +** then the array of [sqlite3_value] objects passed as the +** third parameter are always [protected sqlite3_value] objects. */ int sqlite3_create_function( sqlite3 *db, @@ -3412,14 +3458,18 @@ int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); ** to [sqlite3_create_function()] and [sqlite3_create_function16()] ** define callbacks that implement the SQL functions and aggregates. ** The 4th parameter to these callbacks is an array of pointers to -** [sqlite3_value] objects. There is one [sqlite3_value] object for +** [protected sqlite3_value] objects. There is one [sqlite3_value] object for ** each parameter to the SQL function. These routines are used to ** extract values from the [sqlite3_value] objects. ** +** These routines work only with [protected sqlite3_value] objects. +** Any attempt to use these routines on an [unprotected sqlite3_value] +** object results in undefined behavior. +** ** These routines work just like the corresponding ** [sqlite3_column_blob | sqlite3_column_* routines] except that -** these routines take a single [sqlite3_value*] pointer instead -** of an [sqlite3_stmt*] pointer and an integer column number. +** these routines take a single [protected sqlite3_value] object pointer +** instead of an [sqlite3_stmt*] pointer and an integer column number. ** ** The sqlite3_value_text16() interface extracts a UTF16 string ** in the native byte-order of the host machine. The @@ -3441,16 +3491,13 @@ int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); ** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as -** the SQL function that supplied the sqlite3_value* parameters. -** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()] -** interface, then these routines should be called from the same thread -** that ran [sqlite3_column_value()]. +** the SQL function that supplied the [sqlite3_value*] parameters. ** ** ** INVARIANTS: ** ** {F15103} The [sqlite3_value_blob(V)] interface converts the -** [sqlite3_value] object V into a blob and then returns a +** [protected sqlite3_value] object V into a blob and then returns a ** pointer to the converted value. ** ** {F15106} The [sqlite3_value_bytes(V)] interface returns the @@ -3466,33 +3513,33 @@ int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)]. ** ** {F15112} The [sqlite3_value_double(V)] interface converts the -** [sqlite3_value] object V into a floating point value and +** [protected sqlite3_value] object V into a floating point value and ** returns a copy of that value. ** ** {F15115} The [sqlite3_value_int(V)] interface converts the -** [sqlite3_value] object V into a 64-bit signed integer and +** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** ** {F15118} The [sqlite3_value_int64(V)] interface converts the -** [sqlite3_value] object V into a 64-bit signed integer and +** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns a copy of that integer. ** ** {F15121} The [sqlite3_value_text(V)] interface converts the -** [sqlite3_value] object V into a zero-terminated UTF-8 +** [protected sqlite3_value] object V into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** ** {F15124} The [sqlite3_value_text16(V)] interface converts the -** [sqlite3_value] object V into a zero-terminated 2-byte +** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 native byte order ** string and returns a pointer to that string. ** ** {F15127} The [sqlite3_value_text16be(V)] interface converts the -** [sqlite3_value] object V into a zero-terminated 2-byte +** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 big-endian ** string and returns a pointer to that string. ** ** {F15130} The [sqlite3_value_text16le(V)] interface converts the -** [sqlite3_value] object V into a zero-terminated 2-byte +** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 little-endian ** string and returns a pointer to that string. ** @@ -3502,12 +3549,12 @@ int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); ** the [sqlite3_value] object V. ** ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts -** the [sqlite3_value] object V into either an integer or +** the [protected sqlite3_value] object V into either an integer or ** a floating point value if it can do so without loss of ** information, and returns one of [SQLITE_NULL], ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or ** [SQLITE_BLOB] as appropriate for -** the [sqlite3_value] object V after the conversion attempt. +** the [protected sqlite3_value] object V after the conversion attempt. */ const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); @@ -3777,11 +3824,14 @@ typedef void (*sqlite3_destructor_type)(void*); ** from [sqlite3_malloc()] before it returns. ** ** The sqlite3_result_value() interface sets the result of -** the application-defined function to be a copy the [sqlite3_value] -** object specified by the 2nd parameter. The +** the application-defined function to be a copy the +** [unprotected sqlite3_value] object specified by the 2nd parameter. The ** sqlite3_result_value() interface makes a copy of the [sqlite3_value] ** so that [sqlite3_value] specified in the parameter may change or ** be deallocated after sqlite3_result_value() returns without harm. +** A [protected sqlite3_value] object may always be used where an +** [unprotected sqlite3_value] object is required, so either +** kind of [sqlite3_value] object can be used with this interface. ** ** If these routines are called from within the different thread ** than the one containing the application-defined function that recieved @@ -3851,7 +3901,8 @@ typedef void (*sqlite3_destructor_type)(void*); ** is positive. ** ** {F16448} The [sqlite3_result_value(C,V)] interface changes the -** return value of function C to be [sqlite3_value] object V. +** return value of function C to be [unprotected sqlite3_value] +** object V. ** ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the ** return value of function C to be an N-byte blob of all zeros.