Documentation improvements in sqlite.h.in. No changes to code.
FossilOrigin-Name: a6f39181a7b3083ae46cffd7aee7db895b4df8a4
This commit is contained in:
drh
parent
6c53320320
commit
6aa5f152a3
24
manifest
24
manifest
@ -1,5 +1,8 @@
|
||||
C Adjust\ssync\scount\sfor\sSQLITE_DISABLE_DIRSYNC\scompiler\soption.
|
||||
D 2009-08-19T04:24:48
|
||||
-----BEGIN PGP SIGNED MESSAGE-----
|
||||
Hash: SHA1
|
||||
|
||||
C Documentation\simprovements\sin\ssqlite.h.in.\s\sNo\schanges\sto\scode.
|
||||
D 2009-08-19T15:57:08
|
||||
F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
|
||||
F Makefile.in 0f7761c5d1c62ae7a841e3393ffaff1fa0f5c00a
|
||||
F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
|
||||
@ -161,7 +164,7 @@ F src/resolve.c 4a61d03e49b15440878096e6030863fc628828f0
|
||||
F src/rowset.c c64dafba1f9fd876836c8db8682966b9d197eb1f
|
||||
F src/select.c 67b0778c9585905c8aa75aaa469e76ef3c1d315a
|
||||
F src/shell.c db2643650b9268df89a4bedca3f1c6d9e786f1bb
|
||||
F src/sqlite.h.in 393349b50ab4a22ed740a9f8cc4237d17e81e7b4
|
||||
F src/sqlite.h.in 3ccf717d82101f19548d0b1243f0a6f4854d51ee
|
||||
F src/sqlite3ext.h 1db7d63ab5de4b3e6b83dd03d1a4e64fef6d2a17
|
||||
F src/sqliteInt.h d675e20da30db2c28e7166deb1fc758fb5b29a9a
|
||||
F src/sqliteLimit.h ffe93f5a0c4e7bd13e70cd7bf84cfb5c3465f45d
|
||||
@ -746,7 +749,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
|
||||
F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
|
||||
F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
|
||||
F tool/vdbe-compress.tcl 672f81d693a03f80f5ae60bfefacd8a349e76746
|
||||
P 093917d7fda442012dfd1a1b2f20f85d2eefa093
|
||||
R bd2ad6ef6f8298aaa392cef396e66c78
|
||||
U shane
|
||||
Z 8a5e7a3b12f153b47f147ba40f17579d
|
||||
P 709e16145e37940cb243eede75071fb15095d960
|
||||
R 826b929a3a8cf85b7d98d0f8ef95004e
|
||||
U drh
|
||||
Z 34436c77187f1f7c6f3ba769592974b4
|
||||
-----BEGIN PGP SIGNATURE-----
|
||||
Version: GnuPG v1.4.6 (GNU/Linux)
|
||||
|
||||
iD8DBQFKjCDXoxKgR168RlERAgBaAJ44m8/HPKZAOF1i7vTi2B+cf3uYnwCgjZp4
|
||||
FFl5KHEGM2pvi2W+2/k0MT0=
|
||||
=XAeg
|
||||
-----END PGP SIGNATURE-----
|
||||
|
||||
@ -1 +1 @@
|
||||
709e16145e37940cb243eede75071fb15095d960
|
||||
a6f39181a7b3083ae46cffd7aee7db895b4df8a4
|
||||
101
src/sqlite.h.in
101
src/sqlite.h.in
@ -93,14 +93,23 @@ extern "C" {
|
||||
** The Z value is the release number and is incremented with
|
||||
** each release but resets back to 0 whenever Y is incremented.
|
||||
**
|
||||
** The SQLITE_VERSION_NUMBER is an integer that is computed as
|
||||
** follows:
|
||||
**
|
||||
** <blockquote><pre>
|
||||
** SQLITE_VERSION_NUMBER = X*1000000 + Y*1000 + Z
|
||||
** </pre></blockquote>
|
||||
**
|
||||
** Since version 3.6.18, SQLite source code has been stored in the
|
||||
** "fossil" configuration management system. The SQLITE_SOURCE_ID
|
||||
** <a href="http://www.fossil-scm.org/">fossil configuration management
|
||||
** system</a>. The SQLITE_SOURCE_ID
|
||||
** macro is a string which identifies a particular check-in of SQLite
|
||||
** within its configuration management system. The string contains the
|
||||
** date and time of the check-in (UTC) and an SHA1 hash of the entire
|
||||
** source tree.
|
||||
**
|
||||
** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
|
||||
** See also: [sqlite3_libversion()],
|
||||
** [sqlite3_libversion_number()], and [sqlite3_sourceid()].
|
||||
**
|
||||
** Requirements: [H10011] [H10014]
|
||||
*/
|
||||
@ -115,9 +124,14 @@ extern "C" {
|
||||
** These interfaces provide the same information as the [SQLITE_VERSION],
|
||||
** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] #defines in the header,
|
||||
** but are associated with the library instead of the header file. Cautious
|
||||
** programmers might include a check in their application to verify that
|
||||
** programmers might include an assert in their application to verify that
|
||||
** sqlite3_libversion_number() always returns the value
|
||||
** [SQLITE_VERSION_NUMBER].
|
||||
** [SQLITE_VERSION_NUMBER] and thus insure that the application is
|
||||
** compiled with matching library and header files.
|
||||
**
|
||||
** <blockquote><pre>
|
||||
** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
|
||||
** </pre></blockquote>
|
||||
**
|
||||
** The sqlite3_libversion() function returns the same information as is
|
||||
** in the sqlite3_version[] string constant. The function is provided
|
||||
@ -137,7 +151,7 @@ int sqlite3_libversion_number(void);
|
||||
** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
|
||||
**
|
||||
** SQLite can be compiled with or without mutexes. When
|
||||
** the [SQLITE_THREADSAFE] C preprocessor macro 1 or 2, mutexes
|
||||
** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
|
||||
** are enabled and SQLite is threadsafe. When the
|
||||
** [SQLITE_THREADSAFE] macro is 0,
|
||||
** the mutexes are omitted. Without the mutexes, it is not safe
|
||||
@ -148,7 +162,7 @@ int sqlite3_libversion_number(void);
|
||||
** the mutexes. But for maximum safety, mutexes should be enabled.
|
||||
** The default behavior is for mutexes to be enabled.
|
||||
**
|
||||
** This interface can be used by a program to make sure that the
|
||||
** This interface can be used by an application to make sure that the
|
||||
** version of SQLite that it is linking against was compiled with
|
||||
** the desired setting of the [SQLITE_THREADSAFE] macro.
|
||||
**
|
||||
@ -482,8 +496,9 @@ int sqlite3_exec(
|
||||
/*
|
||||
** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
|
||||
**
|
||||
** An [sqlite3_file] object represents an open file in the OS
|
||||
** interface layer. Individual OS interface implementations will
|
||||
** An [sqlite3_file] object represents an open file in the
|
||||
** [sqlite3_vfs | 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
|
||||
@ -860,7 +875,8 @@ struct sqlite3_vfs {
|
||||
** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
|
||||
** implementations for sqlite3_os_init() and sqlite3_os_end()
|
||||
** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
|
||||
** When built for other platforms (using the [SQLITE_OS_OTHER=1] compile-time
|
||||
** When [custom builds | built for other platforms]
|
||||
** (using the [SQLITE_OS_OTHER=1] compile-time
|
||||
** option) the application must supply a suitable implementation for
|
||||
** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
|
||||
** implementation of sqlite3_os_init() or sqlite3_os_end()
|
||||
@ -941,13 +957,15 @@ SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
|
||||
** This object is used in only one place in the SQLite interface.
|
||||
** A pointer to an instance of this object is the argument to
|
||||
** [sqlite3_config()] when the configuration option is
|
||||
** [SQLITE_CONFIG_MALLOC]. By creating an instance of this object
|
||||
** and passing it to [sqlite3_config()] during configuration, an
|
||||
** application can specify an alternative memory allocation subsystem
|
||||
** for SQLite to use for all of its dynamic memory needs.
|
||||
** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
|
||||
** By creating an instance of this object
|
||||
** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
|
||||
** during configuration, an application can specify an alternative
|
||||
** memory allocation subsystem for SQLite to use for all of its
|
||||
** dynamic memory needs.
|
||||
**
|
||||
** Note that SQLite comes with a built-in memory allocator that is
|
||||
** perfectly adequate for the overwhelming majority of applications
|
||||
** Note that SQLite comes with several [built-in memory allocators]
|
||||
** that are perfectly adequate for the overwhelming majority of applications
|
||||
** and that this object is only useful to a tiny minority of applications
|
||||
** with specialized memory allocation requirements. This object is
|
||||
** also used during testing of SQLite in order to specify an alternative
|
||||
@ -955,8 +973,16 @@ SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
|
||||
** order to verify that SQLite recovers gracefully from such
|
||||
** conditions.
|
||||
**
|
||||
** The xMalloc, xFree, and xRealloc methods must work like the
|
||||
** malloc(), free(), and realloc() functions from the standard library.
|
||||
** The xMalloc and xFree methods must work like the
|
||||
** malloc() and free() functions from the standard C library.
|
||||
** The xRealloc method must work like realloc() from the standard C library
|
||||
** with the exception that if the second argument to xRealloc is zero,
|
||||
** xRealloc must be a no-op - it must not perform any allocation or
|
||||
** deallocation. SQLite guaranteeds that the second argument to
|
||||
** xRealloc is always a value returned by a prior call to xRoundup.
|
||||
** And so in cases where xRoundup always returns a positive number,
|
||||
** xRealloc can perform exactly as the standard library realloc() and
|
||||
** still be in compliance with this specification.
|
||||
**
|
||||
** xSize should return the allocated size of a memory allocation
|
||||
** previously obtained from xMalloc or xRealloc. The allocated size
|
||||
@ -966,6 +992,9 @@ SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
|
||||
** a memory allocation given a particular requested size. Most memory
|
||||
** allocators round up memory allocations at least to the next multiple
|
||||
** of 8. Some allocators round up to a larger multiple or to a power of 2.
|
||||
** Every memory allocation request coming in through [sqlite3_malloc()]
|
||||
** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
|
||||
** that causes the corresponding memory allocation to fail.
|
||||
**
|
||||
** The xInit method initializes the memory allocator. (For example,
|
||||
** it might allocate any require mutexes or initialize internal data
|
||||
@ -977,8 +1006,13 @@ SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
|
||||
** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
|
||||
** the xInit method, so the xInit method need not be threadsafe. The
|
||||
** xShutdown method is only called from [sqlite3_shutdown()] so it does
|
||||
** not need to be threadsafe either. All other methods must be threadsafe
|
||||
** in multithreaded applications.
|
||||
** not need to be threadsafe either. For all other methods, SQLite
|
||||
** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
|
||||
** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
|
||||
** it is by default) and so the methods are automatically serialized.
|
||||
** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
|
||||
** methods must be threadsafe or else make their own arrangements for
|
||||
** serialization.
|
||||
**
|
||||
** SQLite will never invoke xInit() more than once without an intervening
|
||||
** call to xShutdown().
|
||||
@ -1135,9 +1169,12 @@ struct sqlite3_mem_methods {
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
|
||||
** <dd>This option takes two arguments that determine the default
|
||||
** memory allcation lookaside optimization. The first argument is the
|
||||
** memory allocation lookaside optimization. The first argument is the
|
||||
** size of each lookaside buffer slot and the second is the number of
|
||||
** slots allocated to each database connection.</dd>
|
||||
** slots allocated to each database connection. This option sets the
|
||||
** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
|
||||
** verb to [sqlite3_db_config()] can be used to change the lookaside
|
||||
** configuration on individual connections.</dd>
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_PCACHE</dt>
|
||||
** <dd>This option takes a single argument which is a pointer to
|
||||
@ -1187,12 +1224,15 @@ struct sqlite3_mem_methods {
|
||||
** <dd>This option takes three additional arguments that determine the
|
||||
** [lookaside memory allocator] configuration for the [database connection].
|
||||
** The first argument (the third parameter to [sqlite3_db_config()] is a
|
||||
** pointer to an 8-byte aligned memory buffer to use for lookaside memory.
|
||||
** pointer to an memory buffer to use for lookaside memory.
|
||||
** The first argument may be NULL in which case SQLite will allocate the
|
||||
** lookaside buffer itself using [sqlite3_malloc()]. The second argument is the
|
||||
** size of each lookaside buffer slot and the third argument is the number of
|
||||
** slots. The size of the buffer in the first argument must be greater than
|
||||
** or equal to the product of the second and third arguments.</dd>
|
||||
** or equal to the product of the second and third arguments. The buffer
|
||||
** must be aligned to an 8-byte boundary. If the second argument is not
|
||||
** a multiple of 8, it is internally rounded down to the next smaller
|
||||
** multiple of 8. See also: [SQLITE_CONFIG_LOOKASIDE]</dd>
|
||||
**
|
||||
** </dl>
|
||||
*/
|
||||
@ -3123,7 +3163,7 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
|
||||
** [SQLITE_UTF8 | text encoding] this SQL function prefers for
|
||||
** its parameters. Any SQL function implementation should be able to work
|
||||
** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
|
||||
** more efficient with one encoding than another. It is allowed to
|
||||
** more efficient with one encoding than another. An application may
|
||||
** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
|
||||
** times with the same function but with different values of eTextRep.
|
||||
** When multiple implementations of the same function are available, SQLite
|
||||
@ -3145,7 +3185,7 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
|
||||
** It is permitted to register multiple implementations of the same
|
||||
** functions with the same name but with either differing numbers of
|
||||
** arguments or differing preferred text encodings. SQLite will use
|
||||
** the implementation most closely matches the way in which the
|
||||
** the implementation that most closely matches the way in which the
|
||||
** SQL function is used. A function implementation with a non-negative
|
||||
** nArg parameter is a better match than a function implementation with
|
||||
** a negative nArg. A function where the preferred text encoding
|
||||
@ -5002,7 +5042,7 @@ int sqlite3_test_control(int op, ...);
|
||||
** This routine returns SQLITE_OK on success and a non-zero
|
||||
** [error code] on failure.
|
||||
**
|
||||
** This routine is threadsafe but is not atomic. This routine can
|
||||
** This routine is threadsafe but is not atomic. This routine can be
|
||||
** called while other threads are running the same or different SQLite
|
||||
** interfaces. However the values returned in *pCurrent and
|
||||
** *pHighwater reflect the status of SQLite at different points in time
|
||||
@ -5125,7 +5165,14 @@ SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiw
|
||||
** CAPI3REF: Status Parameters for database connections {H17520} <H17500>
|
||||
** EXPERIMENTAL
|
||||
**
|
||||
** Status verbs for [sqlite3_db_status()].
|
||||
** These constants are the available integer "verbs" that can be passed as
|
||||
** the second argument to the [sqlite3_db_status()] interface.
|
||||
**
|
||||
** New verbs may be added in future releases of SQLite. Existing verbs
|
||||
** might be discontinued. Applications should check the return code from
|
||||
** [sqlite3_db_status()] to make sure that the call worked.
|
||||
** The [sqlite3_db_status()] interface will return a non-zero error code
|
||||
** if a discontinued or unsupported verb is invoked.
|
||||
**
|
||||
** <dl>
|
||||
** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user