From: drh Date: Sat, 1 Sep 2007 18:17:21 +0000 (+0000) Subject: Comment changes in sqlite.h.in in order to generate better capi3ref.html X-Git-Tag: version-3.6.10~1811 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4ff7fa0d679410afdfcff74cc421c8ef8f6ba0fa;p=thirdparty%2Fsqlite.git Comment changes in sqlite.h.in in order to generate better capi3ref.html documentation. (CVS 4366) FossilOrigin-Name: 280474595687bb843872f1bbc82cda3b1982085c --- diff --git a/manifest b/manifest index 11214b63c1..f2b1a84487 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Remove\scode\sfor\scalling\sthe\sSQL\sfunction\srandstr()\swith\s0\sor\s1\sargument,\sas\sit\sis\sregistered\swith\ssqlite\sas\srequiring\sexactly\s2.\sAlso\stest\sio\serrors\sin\ssqlite3_release_memory().\s(CVS\s4365) -D 2007-09-01T17:00:13 +C Comment\schanges\sin\ssqlite.h.in\sin\sorder\sto\sgenerate\sbetter\scapi3ref.html\ndocumentation.\s(CVS\s4366) +D 2007-09-01T18:17:22 F Makefile.in bfcc303429a5d9dcd552d807ee016c77427418c3 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028 @@ -130,7 +130,7 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da F src/select.c 4706a6115da1bdc09a2be5991168a6cc2c0df267 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96 F src/shell.c ac29402b538515fa4697282387be9c1205e6e9eb -F src/sqlite.h.in 090436ac9963592c2c2b4ae9e4d0bb774c722e09 +F src/sqlite.h.in aa6d84a8ed4fb83bfe266bdf7b1f9924a287746f F src/sqlite3ext.h a93f59cdee3638dc0c9c086f80df743a4e68c3cb F src/sqliteInt.h adc8a20e80ccf9eef24cc32f241a3427915a136e F src/sqliteLimit.h 1bcbbdfa856f8b71b561abb31edb864b0eca1d12 @@ -568,7 +568,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5 -P fb27692ab10b22851b265348bb6b3e1dececd60f -R 8691eaca2d86eeb9c8f0223ed070263c -U danielk1977 -Z 57e05a1c340e3f153329a367979054dc +P 5842f68c1ba838f24e9ba02c818d308540d591a4 +R 7b1c58e73d5811442454abb730c28ae4 +U drh +Z c91948583b937dd8dfc1fcc431f09e74 diff --git a/manifest.uuid b/manifest.uuid index 998e406530..67d48ab7f4 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -5842f68c1ba838f24e9ba02c818d308540d591a4 \ No newline at end of file +280474595687bb843872f1bbc82cda3b1982085c \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index b481679aea..907b2342a0 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.253 2007/08/31 18:34:59 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.254 2007/09/01 18:17:22 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -223,7 +223,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** 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. +** 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. @@ -244,9 +244,8 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** 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 that holds the error -** message. Use [sqlite3_free()] for this. If errmsg==NULL, -** then no error message is ever written. +** 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. @@ -437,7 +436,7 @@ int sqlite3_exec( ** 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 -** of their own use. The pMethods entry is a pointer to an +** 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. */ @@ -449,23 +448,26 @@ struct sqlite3_file { /* ** CAPI3REF: OS Interface File Virtual Methods Object ** -** Every open file in the [sqlite3_vfs] xOpen method contains a pointer to -** an instance of the following object. This object defines the +** 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 means that data is not -** necessarily synced to disk completely, only that all writes that -** occur before the sync complete before any writes that occur after the -** sync. The second flag is the normal fsync(). The third flag is a +** 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 -** SQLITE_LOCK_NONE, SQLITE_LOCK_READ, SQLITE_LOCK_RESERVED, -** SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE. xLock() -** increases the lock. xUnlock() decreases the lock. +** +** 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, @@ -474,16 +476,17 @@ struct sqlite3_file { ** ** 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 argument (the -** "op" argument) is intended to be an integer opcode. The third +** [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. Applications -** that define a custom xFileControl method should use opcodes +** 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 @@ -494,17 +497,17 @@ struct sqlite3_file { ** underlying device: ** ** ** ** The SQLITE_IOCAP_ATOMIC property means that all writes of @@ -576,7 +579,7 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** 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 +** 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. ** @@ -602,10 +605,10 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** 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. +** 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 +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be ** set. ** ** SQLite will also add one of the following flags to the xOpen() @@ -649,10 +652,11 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** szOsFile bytes are allocated for this object. The xOpen method ** fills in the allocated space. ** -** The flags argument to xAccess() may be 0 (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_READONLY -** to test to see if a file is read-only. The file can be a +** 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 @@ -663,7 +667,7 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** 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 generated. The +** 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 @@ -1510,7 +1514,8 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** program using one of these routines. ** ** The first argument "db" is an [sqlite3 | SQLite database handle] -** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()]. +** 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() @@ -2622,15 +2627,15 @@ int sqlite3_sleep(int); ** is NULL pointer, then SQLite does a search for an appropriate temporary ** file directory. ** -** Once [sqlite3_open()] has been called, changing this variable will -** invalidate the current temporary database, if any. Generally speaking, -** it is not safe to invoke this routine after [sqlite3_open()] has -** been called. +** 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 Databse Is In Auto-Commit Mode +** 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 @@ -2728,14 +2733,16 @@ void *sqlite3_update_hook( ** 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 +** 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 for backward compatibility. +** 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); @@ -2745,9 +2752,6 @@ int sqlite3_enable_shared_cache(int); ** 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). -** -** This function is not a part of standard builds. It is only created -** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. */ int sqlite3_release_memory(int); @@ -2783,7 +2787,7 @@ int sqlite3_release_memory(int); ** 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 bound on the total memory allocation for all threads. In +** 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. */ @@ -3485,6 +3489,8 @@ int sqlite3_mutex_notheld(sqlite3_mutex*); ** 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*);