Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Comment changes in sqlite.h.in in order to generate better capi3ref.html documentation. (CVS 4366) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
280474595687bb843872f1bbc82cda3b |
User & Date: | drh 2007-09-01 18:17:22.000 |
Context
2007-09-01
| ||
18:24 | Fix a bug in jrnlTruncate(). And other coverage improvements. (CVS 4367) (check-in: 02b751fb9d user: danielk1977 tags: trunk) | |
18:17 | Comment changes in sqlite.h.in in order to generate better capi3ref.html documentation. (CVS 4366) (check-in: 2804745956 user: drh tags: trunk) | |
17:00 | Remove code for calling the SQL function randstr() with 0 or 1 argument, as it is registered with sqlite as requiring exactly 2. Also test io errors in sqlite3_release_memory(). (CVS 4365) (check-in: 5842f68c1b 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.254 2007/09/01 18:17:22 drh 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++. |
︙ | ︙ | |||
219 220 221 222 223 224 225 | ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. ** ** If one or more of the SQL statements are queries, then ** the callback function specified by the 3rd parameter is ** invoked once for each row of the query result. This callback ** should normally return 0. If the callback returns a non-zero ** value then the query is aborted, all subsequent SQL statements | | | < | | 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 | ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. ** ** If one or more of the SQL statements are queries, then ** the callback function specified by the 3rd parameter is ** invoked once for each row of the query result. This callback ** should normally return 0. If the callback returns a non-zero ** value then the query is aborted, all subsequent SQL statements ** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT]. ** ** The 4th parameter to this interface is an arbitrary pointer that is ** passed through to the callback function as its first parameter. ** ** The 2nd parameter to the callback function is the number of ** columns in the query result. The 3rd parameter to the callback ** is an array of strings holding the values for each column ** as extracted using [sqlite3_column_text()]. ** The 4th parameter to the callback is an array of strings ** obtained using [sqlite3_column_name()] and holding ** the names of each column. ** ** The callback function may be NULL, even for queries. A NULL ** callback is not an error. It just means that no callback ** will be invoked. ** ** If an error occurs while parsing or evaluating the SQL (but ** not while executing the callback) then an appropriate error ** message is written into memory obtained from [sqlite3_malloc()] and ** *errmsg is made to point to that message. The calling function ** is responsible for freeing the memory using [sqlite3_free()]. ** If errmsg==NULL, then no error message is ever written. ** ** The return value is is SQLITE_OK if there are no errors and ** some other [SQLITE_OK | return code] if there is an error. ** The particular return value depends on the type of error. ** */ int sqlite3_exec( |
︙ | ︙ | |||
433 434 435 436 437 438 439 | /* ** CAPI3REF: OS Interface Open File Handle ** ** An [sqlite3_file] object represents an open file in the OS ** interface layer. Individual OS interface implementations will ** want to subclass this object by appending additional fields | | | | | | < < | > > > | > | > | | | | > | | | | | | | | | | | | | 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 | /* ** CAPI3REF: OS Interface Open File Handle ** ** An [sqlite3_file] object represents an open file in the OS ** interface layer. Individual OS interface implementations will ** want to subclass this object by appending additional fields ** for their own use. The pMethods entry is a pointer to an ** [sqlite3_io_methods] object that defines methods for performing ** I/O operations on the open file. */ typedef struct sqlite3_file sqlite3_file; struct sqlite3_file { const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; /* ** CAPI3REF: OS Interface File Virtual Methods Object ** ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to ** an instance of the this object. This object defines the ** methods used to perform various operations against the open file. ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). * The second choice is an ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to ** indicate that only the data of the file and not its inode needs to be ** synced. ** ** The integer values to xLock() and xUnlock() are one of ** <ul> ** <li> [SQLITE_LOCK_NONE], ** <li> [SQLITE_LOCK_READ], ** <li> [SQLITE_LOCK_RESERVED], ** <li> [SQLITE_LOCK_PENDING], or ** <li> [SQLITE_LOCK_EXCLUSIVE]. ** </ul> ** xLock() increases the lock. xUnlock() decreases the lock. ** The xCheckReservedLock() method looks ** to see if any database connection, either in this ** process or in some other process, is holding an RESERVED, ** PENDING, or EXCLUSIVE lock on the file. It returns true ** if such a lock exists and false if not. ** ** The xFileControl() method is a generic interface that allows custom ** VFS implementations to directly control an open file using the ** [sqlite3_file_control()] interface. The second "op" argument ** is an integer opcode. The third ** argument is a generic pointer which is intended to be a pointer ** to a structure that may contain arguments or space in which to ** write return values. Potential uses for xFileControl() might be ** functions to enable blocking locks with timeouts, to change the ** locking strategy (for example to use dot-file locks), to inquire ** about the status of a lock, or to break stale locks. The SQLite ** core reserves opcodes less than 100 for its own use. ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. ** Applications that define a custom xFileControl method should use opcodes ** greater than 100 to avoid conflicts. ** ** The xSectorSize() method returns the sector size of the ** device that underlies the file. The sector size is the ** minimum write that can be performed without disturbing ** other bytes in the file. The xDeviceCharacteristics() ** method returns a bit vector describing behaviors of the ** underlying device: ** ** <ul> ** <li> [SQLITE_IOCAP_ATOMIC] ** <li> [SQLITE_IOCAP_ATOMIC512] ** <li> [SQLITE_IOCAP_ATOMIC1K] ** <li> [SQLITE_IOCAP_ATOMIC2K] ** <li> [SQLITE_IOCAP_ATOMIC4K] ** <li> [SQLITE_IOCAP_ATOMIC8K] ** <li> [SQLITE_IOCAP_ATOMIC16K] ** <li> [SQLITE_IOCAP_ATOMIC32K] ** <li> [SQLITE_IOCAP_ATOMIC64K] ** <li> [SQLITE_IOCAP_SAFE_APPEND] ** <li> [SQLITE_IOCAP_SEQUENTIAL] ** </ul> ** ** The SQLITE_IOCAP_ATOMIC property means that all writes of ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values ** mean that writes of blocks that are nnn bytes in size and ** are aligned to an address which is an integer multiple of ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
︙ | ︙ | |||
572 573 574 575 576 577 578 | ** SQLite core and the underlying operating system. The "vfs" ** in the name of the object stands for "virtual file system". ** ** The iVersion field is initially 1 but may be larger for future ** versions of SQLite. Additional fields may be appended to this ** object when the iVersion value is increased. ** | | | 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 | ** SQLite core and the underlying operating system. The "vfs" ** in the name of the object stands for "virtual file system". ** ** The iVersion field is initially 1 but may be larger for future ** versions of SQLite. Additional fields may be appended to this ** object when the iVersion value is increased. ** ** The szOsFile field is the size of the subclassed [sqlite3_file] ** structure used by this VFS. mxPathname is the maximum length of ** a pathname in this VFS. ** ** Registered vfs modules are kept on a linked list formed by ** the pNext pointer. The [sqlite3_register_vfs()] ** and [sqlite3_unregister_vfs()] interfaces manage this list ** in a thread-safe way. The [sqlite3_find_vfs()] interface |
︙ | ︙ | |||
598 599 600 601 602 603 604 | ** SQLite will guarantee that the zFilename string passed to ** xOpen() is a full pathname as generated by xFullPathname() and ** that the string will be valid and unchanged until xClose() is ** called. So the [sqlite3_file] can store a pointer to the ** filename if it needs to remember the filename for some reason. ** ** The flags argument to xOpen() is a copy of the flags argument | | | | | 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 | ** SQLite will guarantee that the zFilename string passed to ** xOpen() is a full pathname as generated by xFullPathname() and ** that the string will be valid and unchanged until xClose() is ** called. So the [sqlite3_file] can store a pointer to the ** filename if it needs to remember the filename for some reason. ** ** The flags argument to xOpen() is a copy of the flags argument ** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()] ** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. ** If xOpen() opens a file read-only then it sets *pOutFlags to ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be ** set. ** ** SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: ** ** <ul> ** <li> [SQLITE_OPEN_MAIN_DB] |
︙ | ︙ | |||
645 646 647 648 649 650 651 | ** for the main database file. ** ** Space to hold the [sqlite3_file] structure passed as the third ** argument to xOpen is allocated by caller (the SQLite core). ** szOsFile bytes are allocated for this object. The xOpen method ** fills in the allocated space. ** | | > | | | | | 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 | ** for the main database file. ** ** Space to hold the [sqlite3_file] structure passed as the third ** argument to xOpen is allocated by caller (the SQLite core). ** szOsFile bytes are allocated for this object. The xOpen method ** fills in the allocated space. ** ** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] ** to test for the existance of a file, ** or [SQLITE_ACCESS_READWRITE] to test to see ** if a file is readable and writable, or [SQLITE_ACCESS_READ] ** to test to see if a file is at least readable. The file can be a ** directory. ** ** SQLite will always allocate at least mxPathname+1 byte for ** the output buffers for xGetTempName and xFullPathname. ** ** The xRandomness(), xSleep(), and xCurrentTime() interfaces ** are not strictly a part of the filesystem, but they are ** included in the VFS structure for completeness. ** The xRandomness() function attempts to return nBytes bytes ** of good-quality randomness into zOut. The return value is ** the actual number of bytes of randomness obtained. The ** xSleep() method cause the calling thread to sleep for at ** least the number of microseconds given. The xCurrentTime() ** method returns a Julian Day Number for the current date and ** time. */ typedef struct sqlite3_vfs sqlite3_vfs; struct sqlite3_vfs { |
︙ | ︙ | |||
1506 1507 1508 1509 1510 1511 1512 | /* ** CAPI3REF: Compiling An SQL Statement ** ** To execute an SQL query, it must first be compiled into a byte-code ** program using one of these routines. ** ** The first argument "db" is an [sqlite3 | SQLite database handle] | | > | 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 | /* ** CAPI3REF: Compiling An SQL Statement ** ** To execute an SQL query, it must first be compiled into a byte-code ** program using one of these routines. ** ** The first argument "db" is an [sqlite3 | SQLite database handle] ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] ** or [sqlite3_open16()]. ** The second argument "zSql" is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16. ** ** If the nByte argument is less ** than zero, then zSql is read up to the first zero terminator. If |
︙ | ︙ | |||
2618 2619 2620 2621 2622 2623 2624 | ** ** If this global variable is made to point to a string which is ** the name of a folder (a.ka. directory), then all temporary files ** created by SQLite will be placed in that directory. If this variable ** is NULL pointer, then SQLite does a search for an appropriate temporary ** file directory. ** | | | | | | | 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 | ** ** If this global variable is made to point to a string which is ** the name of a folder (a.ka. directory), then all temporary files ** created by SQLite will be placed in that directory. If this variable ** is NULL pointer, then SQLite does a search for an appropriate temporary ** file directory. ** ** It is not safe to modify this variable once a database connection ** 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 ** ** Test to see whether or not the database connection is in autocommit ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on ** by default. Autocommit is disabled by a BEGIN statement and reenabled ** by the next COMMIT or ROLLBACK. ** ** If another thread changes the autocommit status of the database |
︙ | ︙ | |||
2724 2725 2726 2727 2728 2729 2730 | ** ** The cache sharing mode set by this interface effects all subsequent ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. ** Existing database connections continue use the sharing mode that was ** in effect at the time they were opened. ** ** Virtual tables cannot be used with a shared cache. When shared | | | > > < < < | 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 | ** ** The cache sharing mode set by this interface effects all subsequent ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. ** Existing database connections continue use the sharing mode that was ** in effect at the time they were opened. ** ** Virtual tables cannot be used with a shared cache. When shared ** cache is enabled, the [sqlite3_create_module()] API used to register ** virtual tables will always return an error. ** ** This routine returns [SQLITE_OK] if shared cache was ** enabled or disabled successfully. An [SQLITE_ERROR | 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. */ int sqlite3_enable_shared_cache(int); /* ** CAPI3REF: Attempt To Free Heap Memory ** ** Attempt to free N bytes of heap memory by deallocating non-essential ** memory allocations held by the database library (example: memory ** used to cache database pages to improve performance). */ int sqlite3_release_memory(int); /* ** CAPI3REF: Impose A Limit On Heap Size ** ** Place a "soft" limit on the amount of heap memory that may be allocated |
︙ | ︙ | |||
2779 2780 2781 2782 2783 2784 2785 | ** memory alarm interface it will interfere with the operation of the ** soft heap limit and undefined behavior will result. ** ** 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 ** applied to all threads. The value specified for the soft heap limit | | | 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 | ** memory alarm interface it will interfere with the operation of the ** soft heap limit and undefined behavior will result. ** ** 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 ** applied to all threads. The value specified for the soft heap limit ** is an upper bound on the total memory allocation for all threads. In ** version 3.5.0 there is no mechanism for limiting the heap usage for ** individual threads. */ void sqlite3_soft_heap_limit(int); /* ** CAPI3REF: Extract Metadata About A Column Of A Table |
︙ | ︙ | |||
3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 | ** If the second parameter (zDbName) does not match the name of any ** open database file, then SQLITE_ERROR is returned. This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] ** or [sqlite3_errmsg()]. The underlying xFileControl method might ** also return SQLITE_ERROR. There is no way to distinguish between ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. */ int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); /* ** Undo the hack that converts floating point types to integer for ** builds on processors without floating point support. */ | > > | 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 | ** If the second parameter (zDbName) does not match the name of any ** open database file, then SQLITE_ERROR is returned. This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] ** or [sqlite3_errmsg()]. The underlying xFileControl method might ** also return SQLITE_ERROR. There is no way to distinguish between ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. ** ** See also: [SQLITE_FCNTL_LOCKSTATE] */ int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); /* ** Undo the hack that converts floating point types to integer for ** builds on processors without floating point support. */ |
︙ | ︙ |