Fossil SCM

fossil-scm / extsrc / sqlite3.h
Source Blame History 1176 lines
d452c5c… brickviking 1 ** <a href="http://fossil-scm.org/">Fossil configuration management
3c639f7… drh 2 ** [sqlite_version()] and [sqlite_source_id()].
3361df8… drh 3 #define SQLITE_VERSION "3.54.0"
3361df8… drh 4 #define SQLITE_VERSION_NUMBER 3054000
40c5397… drh 5 #define SQLITE_SOURCE_ID "2026-10-09 11:47:51 a3332bd623d997921c3186433cd1eab0c9413aa0f68d93b1731cf80128ec3a36"
dc45faa… drh 6 #define SQLITE_SCM_BRANCH "trunk"
17f9878… drh 7 #define SQLITE_SCM_TAGS ""
40c5397… drh 8 #define SQLITE_SCM_DATETIME "2026-10-09T11:47:51.732Z"
746a963… drh 9 ** ^The sqlite3_version[] string constant contains the text of the
746a963… drh 10 ** [SQLITE_VERSION] macro. ^The sqlite3_libversion() function returns a
746a963… drh 11 ** pointer to the sqlite3_version[] string constant. The sqlite3_libversion()
3c639f7… drh 12 ** See also: [sqlite_version()] and [sqlite_source_id()].
746a963… drh 13 ** semicolon-separated SQL statements passed into its 2nd argument,
746a963… drh 14 ** entry represents the name of a corresponding result column as obtained
e6e6a32… drh 15 #define SQLITE_EMPTY 16 /* No content */
104c079… drh 16 #define SQLITE_ERROR_RESERVESIZE (SQLITE_ERROR | (4<<8))
104c079… drh 17 #define SQLITE_ERROR_KEY (SQLITE_ERROR | (5<<8))
104c079… drh 18 #define SQLITE_ERROR_UNABLE (SQLITE_ERROR | (6<<8))
104c079… drh 19 #define SQLITE_IOERR_BADKEY (SQLITE_IOERR | (35<<8))
104c079… drh 20 #define SQLITE_IOERR_CODEC (SQLITE_IOERR | (36<<8))
ad59a04… drh 21 #define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal only */
746a963… drh 22 ** [sqlite3_open_v2()] has historically been a no-op and might become an
746a963… drh 23 ** least restrictive to most restrictive.
92871e0… drh 24 ** The SQLITE_FCNTL_SYNC_OMITTED file-control is no longer used.
746a963… drh 25 ** all [VFSes] in the VFS stack. The names of all VFS shims and the
746a963… drh 26 ** of type "[sqlite3_vfs] **". This opcode will set *X
d23f1ab… drh 27 ** <li>[[SQLITE_FCNTL_BLOCK_ON_CONNECT]]
d23f1ab… drh 28 ** The [SQLITE_FCNTL_BLOCK_ON_CONNECT] opcode is used to configure the
d23f1ab… drh 29 ** VFS to block when taking a SHARED lock to connect to a wal mode database.
d23f1ab… drh 30 ** This is used to implement the functionality associated with
d23f1ab… drh 31 ** SQLITE_SETLK_BLOCK_ON_CONNECT.
d23f1ab… drh 32 **
746a963… drh 33 ** transaction open on the database or not. It is only available on unix. The
92871e0… drh 34 **
92871e0… drh 35 ** <li>[[SQLITE_FCNTL_FILESTAT]]
92871e0… drh 36 ** The [SQLITE_FCNTL_FILESTAT] opcode returns low-level diagnostic information
92871e0… drh 37 ** about the [sqlite3_file] objects used access the database and journal files
92871e0… drh 38 ** for the given schema. The fourth parameter to [sqlite3_file_control()]
92871e0… drh 39 ** should be an initialized [sqlite3_str] pointer. JSON text describing
92871e0… drh 40 ** various aspects of the sqlite3_file object is appended to the sqlite3_str.
92871e0… drh 41 ** The SQLITE_FCNTL_FILESTAT opcode is usually a no-op, unless compile-time
92871e0… drh 42 ** options are used to enable it.
d23f1ab… drh 43 #define SQLITE_FCNTL_BLOCK_ON_CONNECT 44
92871e0… drh 44 #define SQLITE_FCNTL_FILESTAT 45
92871e0… drh 45
ad59a04… drh 46 /* reserved file-control numbers:
ad59a04… drh 47 ** 101
ad59a04… drh 48 ** 102
ad59a04… drh 49 ** 103
ad59a04… drh 50 */
ad59a04… drh 51
d326547… drh 52 ** ^The xSetSystemCall(), xGetSystemCall(), and xNextSystemCall() interfaces
746a963… drh 53 ** initialized when [sqlite3_open()] is called if it has not been initialized
ad59a04… drh 54 ** configuration option, then the sqlite3_config() call will
ad59a04… drh 55 ** return SQLITE_MISUSE.
746a963… drh 56 ** routines with a wrapper that simulates memory allocation failure or
746a963… drh 57 ** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes a single argument of
746a963… drh 58 ** but some applications might prefer to run slower in exchange for
746a963… drh 59 ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes a single argument of type int,
746a963… drh 60 ** of -1024*N bytes if N is negative. ^If additional
746a963… drh 61 ** in place of the mutex routines built into SQLite.)^ ^SQLite makes a copy of
679265a… drh 62 ** the default size of [lookaside memory] on each [database connection].
679265a… drh 63 ** size of each lookaside buffer slot ("sz") and the second is the number of
679265a… drh 64 ** slots allocated to each database connection ("cnt").)^
679265a… drh 65 ** ^(SQLITE_CONFIG_LOOKASIDE sets the <i>default</i> lookaside size.
679265a… drh 66 ** The [SQLITE_DBCONFIG_LOOKASIDE] option to [sqlite3_db_config()] can
679265a… drh 67 ** be used to change the lookaside configuration on individual connections.)^
679265a… drh 68 ** The [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to change the
679265a… drh 69 ** default lookaside configuration at compile-time.
679265a… drh 70 ** </dd>
746a963… drh 71 ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies off
746a963… drh 72 ** a log message after formatting via [sqlite3_snprintf()].
935cd45… drh 73 ** can be passed as the second parameter to the [sqlite3_db_config()] interface.
935cd45… drh 74 **
746a963… drh 75 ** The [sqlite3_db_config()] interface is a var-args function. It takes a
935cd45… drh 76 ** variable number of parameters, though always at least two. The number of
935cd45… drh 77 ** parameters passed into sqlite3_db_config() depends on which of these
935cd45… drh 78 ** constants is given as the second parameter. This documentation page
935cd45… drh 79 ** refers to parameters beyond the second as "arguments". Thus, when this
935cd45… drh 80 ** page says "the N-th argument" it means "the N-th parameter past the
935cd45… drh 81 ** configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".
88bc7cf… drh 82 ** <dd> The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the
679265a… drh 83 ** configuration of the [lookaside memory allocator] within a database
88bc7cf… drh 84 ** connection.
88bc7cf… drh 85 ** The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i>
88bc7cf… drh 86 ** in the [DBCONFIG arguments|usual format].
935cd45… drh 87 ** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two,
935cd45… drh 88 ** so that a call to [sqlite3_db_config()] that uses SQLITE_DBCONFIG_LOOKASIDE
935cd45… drh 89 ** should have a total of five parameters.
679265a… drh 90 ** <ol>
679265a… drh 91 ** <li><p>The first argument ("buf") is a
679265a… drh 92 ** The first argument may be NULL in which case SQLite will allocate the
679265a… drh 93 ** lookaside buffer itself using [sqlite3_malloc()].
679265a… drh 94 ** <li><P>The second argument ("sz") is the
679265a… drh 95 ** size of each lookaside buffer slot. Lookaside is disabled if "sz"
679265a… drh 96 ** is less than 8. The "sz" argument should be a multiple of 8 less than
679265a… drh 97 ** 65536. If "sz" does not meet this constraint, it is reduced in size until
679265a… drh 98 ** it does.
ad59a04… drh 99 ** <li><p>The third argument ("cnt") is the number of slots.
ad59a04… drh 100 ** Lookaside is disabled if "cnt"is less than 1.
ad59a04… drh 101 * The "cnt" value will be reduced, if necessary, so
ad59a04… drh 102 ** that the product of "sz" and "cnt" does not exceed 2,147,418,112. The "cnt"
679265a… drh 103 ** parameter is usually chosen so that the product of "sz" and "cnt" is less
679265a… drh 104 ** than 1,000,000.
679265a… drh 105 ** </ol>
679265a… drh 106 ** <p>If the "buf" argument is not NULL, then it must
679265a… drh 107 ** point to a memory buffer with a size that is greater than
679265a… drh 108 ** or equal to the product of "sz" and "cnt".
679265a… drh 109 ** The buffer must be aligned to an 8-byte boundary.
679265a… drh 110 ** The lookaside memory
679265a… drh 111 ** when the value returned by [SQLITE_DBSTATUS_LOOKASIDE_USED] is zero.
679265a… drh 112 ** [SQLITE_BUSY].
679265a… drh 113 ** If the "buf" argument is NULL and an attempt
679265a… drh 114 ** to allocate memory based on "sz" and "cnt" fails, then
679265a… drh 115 ** lookaside is silently disabled.
679265a… drh 116 ** <p>
679265a… drh 117 ** The [SQLITE_CONFIG_LOOKASIDE] configuration option can be used to set the
679265a… drh 118 ** default lookaside configuration at initialization. The
679265a… drh 119 ** [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to set the default lookaside
679265a… drh 120 ** configuration at compile-time. Typical values for lookaside are 1200 for
679265a… drh 121 ** "sz" and 40 to 100 for "cnt".
679265a… drh 122 ** </dd>
88bc7cf… drh 123 ** [foreign key constraints]. This is the same setting that is
88bc7cf… drh 124 ** enabled or disabled by the [PRAGMA foreign_keys] statement.
88bc7cf… drh 125 ** triggers in the main database schema or in the schemas of [ATTACH]-ed
88bc7cf… drh 126 ** There must be two additional arguments.
dc45faa… drh 127 ** <dd> ^This option is used to enable or disable using the
dc45faa… drh 128 ** [fts3_tokenizer()] function - part of the [FTS3] full-text search engine
dc45faa… drh 129 ** extension - without using bound parameters as the parameters. Doing so
dc45faa… drh 130 ** is disabled by default. There must be two additional arguments. The first
dc45faa… drh 131 ** argument is an integer. If it is passed 0, then using fts3_tokenizer()
dc45faa… drh 132 ** without bound parameters is disabled. If it is passed a positive value,
dc45faa… drh 133 ** then calling fts3_tokenizer without bound parameters is enabled. If it
dc45faa… drh 134 ** is passed a negative value, this setting is not modified - this can be
dc45faa… drh 135 ** used to query for the current setting. The second parameter is a pointer
dc45faa… drh 136 ** to an integer into which is written 0 or 1 to indicate the current value
dc45faa… drh 137 ** of this setting (after it is modified, if applicable). The second
dc45faa… drh 138 ** parameter may be a NULL pointer, in which case the value of the setting
dc45faa… drh 139 ** is not reported back. Refer to [FTS3] documentation for further details.
dc45faa… drh 140 ** </dd>
88bc7cf… drh 141 ** There must be two additional arguments.
746a963… drh 142 ** If the first argument is -1, then no changes are made to the state of either
746a963… drh 143 ** the C-API or the SQL function.
88bc7cf… drh 144 ** schema. This option does not follow the
88bc7cf… drh 145 ** [DBCONFIG arguments|usual SQLITE_DBCONFIG argument format].
935cd45… drh 146 ** This option takes exactly one additional argument so that the
935cd45… drh 147 ** [sqlite3_db_config()] call has a total of three parameters. The
935cd45… drh 148 ** extra argument must be a pointer to a constant UTF8 string which
935cd45… drh 149 ** will become the new schema name in place of "main". ^SQLite does
935cd45… drh 150 ** not make a copy of the new main schema name string, so the application
935cd45… drh 151 ** must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME
935cd45… drh 152 ** is unchanged until after the database connection closes.
88bc7cf… drh 153 ** <dd> Usually, when a database in [WAL mode] is closed or detached from a
88bc7cf… drh 154 ** database handle, SQLite checks if if there are other connections to the
88bc7cf… drh 155 ** same database, and if there are no other database connection (if the
88bc7cf… drh 156 ** connection being closed is the last open connection to the database),
88bc7cf… drh 157 ** then SQLite performs a [checkpoint] before closing the connection and
88bc7cf… drh 158 ** deletes the WAL file. The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can
935cd45… drh 159 ** be used to override that behavior. The first argument passed to this
935cd45… drh 160 ** operation (the third parameter to [sqlite3_db_config()]) is an integer
935cd45… drh 161 ** which is positive to disable checkpoints-on-close, or zero (the default)
935cd45… drh 162 ** to enable them, and negative to leave the setting unchanged.
935cd45… drh 163 ** The second argument (the fourth parameter) is a pointer to an integer
746a963… drh 164 ** the legacy behavior of the [ALTER TABLE RENAME] command such that it
746a963… drh 165 ** created database files to have a schema format version number (the 4-byte
4f76459… drh 166 ** [SQLITE_ENABLE_STMT_SCANSTATUS] builds. In this case, it sets or clears
4f76459… drh 167 ** a flag that enables collection of run-time performance statistics
4f76459… drh 168 ** used by [sqlite3_stmt_scanstatus_v2()] and the [nexec and ncycle]
4f76459… drh 169 ** columns of the [bytecode virtual table].
4f76459… drh 170 ** For statistics to be collected, the flag must be set on
4f76459… drh 171 ** the database handle both when the SQL statement is
4f76459… drh 172 ** [sqlite3_prepare|prepared] and when it is [sqlite3_step|stepped].
4f76459… drh 173 ** The flag is set (collection of statistics is enabled) by default.
4f76459… drh 174 ** <p>This option takes two arguments: an integer and a pointer to
746a963… drh 175 ** an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 176 ** same as setting [PRAGMA reverse_unordered_selects]. <p>This option takes
88bc7cf… drh 177 ** [[SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]]
88bc7cf… drh 178 ** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</dt>
88bc7cf… drh 179 ** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables
88bc7cf… drh 180 ** the ability of the [ATTACH DATABASE] SQL command to create a new database
88bc7cf… drh 181 ** file if the database filed named in the ATTACH command does not already
88bc7cf… drh 182 ** exist. This ability of ATTACH to create a new database is enabled by
88bc7cf… drh 183 ** default. Applications can disable or reenable the ability for ATTACH to
88bc7cf… drh 184 ** create new database files using this DBCONFIG option.<p>
88bc7cf… drh 185 ** This option takes two arguments which are an integer and a pointer
88bc7cf… drh 186 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 187 ** leave unchanged the attach-create flag, respectively. If the second
88bc7cf… drh 188 ** argument is not NULL, then 0 or 1 is written into the integer that the
88bc7cf… drh 189 ** second argument points to depending on if the attach-create flag is set
88bc7cf… drh 190 ** after processing the first argument.
88bc7cf… drh 191 ** </dd>
88bc7cf… drh 192 **
88bc7cf… drh 193 ** [[SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE]]
88bc7cf… drh 194 ** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</dt>
88bc7cf… drh 195 ** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the
88bc7cf… drh 196 ** ability of the [ATTACH DATABASE] SQL command to open a database for writing.
88bc7cf… drh 197 ** This capability is enabled by default. Applications can disable or
746a963… drh 198 ** reenable this capability using the current DBCONFIG option. If
746a963… drh 199 ** this capability is disabled, the [ATTACH] command will still work,
88bc7cf… drh 200 ** but the database will be opened read-only. If this option is disabled,
88bc7cf… drh 201 ** then the ability to create a new database using [ATTACH] is also disabled,
88bc7cf… drh 202 ** regardless of the value of the [SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]
88bc7cf… drh 203 ** option.<p>
88bc7cf… drh 204 ** This option takes two arguments which are an integer and a pointer
88bc7cf… drh 205 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 206 ** leave unchanged the ability to ATTACH another database for writing,
88bc7cf… drh 207 ** respectively. If the second argument is not NULL, then 0 or 1 is written
88bc7cf… drh 208 ** into the integer to which the second argument points, depending on whether
88bc7cf… drh 209 ** the ability to ATTACH a read/write database is enabled or disabled
88bc7cf… drh 210 ** after processing the first argument.
88bc7cf… drh 211 ** </dd>
88bc7cf… drh 212 **
88bc7cf… drh 213 ** [[SQLITE_DBCONFIG_ENABLE_COMMENTS]]
88bc7cf… drh 214 ** <dt>SQLITE_DBCONFIG_ENABLE_COMMENTS</dt>
88bc7cf… drh 215 ** <dd>The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the
88bc7cf… drh 216 ** ability to include comments in SQL text. Comments are enabled by default.
88bc7cf… drh 217 ** An application can disable or reenable comments in SQL text using this
88bc7cf… drh 218 ** DBCONFIG option.<p>
88bc7cf… drh 219 ** This option takes two arguments which are an integer and a pointer
88bc7cf… drh 220 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
88bc7cf… drh 221 ** leave unchanged the ability to use comments in SQL text,
88bc7cf… drh 222 ** respectively. If the second argument is not NULL, then 0 or 1 is written
88bc7cf… drh 223 ** into the integer that the second argument points to depending on if
88bc7cf… drh 224 ** comments are allowed in SQL text after processing the first argument.
88bc7cf… drh 225 ** </dd>
88bc7cf… drh 226 **
b8ab8b3… drh 227 ** [[SQLITE_DBCONFIG_FP_DIGITS]]
b8ab8b3… drh 228 ** <dt>SQLITE_DBCONFIG_FP_DIGITS</dt>
b8ab8b3… drh 229 ** <dd>The SQLITE_DBCONFIG_FP_DIGITS setting is a small integer that determines
b8ab8b3… drh 230 ** the number of significant digits that SQLite will attempt to preserve when
b8ab8b3… drh 231 ** converting floating point numbers (IEEE 754 "doubles") into text. The
b8ab8b3… drh 232 ** default value 17, as of SQLite version 3.52.0. The value was 15 in all
b8ab8b3… drh 233 ** prior versions.<p>
b8ab8b3… drh 234 ** This option takes two arguments which are an integer and a pointer
b8ab8b3… drh 235 ** to an integer. The first argument is a small integer, between 3 and 23, or
b8ab8b3… drh 236 ** zero. The FP_DIGITS setting is changed to that small integer, or left
ad59a04… drh 237 ** unaltered if the first argument is zero or out of range. The second argument
b8ab8b3… drh 238 ** is a pointer to an integer. If the pointer is not NULL, then the value of
b8ab8b3… drh 239 ** the FP_DIGITS setting, after possibly being modified by the first
b8ab8b3… drh 240 ** arguments, is written into the integer to which the second argument points.
b8ab8b3… drh 241 ** </dd>
b8ab8b3… drh 242 **
88bc7cf… drh 243 **
88bc7cf… drh 244 ** [[DBCONFIG arguments]] <h3>Arguments To SQLITE_DBCONFIG Options</h3>
88bc7cf… drh 245 **
935cd45… drh 246 ** <p>Most of the SQLITE_DBCONFIG options take two arguments, so that the
935cd45… drh 247 ** overall call to [sqlite3_db_config()] has a total of four parameters.
ad59a04… drh 248 ** The first argument (the third parameter to sqlite3_db_config()) is
ad59a04… drh 249 ** an integer.
ad59a04… drh 250 ** The second argument is a pointer to an integer. If the first argument is 1,
ad59a04… drh 251 ** then the option becomes enabled. If the first integer argument is 0,
ad59a04… drh 252 ** then the option is disabled.
ad59a04… drh 253 ** If the first argument is -1, then the option setting
88bc7cf… drh 254 ** is unchanged. The second argument, the pointer to an integer, may be NULL.
88bc7cf… drh 255 ** If the second argument is not NULL, then a value of 0 or 1 is written into
88bc7cf… drh 256 ** the integer to which the second argument points, depending on whether the
88bc7cf… drh 257 ** setting is disabled or enabled after applying any changes specified by
88bc7cf… drh 258 ** the first argument.
88bc7cf… drh 259 **
88bc7cf… drh 260 ** <p>While most SQLITE_DBCONFIG options use the argument format
b8ab8b3… drh 261 ** described in the previous paragraph, the [SQLITE_DBCONFIG_MAINDBNAME],
b8ab8b3… drh 262 ** [SQLITE_DBCONFIG_LOOKASIDE], and [SQLITE_DBCONFIG_FP_DIGITS] options
b8ab8b3… drh 263 ** are different. See the documentation of those exceptional options for
b8ab8b3… drh 264 ** details.
88bc7cf… drh 265 #define SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE 1020 /* int int* */
88bc7cf… drh 266 #define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE 1021 /* int int* */
88bc7cf… drh 267 #define SQLITE_DBCONFIG_ENABLE_COMMENTS 1022 /* int int* */
b8ab8b3… drh 268 #define SQLITE_DBCONFIG_FP_DIGITS 1023 /* int int* */
b8ab8b3… drh 269 #define SQLITE_DBCONFIG_MAX 1023 /* Largest DBCONFIG */
3361df8… drh 270 ** SQLite for parsing. ^The sqlite3_complete(X) and sqlite3_complete16(X)
3361df8… drh 271 ** routines return 1 if the input string X appears to be a complete SQL
3361df8… drh 272 ** statement. ^A statement is judged to be
3361df8… drh 273 ** ^The sqlite3_complete(X) and sqlite3_complete16(X) routines return 0
3361df8… drh 274 ** if the statement is incomplete. ^If a memory allocation fails, then
3361df8… drh 275 ** SQLITE_NOMEM is returned.
3361df8… drh 276 ** The [sqlite3_incomplete(X)] routine is similar to [sqlite3_complete(X)]
e6e6a32… drh 277 ** except that sqlite3_incomplete(X) returns SQLITE_OK if the input X is
e6e6a32… drh 278 ** complete, SQLITE_EMPTY if input X consists entirely of whitespace and/or
e6e6a32… drh 279 ** comments, SQLITE_MISUSE if X is a NULL pointer, and some other non-zero
e6e6a32… drh 280 ** value if X is incomplete. The non-zero return from
3361df8… drh 281 ** sqlite3_incomplete(X) contains additional information about what is
e6e6a32… drh 282 ** needed to complete the input X. See the header comment on the
e6e6a32… drh 283 ** implemenation of the sqlite3_incomplete() routine for a full description
e6e6a32… drh 284 ** of its non-zero return values. The sqlite3_incomplete(X) interface
3361df8… drh 285 ** is only available for UTF-8 text.
3361df8… drh 286 **
3361df8… drh 287 ** ^None of these routines do a full parse the SQL statements and thus
3361df8… drh 288 ** will not detect syntactically incorrect SQL. They only determine if
3361df8… drh 289 ** input text has properly terminated comments, string literals, and
3361df8… drh 290 ** quoted identifiers, and if the statement ends with a semicolon.
9b67f46… drh 291 ** The X input to [sqlite3_complete(X)] and [sqlite3_incomplete(X)]
3361df8… drh 292 ** must be a zero-terminated UTF-8 string.
3361df8… drh 293 SQLITE_API sqlite3_int64 sqlite3_incomplete(const char *sql);
d23f1ab… drh 294 ** CAPI3REF: Set the Setlk Timeout
d23f1ab… drh 295 ** METHOD: sqlite3
d23f1ab… drh 296 **
d23f1ab… drh 297 ** This routine is only useful in SQLITE_ENABLE_SETLK_TIMEOUT builds. If
d23f1ab… drh 298 ** the VFS supports blocking locks, it sets the timeout in ms used by
d23f1ab… drh 299 ** eligible locks taken on wal mode databases by the specified database
d23f1ab… drh 300 ** handle. In non-SQLITE_ENABLE_SETLK_TIMEOUT builds, or if the VFS does
d23f1ab… drh 301 ** not support blocking locks, this function is a no-op.
d23f1ab… drh 302 **
d23f1ab… drh 303 ** Passing 0 to this function disables blocking locks altogether. Passing
d23f1ab… drh 304 ** -1 to this function requests that the VFS blocks for a long time -
d23f1ab… drh 305 ** indefinitely if possible. The results of passing any other negative value
d23f1ab… drh 306 ** are undefined.
d23f1ab… drh 307 **
746a963… drh 308 ** Internally, each SQLite database handle stores two timeout values - the
d23f1ab… drh 309 ** busy-timeout (used for rollback mode databases, or if the VFS does not
d23f1ab… drh 310 ** support blocking locks) and the setlk-timeout (used for blocking locks
d23f1ab… drh 311 ** on wal-mode databases). The sqlite3_busy_timeout() method sets both
d23f1ab… drh 312 ** values, this function sets only the setlk-timeout value. Therefore,
d23f1ab… drh 313 ** to configure separate busy-timeout and setlk-timeout values for a single
d23f1ab… drh 314 ** database handle, call sqlite3_busy_timeout() followed by this function.
d23f1ab… drh 315 **
d23f1ab… drh 316 ** Whenever the number of connections to a wal mode database falls from
d23f1ab… drh 317 ** 1 to 0, the last connection takes an exclusive lock on the database,
d23f1ab… drh 318 ** then checkpoints and deletes the wal file. While it is doing this, any
d23f1ab… drh 319 ** new connection that tries to read from the database fails with an
d23f1ab… drh 320 ** SQLITE_BUSY error. Or, if the SQLITE_SETLK_BLOCK_ON_CONNECT flag is
d23f1ab… drh 321 ** passed to this API, the new connection blocks until the exclusive lock
d23f1ab… drh 322 ** has been released.
d23f1ab… drh 323 */
d23f1ab… drh 324 SQLITE_API int sqlite3_setlk_timeout(sqlite3*, int ms, int flags);
d23f1ab… drh 325
d23f1ab… drh 326 /*
d23f1ab… drh 327 ** CAPI3REF: Flags for sqlite3_setlk_timeout()
d23f1ab… drh 328 */
d23f1ab… drh 329 #define SQLITE_SETLK_BLOCK_ON_CONNECT 0x01
d23f1ab… drh 330
d23f1ab… drh 331 /*
746a963… drh 332 ** Definition: A <b>result table</b> is a memory data structure created by the
746a963… drh 333 ** a no-op if it is called with a NULL pointer. Passing a NULL pointer
746a963… drh 334 ** ^If M is the size of the prior allocation, then min(N,M) bytes of the
746a963… drh 335 ** prior allocation are copied into the beginning of the buffer returned
746a963… drh 336 ** ^The sqlite3_realloc64(X,N) interface works the same as
746a963… drh 337 ** but not overhead added by any underlying system library
8594585… drh 338 ** to the callback is an integer [SQLITE_READ | action code] that specifies
8594585… drh 339 ** <h3>Limitations And Caveats</h3><ul>
8594585… drh 340 **
8594585… drh 341 ** <li>The authorizer callback must not do anything that will modify
8594585… drh 342 ** <li>^When [sqlite3_prepare_v2()] is used to prepare a statement, the
8594585… drh 343 ** <li>^The authorizer callback is invoked only during
8594585… drh 344 **
8594585… drh 345 ** <li>Authorizer callbacks for the expressions of a
8594585… drh 346 ** [generated column] are invoked when the schema is parsed (and specifically
8594585… drh 347 ** when the [CREATE TABLE] statement that contains the generated column is
8594585… drh 348 ** parsed) not when the generated column is used in a DML statement.
8594585… drh 349 ** This is deliberate, as one of the purposes of generated columns
8594585… drh 350 ** is to give schema designers the ability to provide gated access
8594585… drh 351 ** to privileged columns and/or functions.
8594585… drh 352 **
8594585… drh 353 ** </ul>
51267fb… drh 354 **
51267fb… drh 355 ** The case of strings in the 3rd through the 6th argument to the
51267fb… drh 356 ** authorization callback is arbitrary. Authorization callbacks
51267fb… drh 357 ** implementations should use [sqlite3_stricmp()] or similar when
51267fb… drh 358 ** doing comparisons against those values.
8594585… drh 359
8594585… drh 360 /*
8594585… drh 361 ** Note: The SQLITE_COPY macro (with value 0) used to be one of the
8594585… drh 362 ** action codes above. That macro has now been repurposed as a possible
8594585… drh 363 ** value to the 3rd argument to sqlite3_result_str().
8594585… drh 364 */
746a963… drh 365 ** <dd>The database is opened with [shared cache] enabled, overriding
746a963… drh 366 ** <dd>The database is opened with [shared cache] disabled, overriding
055e4d0… drh 367 ** exist or ff the value of P is something other than an integer.
b10fbd8… drh 368 ** an array P of N URI Key/Value pairs. The result from
d326547… drh 369 ** <li> sqlite3_db_handle()
07a16b7… drh 370 ** that describes the [result code] E, as UTF-8, or NULL if E is not a
07a16b7… drh 371 ** sqlite3_error_offset() assumes that the input SQL is UTF-8.
3041904… drh 372
3041904… drh 373 /*
4f76459… drh 374 ** CAPI3REF: Set Error Code And Message
3041904… drh 375 ** METHOD: sqlite3
3041904… drh 376 **
3041904… drh 377 ** Set the error code of the database handle passed as the first argument
3041904… drh 378 ** to errcode, and the error message to a copy of nul-terminated string
3041904… drh 379 ** zErrMsg. If zErrMsg is passed NULL, then the error message is set to
3041904… drh 380 ** the default message associated with the supplied error code. Subsequent
3041904… drh 381 ** calls to [sqlite3_errcode()] and [sqlite3_errmsg()] and similar will
3041904… drh 382 ** return the values set by this routine in place of what was previously
3041904… drh 383 ** set by SQLite itself.
3041904… drh 384 **
3041904… drh 385 ** This function returns SQLITE_OK if the error code and error message are
3041904… drh 386 ** successfully set, SQLITE_NOMEM if an OOM occurs, and SQLITE_MISUSE if
3041904… drh 387 ** the database handle is NULL or invalid.
3041904… drh 388 **
3041904… drh 389 ** The error code and message set by this routine remains in effect until
3041904… drh 390 ** they are changed, either by another call to this routine or until they are
3041904… drh 391 ** changed to by SQLite itself to reflect the result of some subsquent
3041904… drh 392 ** API call.
3041904… drh 393 **
3041904… drh 394 ** This function is intended for use by SQLite extensions or wrappers. The
3041904… drh 395 ** idea is that an extension or wrapper can use this routine to set error
3041904… drh 396 ** messages and error codes and thus behave more like a core SQLite
3041904… drh 397 ** feature from the point of view of an application.
3041904… drh 398 */
3041904… drh 399 SQLITE_API int sqlite3_set_errmsg(sqlite3 *db, int errcode, const char *zErrMsg);
07a16b7… drh 400 ** A concise description of these limits follows, and additional information
07a16b7… drh 401 ** is available at [limits | Limits in SQLite].
ba00a43… drh 402 ** <dd>The maximum depth of the parse tree on any expression and
ba00a43… drh 403 ** the maximum nesting depth for subqueries and VIEWs</dd>)^
4f76459… drh 404 **
4f76459… drh 405 ** [[SQLITE_LIMIT_PARSER_DEPTH]] ^(<dt>SQLITE_LIMIT_PARSER_DEPTH</dt>
4f76459… drh 406 ** <dd>The maximum depth of the LALR(1) parser stack used to analyze
4f76459… drh 407 ** input SQL statements.</dd>)^
ba00a43… drh 408 ** <dd>The maximum depth of recursion for triggers, and the maximum
ba00a43… drh 409 ** nesting depth for separate triggers.</dd>)^
896a463… drh 410 **
896a463… drh 411 ** [[SQLITE_LIMIT_SCHEMA]] ^(<dt>SQLITE_LIMIT_SCHEMA</dt>
896a463… drh 412 ** <dd>The maximum number of objects (tables, indexes, triggers, and views)
896a463… drh 413 ** defined by the database schema.</dd>)^
471d617… drh 414 **
471d617… drh 415 ** [[SQLITE_LIMIT_TRIGGER_STEPS]] ^(<dt>SQLITE_LIMIT_TRIGGER_STEPS</dt>
471d617… drh 416 ** <dd>The maximum number of SQL statements that can be contained within
471d617… drh 417 ** a single trigger.</dd>)^
4f76459… drh 418 #define SQLITE_LIMIT_PARSER_DEPTH 12
896a463… drh 419 #define SQLITE_LIMIT_SCHEMA 13
471d617… drh 420 #define SQLITE_LIMIT_TRIGGER_STEPS 14
07a16b7… drh 421 ** These constants define various flags that can be passed into the
b9ecacf… drh 422 **
b9ecacf… drh 423 ** [[SQLITE_PREPARE_FROM_DDL]] <dt>SQLITE_PREPARE_FROM_DDL</dt>
73512f4… drh 424 ** <dd>The SQLITE_PREPARE_FROM_DDL flag causes the SQL compiler to enforce
73512f4… drh 425 ** security constraints that would otherwise only be enforced when parsing
73512f4… drh 426 ** the database schema. In other words, the SQLITE_PREPARE_FROM_DDL flag
73512f4… drh 427 ** causes the SQL compiler to treat the SQL statement being prepared as if
73512f4… drh 428 ** it had come from an attacker. When SQLITE_PREPARE_FROM_DDL is used and
73512f4… drh 429 ** [SQLITE_DBCONFIG_TRUSTED_SCHEMA] is off, SQL functions may only be called
73512f4… drh 430 ** if they are tagged with [SQLITE_INNOCUOUS] and virtual tables may only
73512f4… drh 431 ** be used if they are tagged with [SQLITE_VTAB_INNOCUOUS]. Best practice
73512f4… drh 432 ** is to use the SQLITE_PREPARE_FROM_DDL option when preparing any SQL that
73512f4… drh 433 ** is derived from parts of the database schema. In particular, virtual
73512f4… drh 434 ** table implementations that run SQL statements that are derived from
73512f4… drh 435 ** arguments to their CREATE VIRTUAL TABLE statement should always use
73512f4… drh 436 ** [sqlite3_prepare_v3()] and set the SQLITE_PREPARE_FROM_DDL flag to
73512f4… drh 437 ** prevent bypass of the [SQLITE_DBCONFIG_TRUSTED_SCHEMA] security checks.
b9ecacf… drh 438 #define SQLITE_PREPARE_FROM_DDL 0x20
b9ecacf… drh 439 ** [sqlite3_prepare_v3()] has an extra
17f9878… drh 440 ** [SQLITE_PREPARE_FROM_DDL|"prepFlags" option] that is sometimes
b9ecacf… drh 441 ** needed for special purpose or to pass along security restrictions.
07a16b7… drh 442 ** Note that nByte measures the length of the input in bytes, not
8594585… drh 443 ** For the sqlite3_prepare16() and sqlite3_prepare16_v2() interfaces,
8594585… drh 444 ** the nByte value must be even or undefined behavior can result.
07a16b7… drh 445 ** maximum string length determined by the [SQLITE_LIMIT_LENGTH].
07a16b7… drh 446 ** is always the first parameter to [application-defined SQL functions].
b10fbd8… drh 447 ** literals may be replaced by a [parameter] that matches one of the following
13c221a… drh 448 ** either UTF8 if the sixth parameter is SQLITE_UTF8 or SQLITE_UTF8_ZT,
13c221a… drh 449 ** or UTF16 otherwise.
b10fbd8… drh 450 ** found in the first character, which is removed, or in the absence of a BOM
b10fbd8… drh 451 ** terminated. If any NUL characters occur at byte offsets less than
13c221a… drh 452 ** ^The sixth argument (the E argument)
13c221a… drh 453 ** to sqlite3_bind_text64(S,K,Z,N,D,E) must be one of
13c221a… drh 454 ** [SQLITE_UTF8], [SQLITE_UTF8_ZT], [SQLITE_UTF16], [SQLITE_UTF16BE],
13c221a… drh 455 ** or [SQLITE_UTF16LE] to specify the encoding of the text in the
13c221a… drh 456 ** third parameter, Z. The special value [SQLITE_UTF8_ZT] means that the
13c221a… drh 457 ** string argument is both UTF-8 encoded and is zero-terminated. In other
13c221a… drh 458 ** words, SQLITE_UTF8_ZT means that the Z array is allocated to hold at
13c221a… drh 459 ** least N+1 bytes and that the Z&#91;N&#93; byte is zero. If
13c221a… drh 460 ** the E argument to sqlite3_bind_text64(S,K,Z,N,D,E) is not one of the
92871e0… drh 461 ** P, even if the call to sqlite3_bind_pointer() fails. Due to a
92871e0… drh 462 ** historical design quirk, results are undefined if D is
92871e0… drh 463 ** SQLITE_TRANSIENT. The T parameter should be a static string,
92871e0… drh 464 ** preferably a string literal. The sqlite3_bind_pointer() routine is
92871e0… drh 465 ** part of the [pointer passing interface] added for SQLite 3.20.0.
b10fbd8… drh 466 ** table column that is the origin of a particular result column in a
8594585… drh 467 ** [SQLITE_MISUSE] means that this routine was called inappropriately.
2a04c64… drh 468 ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1]),
07a16b7… drh 469 ** or if the statement has never been evaluated, then sqlite3_finalize() returns
b10fbd8… drh 470 ** used inside of triggers, views, CHECK constraints, or other elements of
b10fbd8… drh 471 ** the database schema. This flag is especially recommended for SQL
b10fbd8… drh 472 ** sqlite3_create_window_function() is not NULL, then it is the destructor for
07a16b7… drh 473 ** These constants define integer codes that represent the various
13c221a… drh 474 **
13c221a… drh 475 ** <dl>
13c221a… drh 476 ** [[SQLITE_UTF8]] <dt>SQLITE_UTF8</dt><dd>Text is encoding as UTF-8</dd>
13c221a… drh 477 **
13c221a… drh 478 ** [[SQLITE_UTF16LE]] <dt>SQLITE_UTF16LE</dt><dd>Text is encoding as UTF-16
13c221a… drh 479 ** with each code point being expressed "little endian" - the least significant
13c221a… drh 480 ** byte first. This is the usual encoding, for example on Windows.</dd>
13c221a… drh 481 **
13c221a… drh 482 ** [[SQLITE_UTF16BE]] <dt>SQLITE_UTF16BE</dt><dd>Text is encoding as UTF-16
13c221a… drh 483 ** with each code point being expressed "big endian" - the most significant
13c221a… drh 484 ** byte first. This encoding is less common, but is still sometimes seen,
13c221a… drh 485 ** specially on older systems.
13c221a… drh 486 **
13c221a… drh 487 ** [[SQLITE_UTF16]] <dt>SQLITE_UTF16</dt><dd>Text is encoding as UTF-16
13c221a… drh 488 ** with each code point being expressed either little endian or as big
13c221a… drh 489 ** endian, according to the native endianness of the host computer.
13c221a… drh 490 **
13c221a… drh 491 ** [[SQLITE_ANY]] <dt>SQLITE_ANY</dt><dd>This encoding value may only be used
13c221a… drh 492 ** to declare the preferred text for [application-defined SQL functions]
13c221a… drh 493 ** created using [sqlite3_create_function()] and similar. If the preferred
13c221a… drh 494 ** encoding (the 4th parameter to sqlite3_create_function() - the eTextRep
13c221a… drh 495 ** parameter) is SQLITE_ANY, that indicates that the function does not have
13c221a… drh 496 ** a preference regarding the text encoding of its parameters and can take
13c221a… drh 497 ** any text encoding that the SQLite core find convenient to supply. This
13c221a… drh 498 ** option is deprecated. Please do not use it in new applications.
13c221a… drh 499 **
13c221a… drh 500 ** [[SQLITE_UTF16_ALIGNED]] <dt>SQLITE_UTF16_ALIGNED</dt><dd>This encoding
13c221a… drh 501 ** value may be used as the 3rd parameter (the eTextRep parameter) to
13c221a… drh 502 ** [sqlite3_create_collation()] and similar. This encoding value means
13c221a… drh 503 ** that the application-defined collating sequence created expects its
13c221a… drh 504 ** input strings to be in UTF16 in native byte order, and that the start
13c221a… drh 505 ** of the strings must be aligned to a 2-byte boundary.
13c221a… drh 506 **
13c221a… drh 507 ** [[SQLITE_UTF8_ZT]] <dt>SQLITE_UTF8_ZT</dt><dd>This option can only be
ad59a04… drh 508 ** used to specify the text encoding to strings input to
ad59a04… drh 509 ** [sqlite3_result_text64()] and [sqlite3_bind_text64()].
ad59a04… drh 510 ** The SQLITE_UTF8_ZT encoding means that the input string (call it "z")
13c221a… drh 511 ** is UTF-8 encoded and that it is zero-terminated. If the length parameter
13c221a… drh 512 ** (call it "n") is non-negative, this encoding option means that the caller
13c221a… drh 513 ** guarantees that z array contains at least n+1 bytes and that the z&#91;n&#93;
13c221a… drh 514 ** byte has a value of zero.
13c221a… drh 515 ** This option gives the same output as SQLITE_UTF8, but can be more efficient
13c221a… drh 516 ** by avoiding the need to make a copy of the input string, in some cases.
13c221a… drh 517 ** However, if z is allocated to hold fewer than n+1 bytes or if the
13c221a… drh 518 ** z&#91;n&#93; byte is not zero, undefined behavior may result.
13c221a… drh 519 ** </dl>
13c221a… drh 520 #define SQLITE_UTF8_ZT 16 /* Zero-terminated UTF8 */
07a16b7… drh 521 ** might become a no-op if the function is used as a term in an
07a16b7… drh 522 ** the prior [xColumn] method call that was invoked to extract
ad59a04… drh 523 ** fail if an out-of-memory error occurs while trying to do a
ad59a04… drh 524 ** UTF8&rarr;UTF16 or UTF16&rarr;UTF8 conversion.
ad59a04… drh 525 ** If the input sqlite3_value was not obtained from [sqlite3_value_dup()],
ad59a04… drh 526 ** then valid SQL NULL returns can also be distinguished from
ad59a04… drh 527 ** out-of-memory errors after extracting the value
ad59a04… drh 528 ** by invoking the [sqlite3_errcode()] immediately after the suspicious
ad59a04… drh 529 ** If the input sqlite3_value was obtained from sqlite3_value_dup() then
ad59a04… drh 530 ** it is disconnected from the database connection and so sqlite3_errcode()
ad59a04… drh 531 ** will not work.
ad59a04… drh 532 ** In that case, the only way to distinguish an out-of-memory
ad59a04… drh 533 ** condition from a true SQL NULL is to invoke sqlite3_value_type() on the
ad59a04… drh 534 ** input to see if it is NULL prior to trying to extract the value.
ad59a04… drh 535 ** [sqlite3_value_text(X)], [sqlite3_value_text16(X)],
ad59a04… drh 536 ** [sqlite3_value_text16be(X)],
cdaec3a… drh 537 ** object V and returns a pointer to that copy. ^The [sqlite3_value] returned
cdaec3a… drh 538 ** determined by the N parameter on the first successful call. Changing the
ad59a04… drh 539 ** expression can be stored as auxiliary data associated with the pattern
ad59a04… drh 540 ** string. Then as long as the pattern string remains the same,
ad59a04… drh 541 ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary
ad59a04… drh 542 ** data associated by the sqlite3_set_auxdata(C,N,P,X) function with the
ad59a04… drh 543 ** Nth argument value to the application-defined function. ^N is zero
ad59a04… drh 544 ** for the left-most function argument. ^If there is no auxiliary data
ad59a04… drh 545 ** associated with the function argument, the sqlite3_get_auxdata(C,N)
ad59a04… drh 546 ** interface returns a NULL pointer.
dc45faa… drh 547 ** It returns 0 on success and SQLITE_NOMEM on allocation failure.
2b2530d… drh 548 ** single database connection. However, the current implementation stores
2b2530d… drh 549 ** the content on a linked list. Insert and retrieval performance will
2b2530d… drh 550 ** be proportional to the number of entries. The design use case, and
2b2530d… drh 551 ** the use case for which the implementation is optimized, is
2b2530d… drh 552 ** that an application will store only small number of client data names,
2b2530d… drh 553 ** typically just one or two. This interface is not intended to be a
2b2530d… drh 554 ** generalized key/value store for thousands or millions of keys. It
2b2530d… drh 555 ** will work for that, but performance might be disappointing.
cdaec3a… drh 556 ** attacker to invoke them. Any agent that can invoke these interfaces
896a463… drh 557 ** a BLOB containing all zero bytes and N bytes in size. The
896a463… drh 558 ** zeroblob64(C,N) interface returns a [result code], which is normally
896a463… drh 559 ** [SQLITE_OK] but might be some other value if the requested operation
896a463… drh 560 ** could not be complete, for example if insufficient memory is available
896a463… drh 561 ** or if the value of N is out of range.
13c221a… drh 562 ** ^The sqlite3_result_text64(C,Z,N,D,E) interface sets the return value of an
13c221a… drh 563 ** specified the E parameter, which must be one
13c221a… drh 564 ** of [SQLITE_UTF8], [SQLITE_UTF8_ZT], [SQLITE_UTF16], [SQLITE_UTF16BE],
13c221a… drh 565 ** or [SQLITE_UTF16LE]. ^The special value [SQLITE_UTF8_ZT] means that
13c221a… drh 566 ** the result text is both UTF-8 and zero-terminated. In other words,
17f9878… drh 567 ** SQLITE_UTF8_ZT means that the Z array holds at least N+1 bytes and that
13c221a… drh 568 ** the Z&#91;N&#93; is zero.
cdaec3a… drh 569 ** appear if the string were NUL terminated. If any NUL characters occur
cdaec3a… drh 570 ** If these routines are called from within a different thread
13c221a… drh 571 SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n,
cdaec3a… drh 572 ** for the N-th database on database connection D, or a NULL pointer if N is
cdaec3a… drh 573 ** will be advanced to SQLITE_TXN_WRITE if any changes occur and there are
cdaec3a… drh 574 ** SQLITE_TXN_NONE at the next [ROLLBACK] or [COMMIT].</dd>
2a04c64… drh 575 ** ^The update hook is disabled by invoking sqlite3_update_hook()
2a04c64… drh 576 ** with a NULL pointer as the second parameter.
cdaec3a… drh 577 ** used by all database connections within a single process.
cdaec3a… drh 578 ** change in future releases of SQLite.
5f65ed5… drh 579 ** with various operating-system specific filename extensions added.
5f65ed5… drh 580 ** If that does not work, it tries names of the form "sqlite3_X_init"
5f65ed5… drh 581 ** where X consists of the lower-case equivalent of all ASCII alphabetic
5f65ed5… drh 582 ** characters or all ASCII alphanumeric characters in the filename from
5f65ed5… drh 583 ** the last "/" to the first following "." and omitting any initial "lib".)^
b10fbd8… drh 584 ** entry point were as follows:
3361df8… drh 585 ** &nbsp; char **pzErrMsg,
cdaec3a… drh 586 ** checked separately in byte code. If the omit flag is changed to true, then
cdaec3a… drh 587 ** output to show the idxNum as hex instead of as decimal. Another flag is
b10fbd8… drh 588 ** when a new virtual table is being created or reinitialized.
b10fbd8… drh 589 ** on *ppBlob after this function returns.
b10fbd8… drh 590 ** incremental blob I/O routines can only read or overwrite existing
cdaec3a… drh 591 ** mutex. The argument to sqlite3_mutex_alloc() must be one of these
cdaec3a… drh 592 ** ^This interface returns a pointer to the [sqlite3_mutex] object that
a10f931… drh 593 #define SQLITE_TESTCTRL_ATOF 34
cdaec3a… drh 594 ** recognized by SQLite. Applications can use these routines to determine
8594585… drh 595 ** <li> The sqlite3_str object is destroyed and the string it created
8594585… drh 596 ** is returned using [sqlite3_str_finish()] or [sqlite3_result_str()].
d326547… drh 597 ** [sqlite3_str_finish(X)] interface might also return a NULL pointer if the
4f76459… drh 598 **
4f76459… drh 599 ** ^The [sqlite3_str_free(X)] interface destroys both the sqlite3_str object
4f76459… drh 600 ** X and the string content it contains. Calling sqlite3_str_free(X) is
4f76459… drh 601 ** the equivalent of calling [sqlite3_free](sqlite3_str_finish(X)).
4f76459… drh 602 SQLITE_API void sqlite3_str_free(sqlite3_str*);
8594585… drh 603
8594585… drh 604 /*
8594585… drh 605 ** CAPI3REF: Return A Dynamic String From an SQL Function
8594585… drh 606 **
8594585… drh 607 ** The [sqlite3_result_str(C,S,F)] interface causes the
8594585… drh 608 ** [sqlite3_str|dynamic string] S to become the return value for the
8594585… drh 609 ** application-defined function or virtual table that uses
8594585… drh 610 ** [sqlite3_context] C. The F flag can be one of [SQLITE_COPY]
8594585… drh 611 ** or [SQLITE_XFER] or [SQLITE_FINISH].
8594585… drh 612 **
8594585… drh 613 ** If the dynamic string is invalid or incomplete due to an out-of-memory
8594585… drh 614 ** or string-too-large error, then this routine transfers that error
8594585… drh 615 ** over to the SQL function.
8594585… drh 616 **
8594585… drh 617 ** If the F argument is SQLITE_COPY, then a copy of the dynamic string
8594585… drh 618 ** content is made and the dynamic string object is unchanged.
8594585… drh 619 ** If the F argument is SQLITE_XFER, then ownership of the content
8594585… drh 620 ** in the dynamic is transferred to the SQL function (via a pointer copy
8594585… drh 621 ** rather than a string copy) and the dynamic string is reset to an
8594585… drh 622 ** empty string. The SQLITE_FINISH value for F works like SQLITE_RESET
8594585… drh 623 ** except that it also invokes the [sqlite3_str_free(S)] destructor
8594585… drh 624 ** on the dynamic string object.
8594585… drh 625 */
8594585… drh 626 SQLITE_API void sqlite3_result_str(sqlite3_context*, sqlite3_str*, int);
8594585… drh 627
8594585… drh 628 /*
8594585… drh 629 ** CAPI3REF: Control Flags For sqlite3_result_str()
8594585… drh 630 **
8594585… drh 631 ** The following integers can be used as the third "F" argument
8594585… drh 632 ** to [sqlite3_result_str(C,S,F)].
8594585… drh 633 */
8594585… drh 634 #define SQLITE_COPY 0 /* Results copied. Dynamic string unchanged */
8594585… drh 635 #define SQLITE_XFER 1 /* Results transfered. Dynamic string reset */
8594585… drh 636 #define SQLITE_FINISH 2 /* Like SQLITE_XFER, plus dynamic string freed */
17f9878… drh 637
17f9878… drh 638 /*
4f76459… drh 639 ** These interfaces add or remove content to an sqlite3_str object
4f76459… drh 640 ** previously obtained from [sqlite3_str_new()].
4f76459… drh 641 ** ^The [sqlite3_str_truncate(X,N)] method changes the length of the string
17f9878… drh 642 ** under construction to be N bytes or less. This routine is a no-op if
4f76459… drh 643 ** N is negative or if the string is already N bytes or smaller in size.
4f76459… drh 644 **
4f76459… drh 645 SQLITE_API void sqlite3_str_truncate(sqlite3_str*,int N);
cdaec3a… drh 646 ** [sqlite3_str] object. Applications must not use the pointer returned by
cdaec3a… drh 647 ** were too large (they were larger than the "sz" parameter to
3c639f7… drh 648 ** ^The sqlite3_db_status64(D,O,C,H,R) routine works exactly the same
3c639f7… drh 649 ** way as sqlite3_db_status(D,O,C,H,R) routine except that the C and H
3c639f7… drh 650 ** parameters are pointer to 64-bit integers (type: sqlite3_int64) instead
3c639f7… drh 651 ** of pointers to 32-bit integers, which allows larger status values
3c639f7… drh 652 ** to be returned. If a status value exceeds 2,147,483,647 then
3c639f7… drh 653 ** sqlite3_db_status() will truncate the value whereas sqlite3_db_status64()
3c639f7… drh 654 ** will return the full value.
3c639f7… drh 655 **
3c639f7… drh 656 SQLITE_API int sqlite3_db_status64(sqlite3*,int,sqlite3_int64*,sqlite3_int64*,int);
cdaec3a… drh 657 ** the current value is always zero.</dd>)^
cdaec3a… drh 658 ** <dd>This parameter returns the number of malloc attempts that might have
cdaec3a… drh 659 ** the current value is always zero.</dd>)^
cdaec3a… drh 660 ** <dd>This parameter returns the number of malloc attempts that might have
cdaec3a… drh 661 ** the current value is always zero.</dd>)^
cdaec3a… drh 662 ** </dd>
cdaec3a… drh 663 ** value as DBSTATUS_CACHE_USED. Or, if one or more of the pager caches are
cdaec3a… drh 664 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.</dd>
cdaec3a… drh 665 ** </dd>
3c639f7… drh 666 ** <p>
3c639f7… drh 667 ** ^(There is overlap between the quantities measured by this parameter
3c639f7… drh 668 ** (SQLITE_DBSTATUS_CACHE_WRITE) and SQLITE_DBSTATUS_TEMPBUF_SPILL.
3c639f7… drh 669 ** Resetting one will reduce the other.)^
cdaec3a… drh 670 ** additional overhead. This parameter can be used to help identify
3c639f7… drh 671 **
3c639f7… drh 672 ** [[SQLITE_DBSTATUS_TEMPBUF_SPILL] ^(<dt>SQLITE_DBSTATUS_TEMPBUF_SPILL</dt>
3c639f7… drh 673 ** <dd>^(This parameter returns the number of bytes written to temporary
3c639f7… drh 674 ** files on disk that could have been kept in memory had sufficient memory
3c639f7… drh 675 ** been available. This value includes writes to intermediate tables that
3c639f7… drh 676 ** are part of complex queries, external sorts that spill to disk, and
3c639f7… drh 677 ** writes to TEMP tables.)^
3c639f7… drh 678 ** ^The highwater mark is always 0.
3c639f7… drh 679 ** <p>
3c639f7… drh 680 ** ^(There is overlap between the quantities measured by this parameter
3c639f7… drh 681 ** (SQLITE_DBSTATUS_TEMPBUF_SPILL) and SQLITE_DBSTATUS_CACHE_WRITE.
3c639f7… drh 682 ** Resetting one will reduce the other.)^
3c639f7… drh 683 #define SQLITE_DBSTATUS_TEMPBUF_SPILL 13
3c639f7… drh 684 #define SQLITE_DBSTATUS_MAX 13 /* Largest defined DBSTATUS */
bcbf150… drh 685 ** improve performance through careful use of indices.</dd>
bcbf150… drh 686 ** improve performance by adding permanent indices that do not
bcbf150… drh 687 ** then the value returned by this statement status code is undefined.</dd>
bcbf150… drh 688 ** [bound parameters] that might affect the query plan.</dd>
bcbf150… drh 689 ** cycle.</dd>
bcbf150… drh 690 ** had to be processed as normal.</dd>
bcbf150… drh 691 ** be allocated by the cache. ^szPage will always be a power of two. ^The
bcbf150… drh 692 ** associated with each page cache entry. ^The szExtra parameter will be
bcbf150… drh 693 ** does not have to do anything special based upon the value of bPurgeable;
bcbf150… drh 694 ** ^Hence, a cache created with bPurgeable set to false will
bcbf150… drh 695 ** suggested maximum cache-size (number of pages stored) for the cache
bcbf150… drh 696 ** parameter to help it determine what action to take:
bcbf150… drh 697 ** <tr><td> 1 <td> Allocate a new page if it is easy and convenient to do so.
bcbf150… drh 698 ** zero, then the page may be discarded or retained at the discretion of the
bcbf150… drh 699 ** of these pages are pinned, they become implicitly unpinned, meaning that
b10fbd8… drh 700 ** database is modified by using the same database connection as is used
b10fbd8… drh 701 ** sqlite3_backup_step() errors occurred, regardless of whether or not
bcbf150… drh 702 ** when the blocking connection's current transaction is concluded. ^The
bcbf150… drh 703 ** unlock-notify callback is canceled. ^The blocked connection's
dc45faa… drh 704 ** ^The callback function should normally return [SQLITE_OK]. ^If an error
dc45faa… drh 705 ** ^A single database handle may have at most a single write-ahead log
dc45faa… drh 706 ** callback registered at one time. ^Calling [sqlite3_wal_hook()]
dc45faa… drh 707 ** replaces the default behavior or previously registered write-ahead
dc45faa… drh 708 ** log callback.
dc45faa… drh 709 **
dc45faa… drh 710 ** ^The return value is a copy of the third parameter from the
dc45faa… drh 711 ** previous call, if any, or 0.
dc45faa… drh 712 **
dc45faa… drh 713 ** ^The [sqlite3_wal_autocheckpoint()] interface and the
dc45faa… drh 714 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and
dc45faa… drh 715 ** will overwrite any prior [sqlite3_wal_hook()] settings.
dc45faa… drh 716 **
dc45faa… drh 717 ** ^If a write-ahead log callback is set using this function then
dc45faa… drh 718 ** [sqlite3_wal_checkpoint_v2()] or [PRAGMA wal_checkpoint]
dc45faa… drh 719 ** should be invoked periodically to keep the write-ahead log file
dc45faa… drh 720 ** from growing without bound.
dc45faa… drh 721 **
dc45faa… drh 722 ** ^Passing a NULL pointer for the callback disables automatic
dc45faa… drh 723 ** checkpointing entirely. To re-enable the default behavior, call
dc45faa… drh 724 ** sqlite3_wal_autocheckpoint(db,1000) or use [PRAGMA wal_checkpoint].
dc45faa… drh 725 ** a negative value as the N parameter disables automatic
dc45faa… drh 726 ** pages.
dc45faa… drh 727 **
dc45faa… drh 728 ** ^The use of this interface is only necessary if the default setting
dc45faa… drh 729 ** is found to be suboptimal for a particular application.
dc45faa… drh 730 **
dc45faa… drh 731 ** <dt>SQLITE_CHECKPOINT_NOOP<dd>
dc45faa… drh 732 ** ^This mode always checkpoints zero frames. The only reason to invoke
dc45faa… drh 733 ** a NOOP checkpoint is to access the values returned by
dc45faa… drh 734 ** sqlite3_wal_checkpoint_v2() via output parameters *pnLog and *pnCkpt.
dc45faa… drh 735 #define SQLITE_CHECKPOINT_NOOP -1 /* Do no work at all */
bcbf150… drh 736 ** specified as part of the user's SQL statement, regardless of the actual
bcbf150… drh 737 ** [xConnect] or [xCreate] methods of a [virtual table] implementation
ad59a04… drh 738 ** <td valign="top">Rows with the same value in all aOrderBy columns are
ad59a04… drh 739 ** adjacent
ad59a04… drh 740 ** values are the same value for sorting purposes, two NULL values are
ad59a04… drh 741 ** considered to be the same. In other words, the comparison operator is "IS"
bcbf150… drh 742 ** "orderByConsumed" flag is unset, the query planner will add extra
bcbf150… drh 743 ** processing using the [sqlite3_vtab_in()] interface in the
4f76459… drh 744 ** &nbsp; if( rc!=SQLITE_DONE ){
bcbf150… drh 745 ** can return a result code other than SQLITE_OK or SQLITE_NOTFOUND if
bcbf150… drh 746 ** inform a [virtual table] implementation of the [ON CONFLICT] mode
bcbf150… drh 747 ** for the SQL statement being evaluated.
bcbf150… drh 748 ** iteration of the X-th loop. If the query planner's estimate was accurate,
bcbf150… drh 749 ** be the NLOOP value for the current loop.</dd>
bcbf150… drh 750 ** used for the X-th loop.</dd>
bcbf150… drh 751 ** description for the X-th loop.</dd>
bcbf150… drh 752 ** column of an [EXPLAIN QUERY PLAN] query.</dd>
bcbf150… drh 753 ** id of the parent of the current query element, if applicable, or
bcbf150… drh 754 ** returned in the second column of an [EXPLAIN QUERY PLAN] query.</dd>
bcbf150… drh 755 ** set to -1.</dd>
4f76459… drh 756 ** one flag is defined - [SQLITE_SCANSTAT_COMPLEX]. If SQLITE_SCANSTAT_COMPLEX
4f76459… drh 757 ** of a query plan that are reported by "[EXPLAIN QUERY PLAN]" output. If
bcbf150… drh 758 ** for. Query elements are numbered starting from zero. A value of -1 may
bcbf150… drh 759 ** retrieve statistics for the entire query. ^If idx is out of range
4f76459… drh 760 ** See also: [sqlite3_stmt_scanstatus_reset()] and the
17f9878… drh 761 ** [nexec and ncycle] columns of the [bytecode virtual table].
b10fbd8… drh 762 ** [sqlite3_db_cacheflush(D)] interface is invoked, any dirty
bcbf150… drh 763 ** the pre-update hook is invoked with SQLITE_DELETE, because
bcbf150… drh 764 ** the new values are not yet available. In this case, when a
dc45faa… drh 765 SQLITE_API int sqlite3_snapshot_get(
dc45faa… drh 766 SQLITE_API int sqlite3_snapshot_open(
dc45faa… drh 767 SQLITE_API void sqlite3_snapshot_free(sqlite3_snapshot*);
dc45faa… drh 768 SQLITE_API int sqlite3_snapshot_cmp(
dc45faa… drh 769 SQLITE_API int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
3ce667a… drh 770 ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to
3ce667a… drh 771 ** memory that is a serialization of the S database on
3ce667a… drh 772 ** [database connection] D. If S is a NULL pointer, the main database is used.
bcbf150… drh 773 ** to disk if that database were backed up to disk.
bcbf150… drh 774 ** is currently using for that database, or NULL if no such contiguous
dc45faa… drh 775 ** reopen S as an in-memory database based on the serialization
dc45faa… drh 776 ** contained in P. If S is a NULL pointer, the main database is
dc45faa… drh 777 ** used. The serialized database P is N bytes in size. M is the size
dc45faa… drh 778 ** of the buffer P, which might be larger than N. If M is larger than
dc45faa… drh 779 ** N, and the SQLITE_DESERIALIZE_READONLY bit is not set in F, then
ba00a43… drh 780 ** SQLite is permitted to add content to the in-memory database, in
ba00a43… drh 781 ** page-sized chunks, as long as the total size does not exceed M bytes.
ba00a43… drh 782 **
ba00a43… drh 783 ** The parameter M must be greater than or equal to N. Ideally, M
ba00a43… drh 784 ** should have a value which is N+(512&times;K)+20 where K determines how
ba00a43… drh 785 ** must extra space is available to hold new content as the database
ba00a43… drh 786 ** grows. K can be 0 if the database is read-only.
ba00a43… drh 787 **
ba00a43… drh 788 ** If the database content in P is malformed in a malicious way then
ba00a43… drh 789 ** it is possible that SQLite might try to read a few more than N bytes
ba00a43… drh 790 ** from P. If the veracity of the database content P is uncertain,
ba00a43… drh 791 ** then applications are advised to allocate about 20 extra bytes on
ba00a43… drh 792 ** the end of the P buffer to avoid a memory error.
bcbf150… drh 793 ** It is not possible to deserialize into the TEMP database. If the
bcbf150… drh 794 sqlite3_int64 szDb, /* Number of bytes in the deserialization */
bcbf150… drh 795 ** The following are allowed values for the 6th argument (the F argument) to
70539ee… drh 796
70539ee… drh 797 /*
70539ee… drh 798 ** CAPI3REF: Bind array values to the CARRAY table-valued function
70539ee… drh 799 **
7b0960d… drh 800 ** The sqlite3_carray_bind_v2(S,I,P,N,F,X,D) interface binds an array value to
7b0960d… drh 801 ** parameter that is the first argument of the [carray() table-valued function].
ad59a04… drh 802 ** The S parameter is a pointer to the [prepared statement] that uses the
ad59a04… drh 803 ** carray() functions. I is the parameter index to be bound. I must be the
ad59a04… drh 804 ** index of the parameter that is the first argument to the carray()
ad59a04… drh 805 ** table-valued function. P is a pointer to the array to be bound, and N
ad59a04… drh 806 ** is the number of elements in the array. The F argument is one of
ad59a04… drh 807 ** constants [SQLITE_CARRAY_INT32], [SQLITE_CARRAY_INT64],
ad59a04… drh 808 ** [SQLITE_CARRAY_DOUBLE], [SQLITE_CARRAY_TEXT],
7b0960d… drh 809 ** or [SQLITE_CARRAY_BLOB] to indicate the datatype of the array P.
7b0960d… drh 810 **
7b0960d… drh 811 ** If the X argument is not a NULL pointer or one of the special
7b0960d… drh 812 ** values [SQLITE_STATIC] or [SQLITE_TRANSIENT], then SQLite will invoke
7b0960d… drh 813 ** the function X with argument D when it is finished using the data in P.
7b0960d… drh 814 ** The call to X(D) is a destructor for the array P. The destructor X(D)
17f9878… drh 815 ** is invoked even if the call to sqlite3_carray_bind_v2() fails. If the X
7b0960d… drh 816 ** parameter is the special-case value [SQLITE_STATIC], then SQLite assumes
7b0960d… drh 817 ** that the data static and the destructor is never invoked. If the X
7b0960d… drh 818 ** parameter is the special-case value [SQLITE_TRANSIENT], then
7b0960d… drh 819 ** sqlite3_carray_bind_v2() makes its own private copy of the data prior
7b0960d… drh 820 ** to returning and never invokes the destructor X.
7b0960d… drh 821 **
17f9878… drh 822 ** The sqlite3_carray_bind() function works the same as sqlite3_carray_bind_v2()
7b0960d… drh 823 ** with a D parameter set to P. In other words,
7b0960d… drh 824 ** sqlite3_carray_bind(S,I,P,N,F,X) is same as
17f9878… drh 825 ** sqlite3_carray_bind_v2(S,I,P,N,F,X,P).
70539ee… drh 826 */
7b0960d… drh 827 SQLITE_API int sqlite3_carray_bind_v2(
7b0960d… drh 828 sqlite3_stmt *pStmt, /* Statement to be bound */
7b0960d… drh 829 int i, /* Parameter index */
7b0960d… drh 830 void *aData, /* Pointer to array data */
7b0960d… drh 831 int nData, /* Number of data elements */
7b0960d… drh 832 int mFlags, /* CARRAY flags */
7b0960d… drh 833 void (*xDel)(void*), /* Destructor for aData */
7b0960d… drh 834 void *pDel /* Optional argument to xDel() */
7b0960d… drh 835 );
92871e0… drh 836 SQLITE_API int sqlite3_carray_bind(
70539ee… drh 837 sqlite3_stmt *pStmt, /* Statement to be bound */
70539ee… drh 838 int i, /* Parameter index */
70539ee… drh 839 void *aData, /* Pointer to array data */
70539ee… drh 840 int nData, /* Number of data elements */
70539ee… drh 841 int mFlags, /* CARRAY flags */
70539ee… drh 842 void (*xDel)(void*) /* Destructor for aData */
70539ee… drh 843 );
70539ee… drh 844
70539ee… drh 845 /*
92871e0… drh 846 ** CAPI3REF: Datatypes for the CARRAY table-valued function
70539ee… drh 847 **
70539ee… drh 848 ** The fifth argument to the [sqlite3_carray_bind()] interface musts be
70539ee… drh 849 ** one of the following constants, to specify the datatype of the array
70539ee… drh 850 ** that is being bound into the [carray table-valued function].
70539ee… drh 851 */
70539ee… drh 852 #define SQLITE_CARRAY_INT32 0 /* Data is 32-bit signed integers */
70539ee… drh 853 #define SQLITE_CARRAY_INT64 1 /* Data is 64-bit signed integers */
70539ee… drh 854 #define SQLITE_CARRAY_DOUBLE 2 /* Data is doubles */
70539ee… drh 855 #define SQLITE_CARRAY_TEXT 3 /* Data is char* */
70539ee… drh 856 #define SQLITE_CARRAY_BLOB 4 /* Data is struct iovec */
70539ee… drh 857
70539ee… drh 858 /*
70539ee… drh 859 ** Versions of the above #defines that omit the initial SQLITE_, for
70539ee… drh 860 ** legacy compatibility.
70539ee… drh 861 */
70539ee… drh 862 #define CARRAY_INT32 0 /* Data is 32-bit signed integers */
70539ee… drh 863 #define CARRAY_INT64 1 /* Data is 64-bit signed integers */
70539ee… drh 864 #define CARRAY_DOUBLE 2 /* Data is doubles */
70539ee… drh 865 #define CARRAY_TEXT 3 /* Data is char* */
70539ee… drh 866 #define CARRAY_BLOB 4 /* Data is struct iovec */
22b3844… drh 867 ** Or, if one field of a row is updated while a session is enabled, and
22b3844… drh 868 ** then another field of the same row is updated while the session is disabled,
22b3844… drh 869 ** the resulting changeset will contain an UPDATE change that updates both
22b3844… drh 870 ** fields.
d14a780… drh 871 ** Unless the call to this function is a no-op as described above, it is an
d14a780… drh 872 ** error if database zFrom does not exist or does not contain the required
d14a780… drh 873 ** compatible table.
f40c00b… drh 874 ** <dt>SQLITE_CHANGESETSTART_INVERT <dd>
3041904… drh 875 ** All changes made by these functions are enclosed in a savepoint transaction.
3041904… drh 876 ** If any other error (aside from a constraint failure when attempting to
3041904… drh 877 ** write to the target database) occurs, then the savepoint transaction is
3041904… drh 878 ** rolled back, restoring the target database to its original state, and an
3041904… drh 879 ** SQLite error code returned. Additionally, starting with version 3.51.0,
3041904… drh 880 ** an error code and error message that may be accessed using the
3041904… drh 881 ** [sqlite3_errcode()] and [sqlite3_errmsg()] APIs are left in the database
3041904… drh 882 ** handle.
3041904… drh 883 **
0185597… drh 884 ** callback". This may be passed NULL, in which case all changes in the
0185597… drh 885 ** changeset are applied to the database. For sqlite3changeset_apply() and
0185597… drh 886 ** sqlite3_changeset_apply_v2(), if it is not NULL, then it is invoked once
0185597… drh 887 ** for each table affected by at least one change in the changeset. In this
0185597… drh 888 ** case the table name is passed as the second argument, and a copy of
0185597… drh 889 ** the context pointer passed as the sixth argument to apply() or apply_v2()
0185597… drh 890 ** as the first. If the "filter callback" returns zero, then no attempt is
0185597… drh 891 ** made to apply any changes to the table. Otherwise, if the return value is
0185597… drh 892 ** non-zero, all changes related to the table are attempted.
0185597… drh 893 **
0185597… drh 894 ** For sqlite3_changeset_apply_v3(), the xFilter callback is invoked once
0185597… drh 895 ** per change. The second argument in this case is an sqlite3_changeset_iter
0185597… drh 896 ** that may be queried using the usual APIs for the details of the current
0185597… drh 897 ** change. If the "filter callback" returns zero in this case, then no attempt
0185597… drh 898 ** is made to apply the current change. If it returns non-zero, the change
0185597… drh 899 ** is applied.
0185597… drh 900 ** to modify the table contents according to each UPDATE, INSERT or DELETE
0185597… drh 901 ** change that is not excluded by a filter callback. If a change cannot be
0185597… drh 902 ** applied cleanly, the conflict handler function passed as the fifth argument
0185597… drh 903 ** to sqlite3changeset_apply() may be invoked. A description of exactly when
0185597… drh 904 ** the conflict handler is invoked for each type of change is below.
0185597… drh 905 ),
0185597… drh 906 int(*xConflict)(
0185597… drh 907 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 908 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
0185597… drh 909 sqlite3_changeset_iter *p /* Handle describing change and conflict */
0185597… drh 910 ),
0185597… drh 911 void *pCtx, /* First argument passed to xConflict */
0185597… drh 912 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
0185597… drh 913 int flags /* SESSION_CHANGESETAPPLY_* flags */
0185597… drh 914 );
0185597… drh 915 SQLITE_API int sqlite3changeset_apply_v3(
0185597… drh 916 sqlite3 *db, /* Apply change to "main" db of this handle */
0185597… drh 917 int nChangeset, /* Size of changeset in bytes */
0185597… drh 918 void *pChangeset, /* Changeset blob */
0185597… drh 919 int(*xFilter)(
0185597… drh 920 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 921 sqlite3_changeset_iter *p /* Handle describing change */
3b2d0c9… drh 922 **
3b2d0c9… drh 923 ** <dt>SQLITE_CHANGESETAPPLY_NOUPDATELOOP <dd>
3b2d0c9… drh 924 ** Sometimes, a changeset contains two or more update statements such that
3b2d0c9… drh 925 ** although after applying all updates the database will contain no
3b2d0c9… drh 926 ** constraint violations, no single update can be applied before the others.
3b2d0c9… drh 927 ** The simplest example of this is a pair of UPDATEs that have "swapped"
3b2d0c9… drh 928 ** two column values with a UNIQUE constraint.
3b2d0c9… drh 929 ** <p>
3b2d0c9… drh 930 ** Usually, sqlite3changeset_apply() and similar functions work hard to try
3b2d0c9… drh 931 ** to find a way to apply such a changeset. However, if this flag is set,
3b2d0c9… drh 932 ** then all such updates are considered CONSTRAINT conflicts.
3b2d0c9… drh 933 #define SQLITE_CHANGESETAPPLY_NOUPDATELOOP 0x0010
0185597… drh 934 SQLITE_API int sqlite3changeset_apply_v3_strm(
0185597… drh 935 sqlite3 *db, /* Apply change to "main" db of this handle */
0185597… drh 936 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
0185597… drh 937 void *pIn, /* First arg for xInput */
0185597… drh 938 int(*xFilter)(
0185597… drh 939 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 940 sqlite3_changeset_iter *p
0185597… drh 941 ),
0185597… drh 942 int(*xConflict)(
0185597… drh 943 void *pCtx, /* Copy of sixth arg to _apply() */
0185597… drh 944 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
0185597… drh 945 sqlite3_changeset_iter *p /* Handle describing change and conflict */
0185597… drh 946 ),
0185597… drh 947 void *pCtx, /* First argument passed to xConflict */
0185597… drh 948 void **ppRebase, int *pnRebase,
0185597… drh 949 int flags
0185597… drh 950 );
ad59a04… drh 951
ad59a04… drh 952 /*
ad59a04… drh 953 ** CAPI3REF: Configure a changegroup object
ad59a04… drh 954 **
ad59a04… drh 955 ** Configure the changegroup object passed as the first argument.
ad59a04… drh 956 ** At present the only valid value for the second parameter is
ad59a04… drh 957 ** [SQLITE_CHANGEGROUP_CONFIG_PATCHSET].
ad59a04… drh 958 */
ad59a04… drh 959 SQLITE_API int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg);
ad59a04… drh 960
ad59a04… drh 961 /*
ad59a04… drh 962 ** CAPI3REF: Options for sqlite3changegroup_config().
ad59a04… drh 963 **
ad59a04… drh 964 ** The following values may be passed as the 2nd parameter to
ad59a04… drh 965 ** sqlite3changegroup_config().
ad59a04… drh 966 **
ad59a04… drh 967 ** <dt>SQLITE_CHANGEGROUP_CONFIG_PATCHSET <dd>
ad59a04… drh 968 ** A changegroup object generates either a changeset or patchset. Usually,
ad59a04… drh 969 ** this is determined by whether the first call to sqlite3changegroup_add()
ad59a04… drh 970 ** is passed a changeset or a patchset. Or, if the first changes are added
ad59a04… drh 971 ** to the changegroup object using the sqlite3changegroup_change_xxx()
ad59a04… drh 972 ** APIs, then this option may be used to configure whether the changegroup
ad59a04… drh 973 ** object generates a changeset or patchset.
ad59a04… drh 974 **
ad59a04… drh 975 ** When this option is invoked, parameter pArg must point to a value of
ad59a04… drh 976 ** type int. If the changegroup currently contains zero changes, and the
ad59a04… drh 977 ** value of the int variable is zero or greater than zero, then the
ad59a04… drh 978 ** changegroup is configured to generate a changeset or patchset,
ad59a04… drh 979 ** respectively. It is a no-op, not an error, if the changegroup is not
ad59a04… drh 980 ** configured because it has already started accumulating changes.
ad59a04… drh 981 **
ad59a04… drh 982 ** Before returning, the int variable is set to 0 if the changegroup is
ad59a04… drh 983 ** configured to generate a changeset, or 1 if it is configured to generate
ad59a04… drh 984 ** a patchset.
ad59a04… drh 985 */
ad59a04… drh 986 #define SQLITE_CHANGEGROUP_CONFIG_PATCHSET 1
ad59a04… drh 987
ad59a04… drh 988
ad59a04… drh 989 /*
ad59a04… drh 990 ** CAPI3REF: Begin adding a change to a changegroup
ad59a04… drh 991 **
ad59a04… drh 992 ** This API is used, in concert with other sqlite3changegroup_change_xxx()
ad59a04… drh 993 ** APIs, to add changes to a changegroup object one at a time. To add a
ad59a04… drh 994 ** single change, the caller must:
ad59a04… drh 995 **
ad59a04… drh 996 ** 1. Invoke sqlite3changegroup_change_begin() to indicate the type of
ad59a04… drh 997 ** change (INSERT, UPDATE or DELETE), the affected table and whether
ad59a04… drh 998 ** or not the change should be marked as indirect.
ad59a04… drh 999 **
ad59a04… drh 1000 ** 2. Invoke sqlite3changegroup_change_int64() or one of the other four
ad59a04… drh 1001 ** value functions - _null(), _double(), _text() or _blob() - one or
ad59a04… drh 1002 ** more times to specify old.* and new.* values for the change being
ad59a04… drh 1003 ** constructed.
ad59a04… drh 1004 **
ad59a04… drh 1005 ** 3. Invoke sqlite3changegroup_change_finish() to either finish adding
ad59a04… drh 1006 ** the change to the group, or to discard the change altogether.
ad59a04… drh 1007 **
ad59a04… drh 1008 ** The first argument to this function must be a pointer to the existing
ad59a04… drh 1009 ** changegroup object that the change will be added to. The second argument
ad59a04… drh 1010 ** must be SQLITE_INSERT, SQLITE_UPDATE or SQLITE_DELETE. The third is the
ad59a04… drh 1011 ** name of the table that the change affects, and the fourth is a boolean
ad59a04… drh 1012 ** flag specifying whether the change should be marked as "indirect" (if
ad59a04… drh 1013 ** bIndirect is non-zero) or not indirect (if bIndirect is zero).
ad59a04… drh 1014 **
ad59a04… drh 1015 ** Following a successful call to this function, this function may not be
ad59a04… drh 1016 ** called again on the same changegroup object until after
ad59a04… drh 1017 ** sqlite3changegroup_change_finish() has been called. Doing so is an
ad59a04… drh 1018 ** SQLITE_MISUSE error.
ad59a04… drh 1019 **
ad59a04… drh 1020 ** The changegroup object passed as the first argument must be already
ad59a04… drh 1021 ** configured with schema data for the specified table. It may be configured
ad59a04… drh 1022 ** either by calling sqlite3changegroup_schema() with a database that contains
ad59a04… drh 1023 ** the table, or sqlite3changegroup_add() with a changeset that contains the
ad59a04… drh 1024 ** table. If the changegroup object has not been configured with a schema for
ad59a04… drh 1025 ** the specified table when this function is called, SQLITE_ERROR is returned.
ad59a04… drh 1026 **
ad59a04… drh 1027 ** If successful, SQLITE_OK is returned. Otherwise, if an error occurs, an
ad59a04… drh 1028 ** SQLite error code is returned. In this case, if argument pzErr is non-NULL,
ad59a04… drh 1029 ** then (*pzErr) may be set to point to a buffer containing a utf-8 formated,
ad59a04… drh 1030 ** nul-terminated, English language error message. It is the responsibility
ad59a04… drh 1031 ** of the caller to eventually free this buffer using sqlite3_free().
ad59a04… drh 1032 */
ad59a04… drh 1033 SQLITE_API int sqlite3changegroup_change_begin(
ad59a04… drh 1034 sqlite3_changegroup*,
ad59a04… drh 1035 int eOp,
ad59a04… drh 1036 const char *zTab,
ad59a04… drh 1037 int bIndirect,
ad59a04… drh 1038 char **pzErr
ad59a04… drh 1039 );
ad59a04… drh 1040
ad59a04… drh 1041 /*
ad59a04… drh 1042 ** CAPI3REF: Add a 64-bit integer to a changegroup
ad59a04… drh 1043 **
ad59a04… drh 1044 ** This function may only be called between a successful call to
ad59a04… drh 1045 ** sqlite3changegroup_change_begin() and its matching
ad59a04… drh 1046 ** sqlite3changegroup_change_finish() call. If it is called at any
ad59a04… drh 1047 ** other time, it is an SQLITE_MISUSE error. Calling this function
ad59a04… drh 1048 ** specifies a 64-bit integer value to be used in the change currently being
ad59a04… drh 1049 ** added to the changegroup object passed as the first argument.
ad59a04… drh 1050 **
ad59a04… drh 1051 ** The second parameter, bNew, specifies whether the value is to be part of
ad59a04… drh 1052 ** the new.* (if bNew is non-zero) or old.* (if bNew is zero) record of
ad59a04… drh 1053 ** the change under construction. If this does not match the type of change
ad59a04… drh 1054 ** specified by the preceding call to sqlite3changegroup_change_begin() (i.e.
ad59a04… drh 1055 ** an old.* value for an SQLITE_INSERT change, or a new.* value for an
ad59a04… drh 1056 ** SQLITE_DELETE), then SQLITE_ERROR is returned.
ad59a04… drh 1057 **
ad59a04… drh 1058 ** The third parameter specifies the column of the old.* or new.* record that
ad59a04… drh 1059 ** the value will be a part of. If the specified table has an explicit primary
ad59a04… drh 1060 ** key, then this is the index of the table column, numbered from 0 in the order
ad59a04… drh 1061 ** specified within the CREATE TABLE statement. Or, if the table uses an
ad59a04… drh 1062 ** implicit rowid key, then the column 0 is the rowid and the explicit columns
ad59a04… drh 1063 ** are numbered starting from 1. If the iCol parameter is less than 0 or greater
ad59a04… drh 1064 ** than the index of the last column in the table, SQLITE_RANGE is returned.
ad59a04… drh 1065 **
ad59a04… drh 1066 ** The fourth parameter is the integer value to use as part of the old.* or
ad59a04… drh 1067 ** new.* record.
ad59a04… drh 1068 **
ad59a04… drh 1069 ** If this call is successful, SQLITE_OK is returned. Otherwise, if an
ad59a04… drh 1070 ** error occurs, an SQLite error code is returned.
ad59a04… drh 1071 */
ad59a04… drh 1072 SQLITE_API int sqlite3changegroup_change_int64(
ad59a04… drh 1073 sqlite3_changegroup*,
ad59a04… drh 1074 int bNew,
ad59a04… drh 1075 int iCol,
ad59a04… drh 1076 sqlite3_int64 iVal
ad59a04… drh 1077 );
ad59a04… drh 1078
ad59a04… drh 1079 /*
ad59a04… drh 1080 ** CAPI3REF: Add a NULL to a changegroup
ad59a04… drh 1081 **
ad59a04… drh 1082 ** This function is similar to sqlite3changegroup_change_int64(). Except that
ad59a04… drh 1083 ** it configures the change currently under construction with a NULL value
ad59a04… drh 1084 ** instead of a 64-bit integer.
ad59a04… drh 1085 */
ad59a04… drh 1086 SQLITE_API int sqlite3changegroup_change_null(sqlite3_changegroup*, int, int);
ad59a04… drh 1087
ad59a04… drh 1088 /*
ad59a04… drh 1089 ** CAPI3REF: Add an double to a changegroup
ad59a04… drh 1090 **
ad59a04… drh 1091 ** This function is similar to sqlite3changegroup_change_int64(). Except that
ad59a04… drh 1092 ** it configures the change currently being constructed with a real value
ad59a04… drh 1093 ** instead of a 64-bit integer.
ad59a04… drh 1094 */
ad59a04… drh 1095 SQLITE_API int sqlite3changegroup_change_double(sqlite3_changegroup*, int, int, double);
ad59a04… drh 1096
ad59a04… drh 1097 /*
ad59a04… drh 1098 ** CAPI3REF: Add a text value to a changegroup
ad59a04… drh 1099 **
ad59a04… drh 1100 ** This function is similar to sqlite3changegroup_change_int64(). It configures
ad59a04… drh 1101 ** the currently accumulated change with a text value instead of a 64-bit
ad59a04… drh 1102 ** integer. Parameter pVal points to a buffer containing the text encoded using
ad59a04… drh 1103 ** utf-8. Parameter nVal may either be the size of the text value in bytes, or
ad59a04… drh 1104 ** else a negative value, in which case the buffer pVal points to is assumed to
ad59a04… drh 1105 ** be nul-terminated.
ad59a04… drh 1106 */
ad59a04… drh 1107 SQLITE_API int sqlite3changegroup_change_text(
ad59a04… drh 1108 sqlite3_changegroup*, int, int, const char *pVal, int nVal
ad59a04… drh 1109 );
ad59a04… drh 1110
ad59a04… drh 1111 /*
ad59a04… drh 1112 ** CAPI3REF: Add a blob to a changegroup
ad59a04… drh 1113 **
ad59a04… drh 1114 ** This function is similar to sqlite3changegroup_change_int64(). It configures
ad59a04… drh 1115 ** the currently accumulated change with a blob value instead of a 64-bit
ad59a04… drh 1116 ** integer. Parameter pVal points to a buffer containing the blob. Parameter
ad59a04… drh 1117 ** nVal is the size of the blob in bytes.
ad59a04… drh 1118 */
ad59a04… drh 1119 SQLITE_API int sqlite3changegroup_change_blob(
ad59a04… drh 1120 sqlite3_changegroup*, int, int, const void *pVal, int nVal
ad59a04… drh 1121 );
ad59a04… drh 1122
ad59a04… drh 1123 /*
ad59a04… drh 1124 ** CAPI3REF: Finish adding one-at-at-time changes to a changegroup
ad59a04… drh 1125 **
ad59a04… drh 1126 ** This function may only be called following a successful call to
ad59a04… drh 1127 ** sqlite3changegroup_change_begin(). Otherwise, it is an SQLITE_MISUSE error.
ad59a04… drh 1128 **
ad59a04… drh 1129 ** If parameter bDiscard is non-zero, then the current change is simply
ad59a04… drh 1130 ** discarded. In this case this function is always successful and SQLITE_OK
ad59a04… drh 1131 ** returned.
ad59a04… drh 1132 **
ad59a04… drh 1133 ** If parameter bDiscard is zero, then an attempt is made to add the current
ad59a04… drh 1134 ** change to the changegroup. Assuming the changegroup is configured to
ad59a04… drh 1135 ** produce a changeset (not a patchset), this requires that:
ad59a04… drh 1136 **
ad59a04… drh 1137 ** * If the change is an INSERT or DELETE, then a value must be specified
ad59a04… drh 1138 ** for all columns of the new.* or old.* record, respectively.
ad59a04… drh 1139 **
ad59a04… drh 1140 ** * If the change is an UPDATE record, then values must be provided for
ad59a04… drh 1141 ** the PRIMARY KEY columns of the old.* record, but must not be provided
ad59a04… drh 1142 ** for PRIMARY KEY columns of the new.* record.
ad59a04… drh 1143 **
ad59a04… drh 1144 ** * If the change is an UPDATE record, then for each non-PRIMARY KEY
ad59a04… drh 1145 ** column in the old.* record for which a value has been provided, a
ad59a04… drh 1146 ** value must also be provided for the same column in the new.* record.
ad59a04… drh 1147 ** Similarly, for each non-PK column in the old.* record for which
ad59a04… drh 1148 ** a value is not provided, a value must not be provided for the same
ad59a04… drh 1149 ** column in the new.* record.
ad59a04… drh 1150 **
ad59a04… drh 1151 ** * All values specified for PRIMARY KEY columns must be non-NULL.
ad59a04… drh 1152 **
ad59a04… drh 1153 ** Otherwise, it is an error.
ad59a04… drh 1154 **
ad59a04… drh 1155 ** If the changegroup already contains a change for the same row (identified
ad59a04… drh 1156 ** by PRIMARY KEY columns), then the current change is combined with the
ad59a04… drh 1157 ** existing change in the same way as for sqlite3changegroup_add().
ad59a04… drh 1158 **
ad59a04… drh 1159 ** For a patchset, all of the above rules apply except that it doesn't matter
ad59a04… drh 1160 ** whether or not values are provided for the non-PK old.* record columns
ad59a04… drh 1161 ** for an UPDATE or DELETE change. This means that code used to produce
ad59a04… drh 1162 ** a changeset using the sqlite3changegroup_change_xxx() APIs may also
ad59a04… drh 1163 ** be used to produce patchsets.
ad59a04… drh 1164 **
ad59a04… drh 1165 ** If the call is successful, SQLITE_OK is returned. Otherwise, if an error
ad59a04… drh 1166 ** occurs, an SQLite error code is returned. If an error is returned and
ad59a04… drh 1167 ** parameter pzErr is not NULL, then (*pzErr) may be set to point to a buffer
ad59a04… drh 1168 ** containing a nul-terminated, utf-8 encoded, English language error message.
ad59a04… drh 1169 ** It is the responsibility of the caller to eventually free any such error
ad59a04… drh 1170 ** message buffer using sqlite3_free().
ad59a04… drh 1171 */
ad59a04… drh 1172 SQLITE_API int sqlite3changegroup_change_finish(
ad59a04… drh 1173 sqlite3_changegroup*,
ad59a04… drh 1174 int bDiscard,
ad59a04… drh 1175 char **pzErr
ad59a04… drh 1176 );

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button