Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Trivial documentation fixes (CVS 4836) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
9819cefbd7032fe6884c6c891e8e3990 |
User & Date: | mlcreech 2008-03-07 03:20:32.000 |
Context
2008-03-07
| ||
15:34 | Cleanup the locking-style code in os_unix.c. (CVS 4837) (check-in: 40f55c09db user: drh tags: trunk) | |
03:20 | Trivial documentation fixes (CVS 4836) (check-in: 9819cefbd7 user: mlcreech tags: trunk) | |
02:20 | Add missing prefix & exec_prefix to Makefile - fixes #2979. (CVS 4835) (check-in: 4cda019b63 user: mlcreech 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.290 2008/03/07 03:20:32 mlcreech 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++. |
︙ | ︙ | |||
128 129 130 131 132 133 134 | int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** ** SQLite can be compiled with or without mutexes. When ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes | | | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** ** SQLite can be compiled with or without mutexes. When ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes ** are enabled and SQLite is threadsafe. When that macro is false, ** the mutexes are omitted. Without the mutexes, it is not safe ** to use SQLite from more than one thread. ** ** There is a measurable performance penalty for enabling mutexes. ** So if speed is of utmost importance, it makes sense to disable ** the mutexes. But for maximum safety, mutexes should be enabled. ** The default behavior is for mutexes to be enabled. |
︙ | ︙ | |||
430 431 432 433 434 435 436 | ** a related primary result code as a prefix. ** ** {F10224} Primary result code names contain a single "_" character. ** ** {F10225} Extended result code names contain two or more "_" characters. ** ** {F10226} The numeric value of an extended result code contains the | | | | 430 431 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 | ** a related primary result code as a prefix. ** ** {F10224} Primary result code names contain a single "_" character. ** ** {F10225} Extended result code names contain two or more "_" characters. ** ** {F10226} The numeric value of an extended result code contains the ** numeric value of its corresponding primary result code in ** its least significant 8 bits. */ #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) /* ** CAPI3REF: Flags For File Open Operations {F10230} ** ** These bit values are intended for use in the ** 3rd parameter to the [sqlite3_open_v2()] interface and ** in the 4th parameter to the xOpen method of the ** [sqlite3_vfs] object. */ #define SQLITE_OPEN_READONLY 0x00000001 #define SQLITE_OPEN_READWRITE 0x00000002 #define SQLITE_OPEN_CREATE 0x00000004 |
︙ | ︙ | |||
516 517 518 519 520 521 522 | #define SQLITE_LOCK_PENDING 3 #define SQLITE_LOCK_EXCLUSIVE 4 /* ** CAPI3REF: Synchronization Type Flags {F10260} ** ** When SQLite invokes the xSync() method of an | | | | 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 | #define SQLITE_LOCK_PENDING 3 #define SQLITE_LOCK_EXCLUSIVE 4 /* ** CAPI3REF: Synchronization Type Flags {F10260} ** ** When SQLite invokes the xSync() method of an ** [sqlite3_io_methods] object it uses a combination of ** these integer values as the second argument. ** ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means ** to use Mac OS-X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 #define SQLITE_SYNC_DATAONLY 0x00010 |
︙ | ︙ | |||
549 550 551 552 553 554 555 | const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; /* ** CAPI3REF: OS Interface File Virtual Methods Object {F11120} ** ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to | | | 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 | const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; /* ** CAPI3REF: OS Interface File Virtual Methods Object {F11120} ** ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to ** an instance of 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 |
︙ | ︙ | |||
647 648 649 650 651 652 653 | ** CAPI3REF: Standard File Control Opcodes {F11310} ** ** These integer constants are opcodes for the xFileControl method ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] ** interface. ** ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This | | | 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 | ** CAPI3REF: Standard File Control Opcodes {F11310} ** ** These integer constants are opcodes for the xFileControl method ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] ** interface. ** ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This ** opcode causes the xFileControl method to write the current state of ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) ** into an integer that the pArg argument points to. This capability ** is used during testing and only needs to be supported when SQLITE_TEST ** is defined. */ #define SQLITE_FCNTL_LOCKSTATE 1 |
︙ | ︙ | |||
689 690 691 692 693 694 695 | ** ** Registered sqlite3_vfs objects are kept on a linked list formed by ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface ** searches the list. ** | | | 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 | ** ** Registered sqlite3_vfs objects are kept on a linked list formed by ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface ** searches the list. ** ** The pNext field is the only field in the sqlite3_vfs ** structure that SQLite will ever modify. SQLite will only access ** or modify this field while holding a particular static mutex. ** The application should never modify anything within the sqlite3_vfs ** object once the object has been registered. ** ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. |
︙ | ︙ | |||
727 728 729 730 731 732 733 | ** <li> [SQLITE_OPEN_TRANSIENT_DB] ** <li> [SQLITE_OPEN_SUBJOURNAL] ** <li> [SQLITE_OPEN_MASTER_JOURNAL] ** </ul> {END} ** ** The file I/O implementation can use the object type flags to ** changes the way it deals with files. For example, an application | | | | | | | | | | | 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 | ** <li> [SQLITE_OPEN_TRANSIENT_DB] ** <li> [SQLITE_OPEN_SUBJOURNAL] ** <li> [SQLITE_OPEN_MASTER_JOURNAL] ** </ul> {END} ** ** The file I/O implementation can use the object type flags to ** changes the way it deals with files. For example, an application ** that does not care about crash recovery or rollback might make ** the open of a journal file a no-op. Writes to this journal would ** also be no-ops, and any attempt to read the journal would return ** SQLITE_IOERR. Or the implementation might recognize that a database ** file will be doing page-aligned sector reads and writes in a random ** order and set up its I/O subsystem accordingly. ** ** SQLite might also add one of the following flags to the xOpen ** method: ** ** <ul> ** <li> [SQLITE_OPEN_DELETEONCLOSE] ** <li> [SQLITE_OPEN_EXCLUSIVE] ** </ul> ** ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be ** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE] ** will be set for TEMP databases, journals and for subjournals. ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened ** for exclusive access. This flag is set for all files except ** for the main database file. {END} ** ** {F11148} At least szOsFile bytes of memory are allocated by SQLite ** to hold the [sqlite3_file] structure passed as the third ** argument to xOpen. {END} The xOpen method does not have to ** allocate the structure; it should just fill it in. ** ** {F11149} 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. {END} The file can be a ** directory. ** ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for ** the output buffers for xGetTempname and xFullPathname. {F11151} The exact ** size of the output buffer is also passed as a parameter to both ** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN ** should be returned. As this is handled as a fatal error by SQLite, ** vfs implementations should endeavor to prevent this by setting ** mxPathname to a sufficiently large value. ** ** 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 causes 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 { int iVersion; /* Structure version number */ |
︙ | ︙ | |||
810 811 812 813 814 815 816 | }; /* ** CAPI3REF: Flags for the xAccess VFS method {F11190} ** ** {F11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine | | | 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 | }; /* ** CAPI3REF: Flags for the xAccess VFS method {F11190} ** ** {F11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine ** what kind of permissions the xAccess method is ** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method ** simply checks to see if the file exists. {F11193} With ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see ** if the file is both readable and writable. {F11194} With ** SQLITE_ACCESS_READ the xAccess method ** checks to see if the file is readable. */ |
︙ | ︙ | |||
851 852 853 854 855 856 857 | ** 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 | | | 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 | ** 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 ** shown in the first argument. If no successful inserts ** have ever occurred on this database connection, zero is returned. ** ** If an INSERT occurs within a trigger, then the rowid of the |
︙ | ︙ | |||
891 892 893 894 895 896 897 | ** ** {F12223} The [sqlite3_last_insert_rowid()] function returns ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** ** LIMITATIONS: ** | | | | 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 | ** ** {F12223} The [sqlite3_last_insert_rowid()] function returns ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** ** LIMITATIONS: ** ** {U12232} If a separate thread does 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 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 ** mechanisms do not count as direct row changes. ** ** A "trigger context" is a scope of execution that begins and ** ends with the script of a trigger. Most SQL statements are |
︙ | ︙ | |||
983 984 985 986 987 988 989 | ** 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 | | | 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 | ** 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 change count for "DELETE FROM table" will be ** zero 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. ** |
︙ | ︙ |