Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | More documentation spellcheck and cleanup. No changes to code. (CVS 5270) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
3a88e3ded9c54c319b6c5b6c3d521752 |
User & Date: | mihailim 2008-06-22 09:55:14.000 |
Context
2008-06-22
| ||
10:21 | Readded erroneously deleted {END} tag and doublechecked {(F,U,X)*}-{END} tag balancing. Minor documentation cleanup. No changes to code. (CVS 5271) (check-in: b55590501b user: mihailim tags: trunk) | |
09:55 | More documentation spellcheck and cleanup. No changes to code. (CVS 5270) (check-in: 3a88e3ded9 user: mihailim tags: trunk) | |
08:58 | More documentation spellcheck and cleanup. No changes to code. (CVS 5269) (check-in: d96b9bcd10 user: mihailim tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.350 2008/06/22 09:55:14 mihailim Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
208 209 210 211 212 213 214 | /* ** CAPI3REF: Closing A Database Connection {F12010} ** ** This routine is the destructor for the [sqlite3] object. ** ** Applications should [sqlite3_finalize | finalize] all [prepared statements] | | | 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 | /* ** CAPI3REF: Closing A Database Connection {F12010} ** ** This routine is the destructor for the [sqlite3] object. ** ** Applications should [sqlite3_finalize | finalize] all [prepared statements] ** and [sqlite3_blob_close | close] all [BLOB handles] associated with ** the [sqlite3] object prior to attempting to close the object. ** The [sqlite3_next_stmt()] interface can be used to locate all ** [prepared statements] associated with a [database connection] if desired. ** Typical code might look like this: ** ** <blockquote><pre> ** sqlite3_stmt *pStmt; |
︙ | ︙ | |||
4564 4565 4566 4567 4568 4569 4570 | ** has been opened. It is intended that this variable be set once ** as part of process initialization and before any SQLite interface ** routines have been call and remain unchanged thereafter. */ SQLITE_EXTERN char *sqlite3_temp_directory; /* | | > | 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 | ** has been opened. It is intended that this variable be set once ** as part of process initialization and before any SQLite interface ** routines have been call and remain unchanged thereafter. */ SQLITE_EXTERN char *sqlite3_temp_directory; /* ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} ** KEYWORDS: {autocommit mode} ** ** The sqlite3_get_autocommit() interface returns non-zero or ** zero if the given database connection is or is not in autocommit mode, ** respectively. Autocommit mode is on by default. ** Autocommit mode is disabled by a [BEGIN] statement. ** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. ** |
︙ | ︙ | |||
4812 4813 4814 4815 4816 4817 4818 | ** successfully. An [error code] is returned otherwise. ** ** Shared cache is disabled by default. But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** ** INVARIANTS: | | | 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 | ** successfully. An [error code] is returned otherwise. ** ** Shared cache is disabled by default. But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** ** INVARIANTS: ** ** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)] ** will enable or disable shared cache mode for any subsequently ** created [database connection] in the same process. ** ** {F10336} When shared cache is enabled, the [sqlite3_create_module()] ** interface will always return an error. ** |
︙ | ︙ | |||
4867 4868 4869 4870 4871 4872 4873 | ** cannot free sufficient memory to prevent the limit from being exceeded, ** the memory is allocated anyway and the current operation proceeds. ** ** A negative or zero value for N means that there is no soft heap limit and ** [sqlite3_release_memory()] will only be called when memory is exhausted. ** The default value for the soft heap limit is zero. ** | | | 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 | ** cannot free sufficient memory to prevent the limit from being exceeded, ** the memory is allocated anyway and the current operation proceeds. ** ** A negative or zero value for N means that there is no soft heap limit and ** [sqlite3_release_memory()] will only be called when memory is exhausted. ** The default value for the soft heap limit is zero. ** ** SQLite makes a best effort to honor the soft heap limit. ** But if the soft heap limit cannot be honored, execution will ** continue without error or notification. This is why the limit is ** called a "soft" limit. It is advisory only. ** ** Prior to SQLite version 3.5.0, this routine only constrained the memory ** allocated by a single thread - the same thread in which this routine ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is |
︙ | ︙ | |||
4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 | ** The third and fourth parameters to this function are the table and column ** name of the desired column, respectively. Neither of these parameters ** may be NULL. ** ** Metadata is returned by writing to the memory locations passed as the 5th ** and subsequent parameters to this function. Any of these arguments may be ** NULL, in which case the corresponding element of metadata is omitted. ** <blockquote> ** <table border="1"> ** <tr><th> Parameter <th> Output<br>Type <th> Description ** ** <tr><td> 5th <td> const char* <td> Data type ** <tr><td> 6th <td> const char* <td> Name of default collation sequence ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint | > | 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 | ** The third and fourth parameters to this function are the table and column ** name of the desired column, respectively. Neither of these parameters ** may be NULL. ** ** Metadata is returned by writing to the memory locations passed as the 5th ** and subsequent parameters to this function. Any of these arguments may be ** NULL, in which case the corresponding element of metadata is omitted. ** ** <blockquote> ** <table border="1"> ** <tr><th> Parameter <th> Output<br>Type <th> Description ** ** <tr><td> 5th <td> const char* <td> Data type ** <tr><td> 6th <td> const char* <td> Name of default collation sequence ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint |
︙ | ︙ | |||
5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 | /* ** CAPI3REF: Virtual Table Object {F18000} ** KEYWORDS: sqlite3_module ** ** A module is a class of virtual tables. Each module is defined ** by an instance of the following structure. This structure consists ** mostly of methods for the module. */ struct sqlite3_module { int iVersion; int (*xCreate)(sqlite3*, void *pAux, int argc, const char *const*argv, sqlite3_vtab **ppVTab, char**); int (*xConnect)(sqlite3*, void *pAux, | > > > | 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 | /* ** CAPI3REF: Virtual Table Object {F18000} ** KEYWORDS: sqlite3_module ** ** A module is a class of virtual tables. Each module is defined ** by an instance of the following structure. This structure consists ** mostly of methods for the module. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ struct sqlite3_module { int iVersion; int (*xCreate)(sqlite3*, void *pAux, int argc, const char *const*argv, sqlite3_vtab **ppVTab, char**); int (*xConnect)(sqlite3*, void *pAux, |
︙ | ︙ | |||
5155 5156 5157 5158 5159 5160 5161 | ** ** The sqlite3_index_info structure and its substructures is used to ** pass information into and receive the reply from the xBestIndex ** method of an sqlite3_module. The fields under **Inputs** are the ** inputs to xBestIndex and are read-only. xBestIndex inserts its ** results into the **Outputs** fields. ** | | < | | < | | 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 | ** ** The sqlite3_index_info structure and its substructures is used to ** pass information into and receive the reply from the xBestIndex ** method of an sqlite3_module. The fields under **Inputs** are the ** inputs to xBestIndex and are read-only. xBestIndex inserts its ** results into the **Outputs** fields. ** ** The aConstraint[] array records WHERE clause constraints of the form: ** ** <pre>column OP expr</pre> ** ** where OP is =, <, <=, >, or >=. The particular operator is ** stored in aConstraint[].op. The index of the column is stored in ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the ** expr on the right-hand side can be evaluated (and thus the constraint ** is usable) and false if it cannot. ** ** The optimizer automatically inverts terms of the form "expr OP column" ** and makes other simplifications to the WHERE clause in an attempt to ** get as many WHERE clause terms into the form shown above as possible. |
︙ | ︙ | |||
5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 | ** the correct order to satisfy the ORDER BY clause so that no separate ** sorting step is required. ** ** The estimatedCost value is an estimate of the cost of doing the ** particular lookup. A full scan of a table with N entries should have ** a cost of N. A binary search of a table of N entries should have a ** cost of approximately log(N). */ struct sqlite3_index_info { /* Inputs */ int nConstraint; /* Number of entries in aConstraint */ struct sqlite3_index_constraint { int iColumn; /* Column on left-hand side of constraint */ unsigned char op; /* Constraint operator */ | > > > | 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 | ** the correct order to satisfy the ORDER BY clause so that no separate ** sorting step is required. ** ** The estimatedCost value is an estimate of the cost of doing the ** particular lookup. A full scan of a table with N entries should have ** a cost of N. A binary search of a table of N entries should have a ** cost of approximately log(N). ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ struct sqlite3_index_info { /* Inputs */ int nConstraint; /* Number of entries in aConstraint */ struct sqlite3_index_constraint { int iColumn; /* Column on left-hand side of constraint */ unsigned char op; /* Constraint operator */ |
︙ | ︙ | |||
5231 5232 5233 5234 5235 5236 5237 | #define SQLITE_INDEX_CONSTRAINT_LT 16 #define SQLITE_INDEX_CONSTRAINT_GE 32 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 /* ** CAPI3REF: Register A Virtual Table Implementation {F18200} ** | | | | | > > > | | | | | | > > > > > > > > > | 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 | #define SQLITE_INDEX_CONSTRAINT_LT 16 #define SQLITE_INDEX_CONSTRAINT_GE 32 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 /* ** CAPI3REF: Register A Virtual Table Implementation {F18200} ** ** This routine is used to register a new module name with a ** [database connection]. Module names must be registered before ** creating new virtual tables on the module, or before using ** preexisting virtual tables of the module. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_create_module( sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlite3_module *, /* Methods for the module */ void * /* Client data for xCreate/xConnect */ ); /* ** CAPI3REF: Register A Virtual Table Implementation {F18210} ** ** This routine is identical to the [sqlite3_create_module()] method above, ** except that it allows a destructor function to be specified. It is ** even more experimental than the rest of the virtual tables API. */ int sqlite3_create_module_v2( sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlite3_module *, /* Methods for the module */ void *, /* Client data for xCreate/xConnect */ void(*xDestroy)(void*) /* Module destructor function */ ); /* ** CAPI3REF: Virtual Table Instance Object {F18010} ** KEYWORDS: sqlite3_vtab ** ** Every module implementation uses a subclass of the following structure ** to describe a particular instance of the module. Each subclass will ** be tailored to the specific needs of the module implementation. ** The purpose of this superclass is to define certain fields that are ** common to all module implementations. ** ** Virtual tables methods can set an error message by assigning a ** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should ** take care that any prior string is freed by a call to [sqlite3_free()] ** prior to assigning a new string to zErrMsg. After the error message ** is delivered up to the client application, the string will be automatically ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field ** since virtual tables are commonly implemented in loadable extensions which ** do not have access to sqlite3MPrintf() or sqlite3Free(). ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ struct sqlite3_vtab { const sqlite3_module *pModule; /* The module for this virtual table */ int nRef; /* Used internally */ char *zErrMsg; /* Error message from sqlite3_mprintf() */ /* Virtual table implementations will typically add additional fields */ }; /* ** CAPI3REF: Virtual Table Cursor Object {F18020} ** KEYWORDS: sqlite3_vtab_cursor ** ** Every module implementation uses a subclass of the following structure ** to describe cursors that point into the virtual table and are used ** to loop through the virtual table. Cursors are created using the ** xOpen method of the module. Each module implementation will define ** the content of a cursor structure to suit its own needs. ** ** This superclass exists in order to define fields of the cursor that ** are common to all implementations. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ struct sqlite3_vtab_cursor { sqlite3_vtab *pVtab; /* Virtual table of this cursor */ /* Virtual table implementations will typically add additional fields */ }; /* ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280} ** ** The xCreate and xConnect methods of a module use the following API ** to declare the format (the names and datatypes of the columns) of ** the virtual tables they implement. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); /* ** CAPI3REF: Overload A Function For A Virtual Table {F18300} ** ** Virtual tables can provide alternative implementations of functions |
︙ | ︙ | |||
5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 | ** interface fixed, support it indefinitely, and remove this comment. ** ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** ** An instance of this object represents an open BLOB on which ** [sqlite3_blob_open | incremental BLOB I/O] can be performed. | > | | | | < | | | | < | | | < | | | | | | | | | | < | | | > | < | < | | | | | < | | | | | | | < | | | | | | < | | | | | | | | | | | | < | | | | | | 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 | ** interface fixed, support it indefinitely, and remove this comment. ** ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** KEYWORDS: {BLOB handle} {BLOB handles} ** ** An instance of this object represents an open BLOB on which ** [sqlite3_blob_open | incremental BLOB I/O] can be performed. ** Objects of this type are created by [sqlite3_blob_open()] ** and destroyed by [sqlite3_blob_close()]. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces ** can be used to read or write small subsections of the BLOB. ** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} ** ** This interfaces opens a handle to the BLOB located ** in row iRow, column zColumn, table zTable in database zDb; ** in other words, the same BLOB that would be selected by: ** ** <pre> ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; ** </pre> {END} ** ** If the flags parameter is non-zero, the the BLOB is opened for read ** and write access. If it is zero, the BLOB is opened for read access. ** ** Note that the database name is not the filename that contains ** the database but rather the symbolic name of the database that ** is assigned when the database is connected using [ATTACH]. ** For the main database file, the database name is "main". ** For TEMP tables, the database name is "temp". ** ** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written ** to *ppBlob. Otherwise an [error code] is returned and any value written ** to *ppBlob should not be used by the caller. ** This function sets the [database connection] error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] ** interface opens an [sqlite3_blob] object P on the BLOB in column C ** of the table T in the database B on the [database connection] D. ** ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts ** a new transaction on the [database connection] D if that ** connection is not already in a transaction. ** ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the BLOB for ** read and write access if and only if the F parameter is non-zero. ** ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return ** information appropriate for that error. */ int sqlite3_blob_open( sqlite3*, const char *zDb, const char *zTable, const char *zColumn, sqlite3_int64 iRow, int flags, sqlite3_blob **ppBlob ); /* ** CAPI3REF: Close A BLOB Handle {F17830} ** ** Closes an open [BLOB handle]. ** ** Closing a BLOB shall cause the current transaction to commit ** if there are no other BLOBs, no pending prepared statements, and the ** database connection is in [autocommit mode]. ** If any writes were made to the BLOB, they might be held in cache ** until the close operation if they will fit. {END} ** ** Closing the BLOB often forces the changes ** out to disk and so if any I/O errors occur, they will likely occur ** at the time when the BLOB is closed. {F17833} Any errors that occur during ** closing are reported as a non-zero return value. ** ** The BLOB is closed unconditionally. Even if this routine returns ** an error code, the BLOB is still closed. ** ** INVARIANTS: ** ** {F17833} The [sqlite3_blob_close(P)] interface closes an ** [sqlite3_blob] object P previously opened using ** [sqlite3_blob_open()]. ** ** {F17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and ** the database connection is in [autocommit mode]. ** ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the ** [sqlite3_blob] object P unconditionally, even if ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. */ int sqlite3_blob_close(sqlite3_blob *); /* ** CAPI3REF: Return The Size Of An Open BLOB {F17840} ** ** Returns the size in bytes of the BLOB accessible via the open ** []BLOB handle] in its only argument. ** ** INVARIANTS: ** ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size ** in bytes of the BLOB that the [sqlite3_blob] object P ** refers to. */ int sqlite3_blob_bytes(sqlite3_blob *); /* ** CAPI3REF: Read Data From A BLOB Incrementally {F17850} ** ** This function is used to read data from an open [BLOB handle] into a ** caller-supplied buffer. N bytes of data are copied into buffer Z ** from the open BLOB, starting at offset iOffset. ** ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is ** less than zero, [SQLITE_ERROR] is returned and no data is read. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes beginning ** at offset X from the BLOB that [sqlite3_blob] object P refers to ** and writes those N bytes into buffer Z. ** ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB ** is less than N+X bytes, then the function returns [SQLITE_ERROR] ** and nothing is read from the BLOB. ** ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero ** then the function returns [SQLITE_ERROR] ** and nothing is read from the BLOB. ** ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK] ** if N bytes where successfully read into buffer Z. ** ** {F17865} If the requested read could not be completed, ** the [sqlite3_blob_read(P,Z,N,X)] interface returns an ** appropriate [error code] or [extended error code]. ** ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return ** information appropriate for that error, where D is the ** [database connection] that was used to open the [BLOB handle] P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} ** ** This function is used to write data into an open [BLOB handle] from a ** caller-supplied buffer. N bytes of data are copied from the buffer Z ** into the open BLOB, starting at offset iOffset. ** ** If the [BLOB handle] passed as the first argument was not opened for ** writing (the flags parameter to [sqlite3_blob_open()] was zero), ** this function returns [SQLITE_READONLY]. ** ** This function may only modify the contents of the BLOB; it is ** not possible to increase the size of a BLOB using this API. ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is written. If N is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes ** from buffer Z into the BLOB that [sqlite3_blob] object P ** refers to beginning at an offset of X into the BLOB. ** ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns ** [SQLITE_READONLY] if the [sqlite3_blob] object P was ** [sqlite3_blob_open | opened] for reading only. ** ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the BLOB ** is less than N+X bytes, then the function returns [SQLITE_ERROR] ** and nothing is written into the BLOB. ** ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero ** then the function returns [SQLITE_ERROR] ** and nothing is written into the BLOB. ** ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK] ** if N bytes where successfully written into the BLOB. ** ** {F17885} If the requested write could not be completed, ** the [sqlite3_blob_write(P,Z,N,X)] interface returns an ** appropriate [error code] or [extended error code]. ** ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], |
︙ | ︙ | |||
5579 5580 5581 5582 5583 5584 5585 | ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to interact ** with the underlying operating system. Most SQLite builds come with a ** single default VFS that is appropriate for the host computer. ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. ** | | | | | < | | | | < | | | | | | 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 | ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to interact ** with the underlying operating system. Most SQLite builds come with a ** single default VFS that is appropriate for the host computer. ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. ** ** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. ** Names are case sensitive. ** Names are zero-terminated UTF-8 strings. ** If there is no match, a NULL pointer is returned. ** If zVfsName is NULL then the default VFS is returned. ** ** New VFSes are registered with sqlite3_vfs_register(). ** Each new VFS becomes the default VFS if the makeDflt flag is set. ** The same VFS can be registered multiple times without injury. ** To make an existing VFS into the default VFS, register it again ** with the makeDflt flag set. If two different VFSes with the ** same name are registered, the behavior is undefined. If a ** VFS is registered with a name that is NULL or an empty string, ** then the behavior is undefined. ** ** Unregister a VFS with the sqlite3_vfs_unregister() interface. ** If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. ** ** INVARIANTS: ** ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the ** registered [sqlite3_vfs] object whose name exactly matches ** the zero-terminated UTF-8 string N, or it returns NULL if ** there is no match. ** ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then ** the function returns a pointer to the default [sqlite3_vfs] ** object if there is one, or NULL if there is no default ** [sqlite3_vfs] object. ** ** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the ** well-formed [sqlite3_vfs] object P using the name given ** by the zName field of the object. ** ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register ** the same [sqlite3_vfs] object multiple times is a harmless no-op. ** ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs] ** object P the default [sqlite3_vfs] object if F is non-zero. ** ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the ** [sqlite3_vfs] object P so that it is no longer returned by ** subsequent calls to [sqlite3_vfs_find()]. */ sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); int sqlite3_vfs_unregister(sqlite3_vfs*); /* ** CAPI3REF: Mutexes {F17000} ** ** The SQLite core uses these routines for thread ** synchronization. Though they are intended for internal ** use by SQLite, code that links against SQLite is ** permitted to use any of these routines. ** ** The SQLite source code contains multiple implementations ** of these mutex routines. An appropriate implementation ** is selected automatically at compile-time. The following ** implementations are available in the SQLite core: ** ** <ul> ** <li> SQLITE_MUTEX_OS2 ** <li> SQLITE_MUTEX_PTHREAD ** <li> SQLITE_MUTEX_W32 ** <li> SQLITE_MUTEX_NOOP ** </ul> ** ** The SQLITE_MUTEX_NOOP implementation is a set of routines ** that does no real locking and is appropriate for use in ** a single-threaded application. The SQLITE_MUTEX_OS2, ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations ** are appropriate for use on OS/2, Unix, and Windows. ** ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex ** implementation is included with the library. In this case the ** application must supply a custom mutex implementation using the ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function ** before calling sqlite3_initialize() or any other public sqlite3_ ** function that calls sqlite3_initialize(). ** ** {F17011} The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. {F17012} If it returns NULL ** that means that a mutex could not be allocated. {F17013} SQLite ** will unwind its stack and return an error. {F17014} The argument ** to sqlite3_mutex_alloc() is one of these integer constants: |
︙ | ︙ | |||
5701 5702 5703 5704 5705 5706 5707 | ** may add additional static mutexes. Static mutexes are for internal ** use by SQLite only. Applications that use SQLite mutexes should ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() | | | | | | | 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 | ** may add additional static mutexes. Static mutexes are for internal ** use by SQLite only. Applications that use SQLite mutexes should ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() ** returns a different mutex on every call. {F17034} But for the static ** mutex types, the same mutex is returned on every call that has ** the same type number. {END} ** ** {F17019} The sqlite3_mutex_free() routine deallocates a previously ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in ** use when they are deallocated. {U17022} Attempting to deallocate a static ** mutex results in undefined behavior. {F17023} SQLite never deallocates ** a static mutex. {END} ** ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt ** to enter a mutex. {F17024} If another thread is already within the mutex, ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return ** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns [SQLITE_OK] ** upon successful entry. {F17026} Mutexes created using ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. ** {F17027} In such cases the, ** mutex must be exited an equal number of times before another thread ** can enter. {U17028} If the same thread tries to enter any other ** kind of mutex more than once, the behavior is undefined. ** {F17029} SQLite will never exhibit ** such behavior in its own use of mutexes. ** ** Some systems (for example, Windows 95) do not support the operation ** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() ** will always return SQLITE_BUSY. {F17030} The SQLite core only ever uses ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. ** ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was ** previously entered by the same thread. {U17032} The behavior ** is undefined if the mutex is not currently entered by the ** calling thread or is not currently allocated. {F17033} SQLite will ** never do either. {END} |
︙ | ︙ | |||
5755 5756 5757 5758 5759 5760 5761 | /* ** CAPI3REF: Mutex Methods Object {F17120} ** ** An instance of this structure defines the low-level routines ** used to allocate and use mutexes. ** ** Usually, the default mutex implementations provided by SQLite are | | | | | | | | 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 | /* ** CAPI3REF: Mutex Methods Object {F17120} ** ** An instance of this structure defines the low-level routines ** used to allocate and use mutexes. ** ** Usually, the default mutex implementations provided by SQLite are ** sufficient, however the user has the option of substituting a custom ** implementation for specialized deployments or systems for which SQLite ** does not provide a suitable implementation. In this case, the user ** creates and populates an instance of this structure to pass ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. ** Additionally, an instance of this structure can be used as an ** output variable when querying the system for the current mutex ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. ** ** The xMutexInit method defined by this structure is invoked as ** part of system initialization by the sqlite3_initialize() function. ** {F17001} The xMutexInit routine shall be called by SQLite once for each ** effective call to [sqlite3_initialize()]. ** ** The xMutexEnd method defined by this structure is invoked as ** part of system shutdown by the sqlite3_shutdown() function. The ** implementation of this method is expected to release all outstanding ** resources obtained by the mutex methods implementation, especially ** those obtained by the xMutexInit method. {F17003} The xMutexEnd() ** interface shall be invoked once for each call to [sqlite3_shutdown()]. ** ** The remaining seven methods defined by this structure (xMutexAlloc, ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and ** xMutexNotheld) implement the following interfaces (respectively): ** ** <ul> ** <li> [sqlite3_mutex_alloc()] </li> |
︙ | ︙ | |||
5811 5812 5813 5814 5815 5816 5817 | void (*xMutexEnter)(sqlite3_mutex *); int (*xMutexTry)(sqlite3_mutex *); void (*xMutexLeave)(sqlite3_mutex *); int (*xMutexHeld)(sqlite3_mutex *); int (*xMutexNotheld)(sqlite3_mutex *); }; | < | | 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 | void (*xMutexEnter)(sqlite3_mutex *); int (*xMutexTry)(sqlite3_mutex *); void (*xMutexLeave)(sqlite3_mutex *); int (*xMutexHeld)(sqlite3_mutex *); int (*xMutexNotheld)(sqlite3_mutex *); }; /* ** CAPI3REF: Mutex Verification Routines {F17080} ** ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines ** are intended for use inside assert() statements. {F17081} The SQLite core ** never uses these routines except inside an assert() and applications ** are advised to follow the lead of the core. {F17082} The core only ** provides implementations for these routines when it is compiled ** with the SQLITE_DEBUG flag. {U17087} External mutex implementations |
︙ | ︙ | |||
5840 5841 5842 5843 5844 5845 5846 | ** ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then ** the routine should return 1. {END} This seems counter-intuitive since ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is | | | 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 | ** ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then ** the routine should return 1. {END} This seems counter-intuitive since ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is ** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld() ** interface should also return 1 when given a NULL pointer. */ int sqlite3_mutex_held(sqlite3_mutex*); int sqlite3_mutex_notheld(sqlite3_mutex*); /* ** CAPI3REF: Mutex Types {F17001} |
︙ | ︙ | |||
5927 5928 5929 5930 5931 5932 5933 | #define SQLITE_TESTCTRL_BITVEC_TEST 8 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 /* ** CAPI3REF: SQLite Runtime Status {F17200} ** | | | 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 | #define SQLITE_TESTCTRL_BITVEC_TEST 8 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 /* ** CAPI3REF: SQLite Runtime Status {F17200} ** ** This interface is used to retrieve runtime status information ** about the preformance of SQLite, and optionally to reset various ** highwater marks. The first argument is an integer code for ** the specific parameter to measure. Recognized integer codes ** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...]. ** The current value of the parameter is returned into *pCurrent. ** The highest recorded value is returned in *pHighwater. If the ** resetFlag is true, then the highest record value is reset after |
︙ | ︙ | |||
5965 5966 5967 5968 5969 5970 5971 | ** ** These integer constants designate various run-time status parameters ** that can be returned by [sqlite3_status()]. ** ** <dl> ** <dt>SQLITE_STATUS_MEMORY_USED</dt> ** <dd>This parameter is the current amount of memory checked out | | | | 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 | ** ** These integer constants designate various run-time status parameters ** that can be returned by [sqlite3_status()]. ** ** <dl> ** <dt>SQLITE_STATUS_MEMORY_USED</dt> ** <dd>This parameter is the current amount of memory checked out ** using [sqlite3_malloc()], either directly or indirectly. The ** figure includes calls made to [sqlite3_malloc()] by the application ** and internal memory usage by the SQLite library. Scratch memory ** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in ** this parameter. The amount returned is the sum of the allocation ** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd> ** ** <dt>SQLITE_STATUS_PAGECACHE_USED</dt> ** <dd>This parameter returns the number of pages used out of the ** page cache buffer configured using [SQLITE_CONFIG_PAGECACHE]. The ** value returned is in pages, not in bytes.</dd> ** ** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> |
︙ | ︙ |