Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | More documentation spellcheck and cleanup. No changes to code. (CVS 5260) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
8c457fb08b93aa1aa9f62d0ec31755d7 |
User & Date: | mihailim 2008-06-21 11:20:48.000 |
Context
2008-06-21
| ||
12:15 | Remove mutex2.test. It will be replaced later today by permutations.test. (CVS 5261) (check-in: 98a6a0a30f user: danielk1977 tags: trunk) | |
11:20 | More documentation spellcheck and cleanup. No changes to code. (CVS 5260) (check-in: 8c457fb08b user: mihailim tags: trunk) | |
08:12 | Fix a problem in the test suite that could cause a crash if using a pre-allocated block of memory for pages (the problem was that sqlite3_shutdown() was being called while there were still open database connections). (CVS 5259) (check-in: 3d413e9b46 user: danielk1977 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.344 2008/06/21 11:20:48 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++. |
︙ | ︙ | |||
1022 1023 1024 1025 1026 1027 1028 | ** SQLITE_THREADSAFE=1) the SQLite library will itself serialize access ** to [database connections] and [prepared statements] so that the ** application is free to use the same [database connection] or the ** same [prepared statement] in different threads at the same time.</dd> ** ** <dt>SQLITE_CONFIG_MALLOC</dt> ** <dd>This option takes a single argument which is a pointer to an | | | | 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 | ** SQLITE_THREADSAFE=1) the SQLite library will itself serialize access ** to [database connections] and [prepared statements] so that the ** application is free to use the same [database connection] or the ** same [prepared statement] in different threads at the same time.</dd> ** ** <dt>SQLITE_CONFIG_MALLOC</dt> ** <dd>This option takes a single argument which is a pointer to an ** instance of the [sqlite3_mem_methods] structure. The argument specifies ** alternative low-level memory allocation routines to be used in place of ** the memory allocation routines built into SQLite.</dd> ** ** <dt>SQLITE_CONFIG_GETMALLOC</dt> ** <dd>This option takes a single argument which is a pointer to an ** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] ** structure is filled with the currently defined memory allocation routines. ** This option can be used to overload the default memory allocation |
︙ | ︙ | |||
1053 1054 1055 1056 1057 1058 1059 | ** <dt>SQLITE_CONFIG_SCRATCH</dt> ** <dd>This option specifies a static memory buffer that SQLite can use for ** scratch memory. There are three arguments: A pointer to the memory, the ** size of each scratch buffer (sz), and the number of buffers (N). The sz ** argument must be a multiple of 16. The first ** argument should point to an allocation of at least (sz+4)*N bytes of memory. ** SQLite will use no more than one scratch buffer at once per thread, so | | | < | < | | | | | | < < | < | | 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 | ** <dt>SQLITE_CONFIG_SCRATCH</dt> ** <dd>This option specifies a static memory buffer that SQLite can use for ** scratch memory. There are three arguments: A pointer to the memory, the ** size of each scratch buffer (sz), and the number of buffers (N). The sz ** argument must be a multiple of 16. The first ** argument should point to an allocation of at least (sz+4)*N bytes of memory. ** SQLite will use no more than one scratch buffer at once per thread, so ** N should be set to the expected maximum number of threads. The sz ** parameter should be 6 times the size of the largest database page size. ** Scratch buffers are used as part of the btree balance operation. If ** The btree balancer needs additional memory beyond what is provided by ** scratch buffers or if no scratch buffer space is specified, then SQLite ** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd> ** ** <dt>SQLITE_CONFIG_PAGECACHE</dt> ** <dd>This option specifies a static memory buffer that SQLite can use for ** the database page cache. There are three arguments: A pointer to the ** memory, the size of each page buffer (sz), and the number of pages (N). ** The sz argument must be a power of two between 512 and 32768. The first ** argument should point to an allocation of at least (sz+4)*N bytes of memory. ** SQLite will use the memory provided by the first argument to satisfy its ** memory needs for the first N pages that it adds to cache. If additional ** page cache memory is needed beyond what is provided by this option, then ** SQLite goes to [sqlite3_malloc()] for the additional storage space.</dd> ** ** <dt>SQLITE_CONFIG_HEAP</dt> ** <dd>This option specifies a static memory buffer that SQLite will use ** for all of its dynamic memory allocation needs beyond those provided ** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. ** There are three arguments: A pointer to the memory, the number of ** bytes in the memory buffer, and the minimum allocation size. When ** this configuration option is used, SQLite never calls the system ** malloc() implementation but instead uses the supplied memory buffer ** to satisfy all [sqlite3_malloc()] requests.</dd> ** ** <dt>SQLITE_CONFIG_MUTEX</dt> ** <dd>This option takes a single argument which is a pointer to an ** instance of the [sqlite3_mutex_methods] structure. The argument specifies ** alternative low-level mutex routines to be used in place ** the mutex routines built into SQLite.</dd> ** ** <dt>SQLITE_CONFIG_GETMALLOC</dt> ** <dd>This option takes a single argument which is a pointer to an ** instance of the [sqlite3_mutex_methods] structure. The ** [sqlite3_mutex_methods] |
︙ | ︙ | |||
1115 1116 1117 1118 1119 1120 1121 | #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ | < | | | < | < | | | | | | | | < | | | | | | | | < | | | | | | 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 | #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ /* ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} ** ** The sqlite3_extended_result_codes() routine enables or disables the ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite. ** The extended result codes are disabled by default for historical ** compatibility considerations. ** ** INVARIANTS: ** ** {F12201} Each new [database connection] shall have the ** [extended result codes] feature disabled by default. ** ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable ** [extended result codes] for the [database connection] D ** if the F parameter is true, or disable them if F is false. */ int sqlite3_extended_result_codes(sqlite3*, int onoff); /* ** CAPI3REF: Last Insert Rowid {F12220} ** ** Each entry in an SQLite table has a unique 64-bit signed ** integer key called the "rowid". The rowid is always available ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those ** names are not also used by explicitly declared columns. If ** the table has a column of type INTEGER PRIMARY KEY then that column ** is another alias for the rowid. ** ** This routine returns the rowid of the most recent ** successful INSERT into the database from the [database connection] ** in the first argument. If no successful INSERTs ** have ever occurred on that database connection, zero is returned. ** ** If an INSERT occurs within a trigger, then the rowid of the inserted ** row is returned by this routine as long as the trigger is running. ** But once the trigger terminates, the value returned by this routine ** reverts to the last value inserted before the trigger fired. ** ** An INSERT that fails due to a constraint violation is not a ** successful INSERT and does not change the value returned by this ** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, ** and INSERT OR ABORT make no changes to the return value of this ** routine when their insertion fails. When INSERT OR REPLACE ** encounters a constraint violation, it does not fail. The ** INSERT continues to completion after deleting rows that caused ** the constraint problem so INSERT OR REPLACE will always change ** the return value of this interface. ** ** For the purposes of this routine, an INSERT is considered to ** be successful even if it is subsequently rolled back. ** ** INVARIANTS: ** ** {F12221} The [sqlite3_last_insert_rowid()] function returns the rowid ** of the most recent successful INSERT performed on the same ** [database connection] and within the same or higher level ** trigger context, or zero if there have been no qualifying inserts. ** ** {F12223} The [sqlite3_last_insert_rowid()] function returns the ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** ** LIMITATIONS: ** ** {U12232} If a separate thread performs a new INSERT on the same ** database connection while the [sqlite3_last_insert_rowid()] ** function is running and thus changes the last insert rowid, ** then the value returned by [sqlite3_last_insert_rowid()] is ** unpredictable and might not equal either the old or the new ** last insert rowid. */ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); /* ** CAPI3REF: Count The Number Of Rows Modified {F12240} ** ** This function returns the number of database rows that were changed ** or inserted or deleted by the most recently completed SQL statement ** on the [database connection] specified by the first parameter. ** Only changes that are directly specified by the INSERT, UPDATE, ** or DELETE statement are counted. Auxiliary changes caused by ** triggers are not counted. Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** ** A "row change" is a change to a single row of a single table ** caused by an INSERT, DELETE, or UPDATE statement. Rows that ** are changed as side effects of REPLACE constraint resolution, ** rollback, ABORT processing, DROP TABLE, or by any other |
︙ | ︙ | |||
1225 1226 1227 1228 1229 1230 1231 | ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does ** not create a new trigger context. ** ** This function returns the number of direct row changes in the ** most recent INSERT, UPDATE, or DELETE statement within the same ** trigger context. ** | | | < | | | | | | < | | > | | | | | | | | < < | | | | < | | > | | | | < | | | | | | > | | | | > | < | 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 | ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does ** not create a new trigger context. ** ** This function returns the number of direct row changes in the ** most recent INSERT, UPDATE, or DELETE statement within the same ** trigger context. ** ** Thus, when called from the top level, this function returns the ** number of changes in the most recent INSERT, UPDATE, or DELETE ** that also occurred at the top level. Within the body of a trigger, ** the sqlite3_changes() interface can be called to find the number of ** changes in the most recently completed INSERT, UPDATE, or DELETE ** statement within the body of the same trigger. ** However, the number returned does not include changes ** caused by subtriggers since those have their own context. ** ** SQLite implements the command "DELETE FROM table" without a WHERE clause ** by dropping and recreating the table. (This is much faster than going ** through and deleting individual elements from the table.) Because of this ** optimization, the deletions in "DELETE FROM table" are not row changes and ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] ** functions, regardless of the number of elements that were originally ** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** INVARIANTS: ** ** {F12241} The [sqlite3_changes()] function shall return the number of ** row changes caused by the most recent INSERT, UPDATE, ** or DELETE statement on the same database connection and ** within the same or higher trigger context, or zero if there have ** not been any qualifying row changes. ** ** {F12243} Statements of the form "DELETE FROM tablename" with no ** WHERE clause shall cause subsequent calls to ** [sqlite3_changes()] to return zero, regardless of the ** number of rows originally in the table. ** ** LIMITATIONS: ** ** {U12252} If a separate thread makes changes on the same database connection ** while [sqlite3_changes()] is running then the value returned ** is unpredictable and not meaningful. */ int sqlite3_changes(sqlite3*); /* ** CAPI3REF: Total Number Of Rows Modified {F12260} ** ** This function returns the number of row changes caused by INSERT, ** UPDATE or DELETE statements since the [database connection] was opened. ** The count includes all changes from all trigger contexts. However, ** the count does not include changes used to implement REPLACE constraints, ** do rollbacks or ABORT processing, or DROP table processing. ** The changes are counted as soon as the statement that makes them is ** completed (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). ** ** SQLite implements the command "DELETE FROM table" without a WHERE clause ** by dropping and recreating the table. (This is much faster than going ** through and deleting individual elements from the table.) Because of this ** optimization, the deletions in "DELETE FROM table" are not row changes and ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] ** functions, regardless of the number of elements that were originally ** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** See also the [sqlite3_changes()] interface. ** ** INVARIANTS: ** ** {F12261} The [sqlite3_total_changes()] returns the total number ** of row changes caused by INSERT, UPDATE, and/or DELETE ** statements on the same [database connection], in any ** trigger context, since the database connection was created. ** ** {F12263} Statements of the form "DELETE FROM tablename" with no ** WHERE clause shall not change the value returned ** by [sqlite3_total_changes()]. ** ** LIMITATIONS: ** ** {U12264} If a separate thread makes changes on the same database connection ** while [sqlite3_total_changes()] is running then the value ** returned is unpredictable and not meaningful. */ int sqlite3_total_changes(sqlite3*); /* ** CAPI3REF: Interrupt A Long-Running Query {F12270} ** ** This function causes any pending database operation to abort and ** return at its earliest opportunity. This routine is typically ** called in response to an user action such as pressing "Cancel" ** or Ctrl-C where the user wants a long query operation to halt ** immediately. ** ** It is safe to call this routine from a thread different from the ** thread that is currently running the database operation. But it ** is not safe to call this routine with a [database connection] that ** is closed or might close before sqlite3_interrupt() returns. ** ** If an SQL operation is very nearly finished at the time when ** sqlite3_interrupt() is called, then it might not have an opportunity ** to be interrupted and might continue to completion. ** ** An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. ** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE ** that is inside an explicit transaction, then the entire transaction ** will be rolled back automatically. ** ** A call to sqlite3_interrupt() has no effect on SQL statements ** that are started after sqlite3_interrupt() returns. ** ** INVARIANTS: ** ** {F12271} The [sqlite3_interrupt()] interface will force all running ** SQL statements associated with the same database connection ** to halt after processing at most one additional row of data. ** ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] ** will return [SQLITE_INTERRUPT]. ** ** LIMITATIONS: ** ** {U12279} If the database connection closes while [sqlite3_interrupt()] |
︙ | ︙ | |||
1365 1366 1367 1368 1369 1370 1371 | ** appears to be a complete SQL statement. A statement is judged to be ** complete if it ends with a semicolon token and is not a fragment of a ** CREATE TRIGGER statement. Semicolons that are embedded within ** string literals or quoted identifier names or comments are not ** independent tokens (they are part of the token in which they are ** embedded) and thus do not count as a statement terminator. ** | | | | | | < | | | > | < | < | > | | | | | < | | | < | 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 | ** appears to be a complete SQL statement. A statement is judged to be ** complete if it ends with a semicolon token and is not a fragment of a ** CREATE TRIGGER statement. Semicolons that are embedded within ** string literals or quoted identifier names or comments are not ** independent tokens (they are part of the token in which they are ** embedded) and thus do not count as a statement terminator. ** ** These routines do not parse the SQL statements thus ** will not detect syntactically incorrect SQL. ** ** INVARIANTS: ** ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions ** return true (non-zero) if and only if the last non-whitespace ** token in their input is a semicolon that is not in between ** the BEGIN and END of a CREATE TRIGGER statement. ** ** LIMITATIONS: ** ** {U10512} The input to sqlite3_complete() must be a zero-terminated ** UTF-8 string. ** ** {U10513} The input to sqlite3_complete16() must be a zero-terminated ** UTF-16 string in native byte order. */ int sqlite3_complete(const char *sql); int sqlite3_complete16(const void *sql); /* ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310} ** ** This routine sets a callback function that might be invoked whenever ** an attempt is made to open a database table that another thread ** or process has locked. ** ** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] ** is returned immediately upon encountering the lock. If the busy callback ** is not NULL, then the callback will be invoked with two arguments. ** ** The first argument to the handler is a copy of the void* pointer which ** is the third argument to sqlite3_busy_handler(). The second argument to ** the handler callback is the number of times that the busy handler has ** been invoked for this locking event. If the ** busy callback returns 0, then no additional attempts are made to ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. ** If the callback returns non-zero, then another attempt ** is made to open the database for reading and the cycle repeats. ** ** The presence of a busy handler does not guarantee that it will be invoked ** when there is lock contention. If SQLite determines that invoking the busy ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] ** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. ** Consider a scenario where one process is holding a read lock that ** it is trying to promote to a reserved lock and ** a second process is holding a reserved lock that it is trying ** to promote to an exclusive lock. The first process cannot proceed ** because it is blocked by the second and the second process cannot ** proceed because it is blocked by the first. If both processes ** invoke the busy handlers, neither will make any progress. Therefore, |
︙ | ︙ | |||
1437 1438 1439 1440 1441 1442 1443 | ** to promote this lock to EXCLUSIVE so that it can spill cache ** pages into the database file without harm to concurrent ** readers. If it is unable to promote the lock, then the in-memory ** cache will be left in an inconsistent state and so the error ** code is promoted from the relatively benign [SQLITE_BUSY] to ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion ** forces an automatic rollback of the changes. See the | | | | | | | | > | | < | | | | | | | | | | | | 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 | ** to promote this lock to EXCLUSIVE so that it can spill cache ** pages into the database file without harm to concurrent ** readers. If it is unable to promote the lock, then the in-memory ** cache will be left in an inconsistent state and so the error ** code is promoted from the relatively benign [SQLITE_BUSY] to ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion ** forces an automatic rollback of the changes. See the ** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError"> ** CorruptionFollowingBusyError</a> wiki page for a discussion of why ** this is important. ** ** There can only be a single busy handler defined for each ** [database connection]. Setting a new busy handler clears any ** previously set handler. Note that calling [sqlite3_busy_timeout()] ** will also set or clear the busy handler. ** ** INVARIANTS: ** ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler ** callback in the database connection identified by the 1st ** parameter with a new busy handler identified by the 2nd and 3rd ** parameters. ** ** {F12312} The default busy handler for new database connections is NULL. ** ** {F12314} When two or more database connection share a ** [sqlite3_enable_shared_cache | common cache], ** the busy handler for the database connection currently using ** the cache is invoked when the cache encounters a lock. ** ** {F12316} If a busy handler callback returns zero, then the SQLite interface ** that provoked the locking event will return [SQLITE_BUSY]. ** ** {F12318} SQLite will invokes the busy handler with two arguments which ** are a copy of the pointer supplied by the 3rd parameter to ** [sqlite3_busy_handler()] and a count of the number of prior ** invocations of the busy handler for the same locking event. ** ** LIMITATIONS: ** ** {U12319} A busy handler should not close the database connection ** or [prepared statement] that invoked the busy handler. */ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); /* ** CAPI3REF: Set A Busy Timeout {F12340} ** ** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps ** for a specified amount of time when a table is locked. The handler ** will sleep multiple times until at least "ms" milliseconds of sleeping ** have accumulated. {F12343} After "ms" milliseconds of sleeping, ** the handler returns 0 which causes [sqlite3_step()] to return ** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. ** ** Calling this routine with an argument less than or equal to zero ** turns off all busy handlers. ** ** There can only be a single busy handler for a particular ** [database connection] any any given moment. If another busy handler ** was defined (using [sqlite3_busy_handler()]) prior to calling ** this routine, that other busy handler is cleared. ** ** INVARIANTS: ** ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting ** on the same database connection. |
︙ | ︙ | |||
1523 1524 1525 1526 1527 1528 1529 | ** complete query results from one or more queries. ** ** The table conceptually has a number of rows and columns. But ** these numbers are not part of the result table itself. These ** numbers are obtained separately. Let N be the number of rows ** and M be the number of columns. ** | | | < | | | | < | | 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 | ** complete query results from one or more queries. ** ** The table conceptually has a number of rows and columns. But ** these numbers are not part of the result table itself. These ** numbers are obtained separately. Let N be the number of rows ** and M be the number of columns. ** ** A result table is an array of pointers to zero-terminated UTF-8 strings. ** There are (N+1)*M elements in the array. The first M pointers point ** to zero-terminated strings that contain the names of the columns. ** The remaining entries all point to query results. NULL values result ** in NULL pointers. All other values are in their UTF-8 zero-terminated ** string representation as returned by [sqlite3_column_text()]. ** ** A result table might consist of one or more memory allocations. ** It is not safe to pass a result table directly to [sqlite3_free()]. ** A result table should be deallocated using [sqlite3_free_table()]. ** ** As an example of the result table format, suppose a query result ** is as follows: ** ** <blockquote><pre> |
︙ | ︙ | |||
1567 1568 1569 1570 1571 1572 1573 | ** </pre></blockquote> ** ** The sqlite3_get_table() function evaluates one or more ** semicolon-separated SQL statements in the zero-terminated UTF-8 ** string of its 2nd parameter. It returns a result table to the ** pointer given in its 3rd parameter. ** | | | | | | < | | | | | < | 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 | ** </pre></blockquote> ** ** The sqlite3_get_table() function evaluates one or more ** semicolon-separated SQL statements in the zero-terminated UTF-8 ** string of its 2nd parameter. It returns a result table to the ** pointer given in its 3rd parameter. ** ** After the calling function has finished using the result, it should ** pass the pointer to the result table to sqlite3_free_table() in order to ** release the memory that was malloced. Because of the way the ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling ** function must not try to call [sqlite3_free()] directly. Only ** [sqlite3_free_table()] is able to release the memory properly and safely. ** ** The sqlite3_get_table() interface is implemented as a wrapper around ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access ** to any internal data structures of SQLite. It uses only the public ** interface defined here. As a consequence, errors that occur in the ** wrapper layer outside of the internal [sqlite3_exec()] call are not ** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then ** it frees the result table under construction, aborts the ** query in process, skips any subsequent queries, sets the ** *resultp output pointer to NULL and returns [SQLITE_NOMEM]. ** ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL ** then [sqlite3_get_table()] writes the number of columns in the ** result set of the query into *ncolumn if the query is ** successful (if the function returns SQLITE_OK). ** ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL ** then [sqlite3_get_table()] writes the number of rows in the ** result set of the query into *nrow if the query is ** successful (if the function returns SQLITE_OK). ** ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value to the ** number of columns in the result set of the query in the sql ** parameter, or to zero if the query in sql has an empty result set. */ int sqlite3_get_table( sqlite3*, /* An open database */ const char *sql, /* SQL to be evaluated */ char ***pResult, /* Results of the query */ int *nrow, /* Number of result rows written here */ int *ncolumn, /* Number of result columns written here */ |
︙ | ︙ | |||
1657 1658 1659 1660 1661 1662 1663 | ** ** The %q option works like %s in that it substitutes a null-terminated ** string from the argument list. But %q also doubles every '\'' character. ** %q is designed for use inside a string literal. By doubling each '\'' ** character it escapes that character and allows it to be inserted into ** the string. ** | | | 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 | ** ** The %q option works like %s in that it substitutes a null-terminated ** string from the argument list. But %q also doubles every '\'' character. ** %q is designed for use inside a string literal. By doubling each '\'' ** character it escapes that character and allows it to be inserted into ** the string. ** ** For example, assume the string variable zText contains text as follows: ** ** <blockquote><pre> ** char *zText = "It's a happy day!"; ** </pre></blockquote> ** ** One can use this text in an SQL statement as follows: ** |
︙ | ︙ | |||
1685 1686 1687 1688 1689 1690 1691 | ** This is correct. Had we used %s instead of %q, the generated SQL ** would have looked like this: ** ** <blockquote><pre> ** INSERT INTO table1 VALUES('It's a happy day!'); ** </pre></blockquote> ** | | | < | | | > | 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 | ** This is correct. Had we used %s instead of %q, the generated SQL ** would have looked like this: ** ** <blockquote><pre> ** INSERT INTO table1 VALUES('It's a happy day!'); ** </pre></blockquote> ** ** This second example is an SQL syntax error. As a general rule you should ** always use %q instead of %s when inserting text into a string literal. ** ** The %Q option works like %q except it also adds single quotes around ** the outside of the total string. Additionally, if the parameter in the ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without ** single quotes) in place of the %Q option. {END} So, for example, ** one could say: ** ** <blockquote><pre> ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); ** sqlite3_exec(db, zSQL, 0, 0, 0); ** sqlite3_free(zSQL); ** </pre></blockquote> ** |
︙ | ︙ | |||
1718 1719 1720 1721 1722 1723 1724 | ** memory obtained from [sqlite3_malloc()] or NULL pointers if ** a call to [sqlite3_malloc()] fails. ** ** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated ** UTF-8 string into the buffer pointed to by the second parameter ** provided that the first parameter is greater than zero. ** | | < | 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 | ** memory obtained from [sqlite3_malloc()] or NULL pointers if ** a call to [sqlite3_malloc()] fails. ** ** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated ** UTF-8 string into the buffer pointed to by the second parameter ** provided that the first parameter is greater than zero. ** ** {F17407} The [sqlite3_snprintf()] interface does not write slots of ** its output buffer (the second parameter) outside the range ** of 0 through N-1 (where N is the first parameter) ** regardless of the length of the string ** requested by the format specification. */ char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem {F17300} |
︙ | ︙ | |||
1764 1765 1766 1767 1768 1769 1770 | ** second parameter. The memory allocation to be resized is the first ** parameter. If the first parameter to sqlite3_realloc() ** is a NULL pointer then its behavior is identical to calling ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). ** If the second parameter to sqlite3_realloc() is zero or ** negative then the behavior is exactly the same as calling ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). | | | < | | < | < | | | | | < | | | | | 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 | ** second parameter. The memory allocation to be resized is the first ** parameter. If the first parameter to sqlite3_realloc() ** is a NULL pointer then its behavior is identical to calling ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). ** If the second parameter to sqlite3_realloc() is zero or ** negative then the behavior is exactly the same as calling ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). ** sqlite3_realloc() returns a pointer to a memory allocation ** of at least N bytes in size or NULL if sufficient memory is unavailable. ** If M is the size of the prior allocation, then min(N,M) bytes ** of the prior allocation are copied into the beginning of buffer returned ** by sqlite3_realloc() and the prior allocation is freed. ** If sqlite3_realloc() returns NULL, then the prior allocation ** is not freed. ** ** The memory returned by sqlite3_malloc() and sqlite3_realloc() ** is always aligned to at least an 8 byte boundary. {END} ** ** The default implementation of the memory allocation subsystem uses ** the malloc(), realloc() and free() provided by the standard C library. ** {F17382} However, if SQLite is compiled with the ** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i> ** is an integer), then SQLite create a static array of at least ** <i>NNN</i> bytes in size and uses that array for all of its dynamic ** memory allocation needs. {END} Additional memory allocator options ** may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in ** implementation of these routines to be omitted. That capability ** is no longer provided. Only built-in memory allocators can be used. ** ** The Windows OS interface layer calls ** the system malloc() and free() directly when converting ** filenames between the UTF-8 encoding used by SQLite ** and whatever filename encoding is used by the particular Windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. ** ** INVARIANTS: ** ** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to ** a newly checked-out block of at least N bytes of memory ** that is 8-byte aligned, or it returns NULL if it is unable ** to fulfill the request. ** ** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if ** N is less than or equal to zero. ** ** {F17305} The [sqlite3_free(P)] interface releases memory previously ** returned from [sqlite3_malloc()] or [sqlite3_realloc()], ** making it available for reuse. |
︙ | ︙ | |||
1832 1833 1834 1835 1836 1837 1838 | ** deallocation needs. ** ** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer ** to a block of checked-out memory of at least N bytes in size ** that is 8-byte aligned, or a NULL pointer. ** ** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first | | | > | | | < | | | | 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 | ** deallocation needs. ** ** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer ** to a block of checked-out memory of at least N bytes in size ** that is 8-byte aligned, or a NULL pointer. ** ** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** copies the first K bytes of content from P into the newly ** allocated block, where K is the lesser of N and the size of ** the buffer P. ** ** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** releases the buffer P. ** ** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is ** not modified or released. ** ** LIMITATIONS: ** ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] ** must be either NULL or else pointers obtained from a prior ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have ** not yet been released. ** ** {U17351} The application must not read or write any part of ** a block of memory after it has been released using ** [sqlite3_free()] or [sqlite3_realloc()]. */ void *sqlite3_malloc(int); void *sqlite3_realloc(void*, int); void sqlite3_free(void*); /* ** CAPI3REF: Memory Allocator Statistics {F17370} ** ** SQLite provides these two interfaces for reporting on the status ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] ** routines, which form the built-in memory allocation subsystem. ** ** INVARIANTS: ** ** {F17371} The [sqlite3_memory_used()] routine returns the ** number of bytes of memory currently outstanding ** (malloced but not freed). ** ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum ** value of [sqlite3_memory_used()] since the high-water mark ** was last reset. ** ** {F17374} The values returned by [sqlite3_memory_used()] and ** [sqlite3_memory_highwater()] include any overhead ** added by SQLite in its implementation of [sqlite3_malloc()], ** but not overhead added by the any underlying system library ** routines that [sqlite3_malloc()] may call. ** |
︙ | ︙ |