** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
-** @(#) $Id: sqlite.h.in,v 1.350 2008/06/22 09:55:14 mihailim Exp $
+** @(#) $Id: sqlite.h.in,v 1.351 2008/06/22 10:21:27 mihailim Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
** {F11141} 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. {END} So the [sqlite3_file] can store a pointer to the
+** called. {END} So the [sqlite3_file] can store a pointer to the
** filename if it needs to remember the filename for some reason.
**
** {F11142} The flags argument to xOpen() includes all bits set in
** {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}
+** for the main database file.
**
** {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
+** 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 existence of a file, or [SQLITE_ACCESS_READWRITE] to
** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
-** to test whether a file is at least readable. {END} The file can be a
+** to test whether 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 buffer xFullPathname. {F11151} The exact size of the output buffer
-** is also passed as a parameter to both methods. {END} If 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. Since this is
** handled as a fatal error by SQLite, vfs implementations should endeavor
** to prevent this by setting mxPathname to a sufficiently large value.
**
** {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.
+** what kind of permissions the xAccess method is looking for.
+** {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
+** simply checks whether the file exists.
+** {F11193} With SQLITE_ACCESS_READWRITE, the xAccess method
+** checks whether the file is both readable and writable.
+** {F11194} With SQLITE_ACCESS_READ, the xAccess method
+** checks whether the file is readable.
*/
#define SQLITE_ACCESS_EXISTS 0
#define SQLITE_ACCESS_READWRITE 1
** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
** results into memory obtained from [sqlite3_malloc()].
** The strings returned by these two routines should be
-** released by [sqlite3_free()]. Both routines return a
+** released by [sqlite3_free()]. Both routines return a
** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
** memory to hold the resulting string.
**
** 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:
+** single quotes) in place of the %Q option. So, for example, one could say:
**
** <blockquote><pre>
** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
** argument to sqlite3_progress_handler().
**
** {F12914} The fourth argument to sqlite3_progress_handler() is a
-*** void pointer passed to the progress callback
+** void pointer passed to the progress callback
** function each time it is invoked.
**
-** {F12915} If a call to [sqlite3_step()] results in fewer than
-** N opcodes being executed,
-** then the progress callback is never invoked. {END}
+** {F12915} If a call to [sqlite3_step()] results in fewer than N opcodes
+** being executed, then the progress callback is never invoked.
**
** {F12916} Every call to [sqlite3_progress_handler()]
** overwrites any previously registered progress handler.
** 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 use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
-** use UTF-16.{END}
+** use UTF-16.
**
** If the nByte argument is less than zero, then zSql is read up to the
** first zero terminator. If nByte is non-negative, then it is the maximum
** that the supplied string is nul-terminated, then there is a small
** performance advantage to be gained by passing an nByte parameter that
** is equal to the number of bytes in the input string <i>including</i>
-** the nul-terminator bytes.{END}
+** the nul-terminator bytes.
**
** *pzTail is made to point to the first byte past the end of the
** first SQL statement in zSql. These routines only compile the first
** for backwards compatibility, but their use is discouraged.
** In the "v2" interfaces, the prepared statement
** that is returned (the [sqlite3_stmt] object) contains a copy of the
-** original SQL text. {END} This causes the [sqlite3_step()] interface to
+** original SQL text. This causes the [sqlite3_step()] interface to
** behave a differently in two ways:
**
** <ol>
** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
** error go away. Note: use [sqlite3_errmsg()] to find the text
-** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
+** of the parsing error that results in an [SQLITE_SCHEMA] return.
** </li>
**
** <li>
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
/*
-** CAPI3REF: Evaluate An SQL Statement {F13200}
+** CAPI3REF: Evaluate An SQL Statement {F13200}
**
** After a [prepared statement] has been prepared using either
** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
**
** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
** even empty strings, are always zero terminated. The return
-** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
+** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
** pointer, possibly even a NULL pointer.
**
** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
** The pointers returned are valid until a type conversion occurs as
** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
** [sqlite3_finalize()] is called. The memory space used to hold strings
-** and blobs is freed automatically. Do <b>not</b> pass the pointers returned
+** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
** [sqlite3_free()].
**
** The remaining arguments to the application-supplied routine are two strings,
** each represented by a (length, data) pair and encoded in the encoding
** that was passed as the third argument when the collation sequence was
-** registered. {END} The application defined collation routine should
+** registered. {END} The application defined collation routine should
** return negative, zero or positive if the first string is less than,
** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
**
);
/*
-** CAPI3REF: Suspend Execution For A Short Time {F10530}
+** CAPI3REF: Suspend Execution For A Short Time {F10530}
**
** The sqlite3_sleep() function causes the current thread to suspend execution
** for at least a number of milliseconds specified in its parameter.
int sqlite3_sleep(int);
/*
-** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}
+** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}
**
** If this global variable is made to point to a string which is
** the name of a folder (a.k.a. directory), then all temporary files
**
** The sqlite3_get_autocommit() interface returns non-zero or
** zero if the given database connection is or is not in autocommit mode,
-** respectively. Autocommit mode is on by default.
+** respectively. Autocommit mode is on by default.
** Autocommit mode is disabled by a [BEGIN] statement.
** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
**
** statement.
**
** LIMITATIONS:
-***
+**
** {U12936} If another thread changes the autocommit status of the database
** connection while this routine is running, then the return value
** is undefined.
int sqlite3_get_autocommit(sqlite3*);
/*
-** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
+** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
**
** The sqlite3_db_handle interface returns the [database connection] handle
** to which a [prepared statement] belongs. The database handle returned by
sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
/*
-** CAPI3REF: Find the next prepared statement {F13140}
+** CAPI3REF: Find the next prepared statement {F13140}
**
** This interface returns a pointer to the next [prepared statement] after
** pStmt associated with the [database connection] pDb. If pStmt is NULL
);
/*
-** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
+** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
** KEYWORDS: {shared cache} {shared cache mode}
**
** This routine enables or disables the sharing of the database cache
int sqlite3_enable_shared_cache(int);
/*
-** CAPI3REF: Attempt To Free Heap Memory {F17340}
+** CAPI3REF: Attempt To Free Heap Memory {F17340}
**
-** The sqlite3_release_memory() interface attempts to
-** free N bytes of heap memory by deallocating non-essential memory
-** allocations held by the database library. {END} Memory used
-** to cache database pages to improve performance is an example of
-** non-essential memory. Sqlite3_release_memory() returns
-** the number of bytes actually freed, which might be more or less
-** than the amount requested.
+** The sqlite3_release_memory() interface attempts to free N bytes
+** of heap memory by deallocating non-essential memory allocations
+** held by the database library. {END} Memory used to cache database
+** pages to improve performance is an example of non-essential memory.
+** sqlite3_release_memory() returns the number of bytes actually freed,
+** which might be more or less than the amount requested.
**
** INVARIANTS:
**
int sqlite3_release_memory(int);
/*
-** CAPI3REF: Impose A Limit On Heap Size {F17350}
+** CAPI3REF: Impose A Limit On Heap Size {F17350}
**
** The sqlite3_soft_heap_limit() interface places a "soft" limit
** on the amount of heap memory that may be allocated by SQLite.
**
** This API can be invoked at program startup in order to register
** one or more statically linked extensions that will be available
-** to all new [database connections].
-**
-** This interface is experimental and is subject to change or
-** removal in future releases of SQLite.
+** to all new [database connections]. {END}
**
** This routine stores a pointer to the extension in an array that is
** obtained from [sqlite3_malloc()]. If you run a memory leak checker
** on your program and it reports a leak because of this array, invoke
** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory.
**
+** This interface is experimental and is subject to change or
+** removal in future releases of SQLite.
+**
** INVARIANTS:
**
** {F12641} This function registers an extension entry point that is
/*
** CAPI3REF: Reset Automatic Extension Loading {F12660}
**
-** This function disables all previously registered automatic extensions.
-** It undoes the effect of all prior [sqlite3_auto_extension()] calls.
+** This function disables all previously registered automatic
+** extensions. {END} It undoes the effect of all prior
+** [sqlite3_auto_extension()] calls.
**
** This interface is experimental and is subject to change or
** removal in future releases of SQLite.
** {F12661} This function disables all previously registered
** automatic extensions.
**
-** {F12662} This function disabled automatic extensions in all threads.
+** {F12662} This function disables automatic extensions in all threads.
*/
void sqlite3_reset_auto_extension(void);
/*
** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
**
-** This interfaces opens a handle to the BLOB located
+** This interfaces opens a [BLOB handle | handle] to the BLOB located
** in row iRow, column zColumn, table zTable in database zDb;
** in other words, the same BLOB that would be selected by:
**
);
/*
-** CAPI3REF: Close A BLOB Handle {F17830}
+** CAPI3REF: Close A BLOB Handle {F17830}
**
** Closes an open [BLOB handle].
**
**
** INVARIANTS:
**
-** {F17833} The [sqlite3_blob_close(P)] interface closes an
-** [sqlite3_blob] object P previously opened using
-** [sqlite3_blob_open()].
+** {F17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob]
+** object P previously opened using [sqlite3_blob_open()].
**
** {F17836} Closing an [sqlite3_blob] object using
** [sqlite3_blob_close()] shall cause the current transaction to
int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
/*
-** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}
+** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}
**
** This function is used to write data into an open [BLOB handle] from a
** caller-supplied buffer. N bytes of data are copied from the buffer Z
int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
/*
-** CAPI3REF: Virtual File System Objects {F11200}
+** CAPI3REF: Virtual File System Objects {F11200}
**
** A virtual filesystem (VFS) is an [sqlite3_vfs] object
** that SQLite uses to interact
** <li> SQLITE_MUTEX_STATIC_PRNG
** <li> SQLITE_MUTEX_STATIC_LRU
** <li> SQLITE_MUTEX_STATIC_LRU2
-** </ul> {END}
+** </ul>
**
** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
** returns a different mutex on every call. {F17034} But for the static
** mutex types, the same mutex is returned on every call that has
-** the same type number. {END}
+** the same type number.
**
** {F17019} The sqlite3_mutex_free() routine deallocates a previously
** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
** defined and if NDEBUG is not defined.
**
** {F17083} These routines should return true if the mutex in their argument
-** is held or not held, respectively, by the calling thread. {END}
+** is held or not held, respectively, by the calling thread.
**
** {X17084} The implementation is not required to provided versions of these
-** routines that actually work.
-** If the implementation does not provide working
-** versions of these routines, it should at least provide stubs
-** that always return true so that one does not get spurious
-** assertion failures. {END}
+** routines that actually work. If the implementation does not provide working
+** versions of these routines, it should at least provide stubs that always
+** return true so that one does not get spurious assertion failures.
**
** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
** the routine should return 1. {END} This seems counter-intuitive since
** CAPI3REF: Mutex Types {F17001}
**
** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
-** which is one of these integer constants. {END}
+** which is one of these integer constants.
*/
#define SQLITE_MUTEX_FAST 0
#define SQLITE_MUTEX_RECURSIVE 1
projects / thirdparty / sqlite.git / commitdiff
