diff options
Diffstat (limited to '')
| -rw-r--r-- | www/capi3ref.html | 12072 |
1 files changed, 12072 insertions, 0 deletions
diff --git a/www/capi3ref.html b/www/capi3ref.html new file mode 100644 index 0000000..a7fce31 --- /dev/null +++ b/www/capi3ref.html @@ -0,0 +1,12072 @@ +<!DOCTYPE html> +<html><head> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +<link href="sqlite.css" rel="stylesheet"> +<title>C/C++ Interface For SQLite Version 3</title> +<!-- path= --> +</head> +<body> +<div class=nosearch> +<a href="index.html"> +<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0"> +</a> +<div><!-- IE hack to prevent disappearing logo --></div> +<div class="tagline desktoponly"> +Small. Fast. Reliable.<br>Choose any three. +</div> +<div class="menu mainmenu"> +<ul> +<li><a href="index.html">Home</a> +<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> +<li class='wideonly'><a href='about.html'>About</a> +<li class='desktoponly'><a href="docs.html">Documentation</a> +<li class='desktoponly'><a href="download.html">Download</a> +<li class='wideonly'><a href='copyright.html'>License</a> +<li class='desktoponly'><a href="support.html">Support</a> +<li class='desktoponly'><a href="prosupport.html">Purchase</a> +<li class='search' id='search_menubutton'> +<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> +</ul> +</div> +<div class="menu submenu" id="submenu"> +<ul> +<li><a href='about.html'>About</a> +<li><a href='docs.html'>Documentation</a> +<li><a href='download.html'>Download</a> +<li><a href='support.html'>Support</a> +<li><a href='prosupport.html'>Purchase</a> +</ul> +</div> +<div class="searchmenu" id="searchmenu"> +<form method="GET" action="search"> +<select name="s" id="searchtype"> +<option value="d">Search Documentation</option> +<option value="c">Search Changelog</option> +</select> +<input type="text" name="q" id="searchbox" value=""> +<input type="submit" value="Go"> +</form> +</div> +</div> +<script> +function toggle_div(nm) { +var w = document.getElementById(nm); +if( w.style.display=="block" ){ +w.style.display = "none"; +}else{ +w.style.display = "block"; +} +} +function toggle_search() { +var w = document.getElementById("searchmenu"); +if( w.style.display=="block" ){ +w.style.display = "none"; +} else { +w.style.display = "block"; +setTimeout(function(){ +document.getElementById("searchbox").focus() +}, 30); +} +} +function div_off(nm){document.getElementById(nm).style.display="none";} +window.onbeforeunload = function(e){div_off("submenu");} +/* Disable the Search feature if we are not operating from CGI, since */ +/* Search is accomplished using CGI and will not work without it. */ +if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ +document.getElementById("search_menubutton").style.display = "none"; +} +/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ +function hideorshow(btn,obj){ +var x = document.getElementById(obj); +var b = document.getElementById(btn); +if( x.style.display!='none' ){ +x.style.display = 'none'; +b.innerHTML='show'; +}else{ +x.style.display = ''; +b.innerHTML='hide'; +} +return false; +} +var antiRobot = 0; +function antiRobotGo(){ +if( antiRobot!=3 ) return; +antiRobot = 7; +var j = document.getElementById("mtimelink"); +if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); +} +function antiRobotDefense(){ +document.body.onmousedown=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousedown=null; +} +document.body.onmousemove=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousemove=null; +} +setTimeout(function(){ +antiRobot |= 1; +antiRobotGo(); +}, 100) +antiRobotGo(); +} +antiRobotDefense(); +</script> + + + + +<h1 align="center"> +C-language Interface Specification for SQLite +</h1> + +<p>This page is intended to be a precise and detailed specification. +For a tutorial introductions, see instead: +<ul> +<li><a href="quickstart.html">SQLite In 3 Minutes Or Less</a> and/or +<li>the <a href="cintro.html">Introduction To The SQLite C/C++ Interface</a>. +</ul> +This same content is also available split out into +<a href="../c3ref/intro.html">some smaller pages</a>.</p> + +<hr> + + + +<h2>Experimental And Deprecated Interfaces</h2> + +<p>SQLite interfaces can be subdivided into three categories:</p> + +<ol> +<li>Stable</li> +<li>Experimental</li> +<li>Deprecated</li> +</ol> + +<p>Stable interfaces will be maintained indefinitely in a backwards +compatible way. An application that uses only stable interfaces +should always be able to relink against a newer version of SQLite +without any changes.</p> + +<p>Experimental interfaces are subject to change. +Applications that use experimental interfaces +may need to be modified when upgrading to a newer SQLite release, though +this is rare. +When new interfaces are added to SQLite, they generally begin +as experimental interfaces. After an interface has been in use for +a while and the developers are confident that the design of the interface +is sound and worthy of long-term support, the interface is marked +as stable.</p> + +<p>Deprecated interfaces have been superceded by better methods of +accomplishing the same thing and should be avoided in new applications. +Deprecated interfaces continue to be supported for the sake of +backwards compatibility. At some point in the future, it is possible +that deprecated interfaces may be removed.</p> + +<p>Key points:</p> + +<ul> +<li>Experimental interfaces are subject to change and/or removal +at any time.</li> + +<li>Deprecated interfaces should not be used in new code and might +be removed in some future release.</li> +</ul> + +<hr> +<h2>List Of Objects:</h2> +<div class='columns' style='columns: 14em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3'>sqlite3</a></li> +<li><a href='#sqlite3_api_routines'>sqlite3_api_routines</a></li> +<li><a href='#sqlite3_backup'>sqlite3_backup</a></li> +<li><a href='#sqlite3_blob'>sqlite3_blob</a></li> +<li><a href='#sqlite3_context'>sqlite3_context</a></li> +<li><a href='#sqlite3_data_directory'>sqlite3_data_directory</a></li> +<li><a href='#sqlite3_file'>sqlite3_file</a></li> +<li><a href='#sqlite3_filename'>sqlite3_filename</a></li> +<li><a href='#sqlite3_index_info'>sqlite3_index_info</a></li> +<li><a href='#sqlite3_int64'>sqlite3_int64</a></li> +<li><a href='#sqlite3_int64'>sqlite3_uint64</a></li> +<li><a href='#sqlite3_int64'>sqlite_int64</a></li> +<li><a href='#sqlite3_int64'>sqlite_uint64</a></li> +<li><a href='#sqlite3_io_methods'>sqlite3_io_methods</a></li> +<li><a href='#sqlite3_mem_methods'>sqlite3_mem_methods</a></li> +<li><a href='#sqlite3_module'>sqlite3_module</a></li> +<li><a href='#sqlite3_mutex'>sqlite3_mutex</a></li> +<li><a href='#sqlite3_mutex_methods'>sqlite3_mutex_methods</a></li> +<li><a href='#sqlite3_pcache'>sqlite3_pcache</a></li> +<li><a href='#sqlite3_pcache_methods2'>sqlite3_pcache_methods2</a></li> +<li><a href='#sqlite3_pcache_page'>sqlite3_pcache_page</a></li> +<li><a href='#sqlite3_snapshot'>sqlite3_snapshot</a></li> +<li><a href='#sqlite3_stmt'>sqlite3_stmt</a></li> +<li><a href='#sqlite3_str'>sqlite3_str</a></li> +<li><a href='#sqlite3_temp_directory'>sqlite3_temp_directory</a></li> +<li><a href='#sqlite3_value'>sqlite3_value</a></li> +<li><a href='#sqlite3_vfs'>sqlite3_vfs</a></li> +<li><a href='#sqlite3_vtab'>sqlite3_vtab</a></li> +<li><a href='#sqlite3_vtab_cursor'>sqlite3_vtab_cursor</a></li> +</ul> +</div> +<hr> + +<h2>List Of Constants:</h2> +<p>Also available: <a href="rescode.html">list of error codes</a></p> +<div class='columns' style='columns: 20em auto;'> +<ul style='padding-top:0;'> +<li><a href='#SQLITE_ABORT'>SQLITE_ABORT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ABORT_ROLLBACK</a></li> +<li><a href='#SQLITE_ACCESS_EXISTS'>SQLITE_ACCESS_EXISTS</a></li> +<li><a href='#SQLITE_ACCESS_EXISTS'>SQLITE_ACCESS_READ</a></li> +<li><a href='#SQLITE_ACCESS_EXISTS'>SQLITE_ACCESS_READWRITE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_ALTER_TABLE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_ANALYZE</a></li> +<li><a href='#SQLITE_ANY'>SQLITE_ANY</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_ATTACH</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_AUTH</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_AUTH_USER</a></li> +<li><a href='#SQLITE_BLOB'>SQLITE_BLOB</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_BUSY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_BUSY_RECOVERY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_BUSY_SNAPSHOT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_BUSY_TIMEOUT</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_CANTOPEN</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_CONVPATH</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_DIRTYWAL</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_FULLPATH</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_ISDIR</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_NOTEMPDIR</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CANTOPEN_SYMLINK</a></li> +<li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_FULL</a></li> +<li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_PASSIVE</a></li> +<li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_RESTART</a></li> +<li><a href='#SQLITE_CHECKPOINT_FULL'>SQLITE_CHECKPOINT_TRUNCATE</a></li> +<li><a href='#sqliteconfigcoveringindexscan'>SQLITE_CONFIG_COVERING_INDEX_SCAN</a></li> +<li><a href='#sqliteconfiggetmalloc'>SQLITE_CONFIG_GETMALLOC</a></li> +<li><a href='#sqliteconfiggetmutex'>SQLITE_CONFIG_GETMUTEX</a></li> +<li><a href='#sqliteconfiggetpcache'>SQLITE_CONFIG_GETPCACHE</a></li> +<li><a href='#sqliteconfiggetpcache2'>SQLITE_CONFIG_GETPCACHE2</a></li> +<li><a href='#sqliteconfigheap'>SQLITE_CONFIG_HEAP</a></li> +<li><a href='#sqliteconfiglog'>SQLITE_CONFIG_LOG</a></li> +<li><a href='#sqliteconfiglookaside'>SQLITE_CONFIG_LOOKASIDE</a></li> +<li><a href='#sqliteconfigmalloc'>SQLITE_CONFIG_MALLOC</a></li> +<li><a href='#sqliteconfigmemdbmaxsize'>SQLITE_CONFIG_MEMDB_MAXSIZE</a></li> +<li><a href='#sqliteconfigmemstatus'>SQLITE_CONFIG_MEMSTATUS</a></li> +<li><a href='#sqliteconfigmmapsize'>SQLITE_CONFIG_MMAP_SIZE</a></li> +<li><a href='#sqliteconfigmultithread'>SQLITE_CONFIG_MULTITHREAD</a></li> +<li><a href='#sqliteconfigmutex'>SQLITE_CONFIG_MUTEX</a></li> +<li><a href='#sqliteconfigpagecache'>SQLITE_CONFIG_PAGECACHE</a></li> +<li><a href='#sqliteconfigpcache'>SQLITE_CONFIG_PCACHE</a></li> +<li><a href='#sqliteconfigpcache2'>SQLITE_CONFIG_PCACHE2</a></li> +<li><a href='#sqliteconfigpcachehdrsz'>SQLITE_CONFIG_PCACHE_HDRSZ</a></li> +<li><a href='#sqliteconfigpmasz'>SQLITE_CONFIG_PMASZ</a></li> +<li><a href='#sqliteconfigscratch'>SQLITE_CONFIG_SCRATCH</a></li> +<li><a href='#sqliteconfigserialized'>SQLITE_CONFIG_SERIALIZED</a></li> +<li><a href='#sqliteconfigsinglethread'>SQLITE_CONFIG_SINGLETHREAD</a></li> +<li><a href='#sqliteconfigsmallmalloc'>SQLITE_CONFIG_SMALL_MALLOC</a></li> +<li><a href='#sqliteconfigsorterrefsize'>SQLITE_CONFIG_SORTERREF_SIZE</a></li> +<li><a href='#sqliteconfigsqllog'>SQLITE_CONFIG_SQLLOG</a></li> +<li><a href='#sqliteconfigstmtjrnlspill'>SQLITE_CONFIG_STMTJRNL_SPILL</a></li> +<li><a href='#sqliteconfiguri'>SQLITE_CONFIG_URI</a></li> +<li><a href='#sqliteconfigwin32heapsize'>SQLITE_CONFIG_WIN32_HEAPSIZE</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_CONSTRAINT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_CHECK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_COMMITHOOK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_DATATYPE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_FOREIGNKEY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_FUNCTION</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_NOTNULL</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_PINNED</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_PRIMARYKEY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_ROWID</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_TRIGGER</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_UNIQUE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CONSTRAINT_VTAB</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_COPY</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_CORRUPT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CORRUPT_INDEX</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CORRUPT_SEQUENCE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_CORRUPT_VTAB</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_INDEX</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TABLE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_INDEX</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_TABLE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_TRIGGER</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TEMP_VIEW</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_TRIGGER</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_VIEW</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_CREATE_VTABLE</a></li> +<li><a href='#sqlitedbconfigdefensive'>SQLITE_DBCONFIG_DEFENSIVE</a></li> +<li><a href='#sqlitedbconfigdqsddl'>SQLITE_DBCONFIG_DQS_DDL</a></li> +<li><a href='#sqlitedbconfigdqsdml'>SQLITE_DBCONFIG_DQS_DML</a></li> +<li><a href='#sqlitedbconfigenablefkey'>SQLITE_DBCONFIG_ENABLE_FKEY</a></li> +<li><a href='#sqlitedbconfigenablefts3tokenizer'>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</a></li> +<li><a href='#sqlitedbconfigenableloadextension'>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a></li> +<li><a href='#sqlitedbconfigenableqpsg'>SQLITE_DBCONFIG_ENABLE_QPSG</a></li> +<li><a href='#sqlitedbconfigenabletrigger'>SQLITE_DBCONFIG_ENABLE_TRIGGER</a></li> +<li><a href='#sqlitedbconfigenableview'>SQLITE_DBCONFIG_ENABLE_VIEW</a></li> +<li><a href='#sqlitedbconfiglegacyaltertable'>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</a></li> +<li><a href='#sqlitedbconfiglegacyfileformat'>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</a></li> +<li><a href='#sqlitedbconfiglookaside'>SQLITE_DBCONFIG_LOOKASIDE</a></li> +<li><a href='#sqlitedbconfigmaindbname'>SQLITE_DBCONFIG_MAINDBNAME</a></li> +<li><a href='#SQLITE_DBCONFIG_DEFENSIVE'>SQLITE_DBCONFIG_MAX</a></li> +<li><a href='#sqlitedbconfignockptonclose'>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</a></li> +<li><a href='#sqlitedbconfigresetdatabase'>SQLITE_DBCONFIG_RESET_DATABASE</a></li> +<li><a href='#sqlitedbconfigreversescanorder'>SQLITE_DBCONFIG_REVERSE_SCANORDER</a></li> +<li><a href='#sqlitedbconfigstmtscanstatus'>SQLITE_DBCONFIG_STMT_SCANSTATUS</a></li> +<li><a href='#sqlitedbconfigtriggereqp'>SQLITE_DBCONFIG_TRIGGER_EQP</a></li> +<li><a href='#sqlitedbconfigtrustedschema'>SQLITE_DBCONFIG_TRUSTED_SCHEMA</a></li> +<li><a href='#sqlitedbconfigwritableschema'>SQLITE_DBCONFIG_WRITABLE_SCHEMA</a></li> +<li><a href='#sqlitedbstatuscachehit'>SQLITE_DBSTATUS_CACHE_HIT</a></li> +<li><a href='#sqlitedbstatuscachemiss'>SQLITE_DBSTATUS_CACHE_MISS</a></li> +<li><a href='#sqlitedbstatuscachespill'>SQLITE_DBSTATUS_CACHE_SPILL</a></li> +<li><a href='#sqlitedbstatuscacheused'>SQLITE_DBSTATUS_CACHE_USED</a></li> +<li><a href='#sqlitedbstatuscacheusedshared'>SQLITE_DBSTATUS_CACHE_USED_SHARED</a></li> +<li><a href='#sqlitedbstatuscachewrite'>SQLITE_DBSTATUS_CACHE_WRITE</a></li> +<li><a href='#sqlitedbstatusdeferredfks'>SQLITE_DBSTATUS_DEFERRED_FKS</a></li> +<li><a href='#sqlitedbstatuslookasidehit'>SQLITE_DBSTATUS_LOOKASIDE_HIT</a></li> +<li><a href='#sqlitedbstatuslookasidemissfull'>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</a></li> +<li><a href='#sqlitedbstatuslookasidemisssize'>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</a></li> +<li><a href='#sqlitedbstatuslookasideused'>SQLITE_DBSTATUS_LOOKASIDE_USED</a></li> +<li><a href='#SQLITE_DBSTATUS options'>SQLITE_DBSTATUS_MAX</a></li> +<li><a href='#sqlitedbstatusschemaused'>SQLITE_DBSTATUS_SCHEMA_USED</a></li> +<li><a href='#sqlitedbstatusstmtused'>SQLITE_DBSTATUS_STMT_USED</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DELETE</a></li> +<li><a href='#SQLITE_DENY'>SQLITE_DENY</a></li> +<li><a href='#SQLITE_DESERIALIZE_FREEONCLOSE'>SQLITE_DESERIALIZE_FREEONCLOSE</a></li> +<li><a href='#SQLITE_DESERIALIZE_FREEONCLOSE'>SQLITE_DESERIALIZE_READONLY</a></li> +<li><a href='#SQLITE_DESERIALIZE_FREEONCLOSE'>SQLITE_DESERIALIZE_RESIZEABLE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DETACH</a></li> +<li><a href='#sqlitedeterministic'>SQLITE_DETERMINISTIC</a></li> +<li><a href='#sqlitedirectonly'>SQLITE_DIRECTONLY</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_DONE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_INDEX</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TABLE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_INDEX</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_TABLE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_TRIGGER</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TEMP_VIEW</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_TRIGGER</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_VIEW</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_DROP_VTABLE</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_EMPTY</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_ERROR</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_MISSING_COLLSEQ</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_RETRY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_ERROR_SNAPSHOT</a></li> +<li><a href='#SQLITE_FAIL'>SQLITE_FAIL</a></li> +<li><a href='#sqlitefcntlbeginatomicwrite'>SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a></li> +<li><a href='#sqlitefcntlbusyhandler'>SQLITE_FCNTL_BUSYHANDLER</a></li> +<li><a href='#sqlitefcntlchunksize'>SQLITE_FCNTL_CHUNK_SIZE</a></li> +<li><a href='#sqlitefcntlckptdone'>SQLITE_FCNTL_CKPT_DONE</a></li> +<li><a href='#sqlitefcntlckptstart'>SQLITE_FCNTL_CKPT_START</a></li> +<li><a href='#sqlitefcntlcksmfile'>SQLITE_FCNTL_CKSM_FILE</a></li> +<li><a href='#sqlitefcntlcommitatomicwrite'>SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a></li> +<li><a href='#sqlitefcntlcommitphasetwo'>SQLITE_FCNTL_COMMIT_PHASETWO</a></li> +<li><a href='#sqlitefcntldataversion'>SQLITE_FCNTL_DATA_VERSION</a></li> +<li><a href='#sqlitefcntlexternalreader'>SQLITE_FCNTL_EXTERNAL_READER</a></li> +<li><a href='#sqlitefcntlfilepointer'>SQLITE_FCNTL_FILE_POINTER</a></li> +<li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_GET_LOCKPROXYFILE</a></li> +<li><a href='#sqlitefcntlhasmoved'>SQLITE_FCNTL_HAS_MOVED</a></li> +<li><a href='#sqlitefcntljournalpointer'>SQLITE_FCNTL_JOURNAL_POINTER</a></li> +<li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_LAST_ERRNO</a></li> +<li><a href='#sqlitefcntllockstate'>SQLITE_FCNTL_LOCKSTATE</a></li> +<li><a href='#sqlitefcntllocktimeout'>SQLITE_FCNTL_LOCK_TIMEOUT</a></li> +<li><a href='#sqlitefcntlmmapsize'>SQLITE_FCNTL_MMAP_SIZE</a></li> +<li><a href='#sqlitefcntloverwrite'>SQLITE_FCNTL_OVERWRITE</a></li> +<li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_PDB</a></li> +<li><a href='#sqlitefcntlpersistwal'>SQLITE_FCNTL_PERSIST_WAL</a></li> +<li><a href='#sqlitefcntlpowersafeoverwrite'>SQLITE_FCNTL_POWERSAFE_OVERWRITE</a></li> +<li><a href='#sqlitefcntlpragma'>SQLITE_FCNTL_PRAGMA</a></li> +<li><a href='#sqlitefcntlrbu'>SQLITE_FCNTL_RBU</a></li> +<li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_RESERVE_BYTES</a></li> +<li><a href='#sqlitefcntlresetcache'>SQLITE_FCNTL_RESET_CACHE</a></li> +<li><a href='#sqlitefcntlrollbackatomicwrite'>SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a></li> +<li><a href='#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE'>SQLITE_FCNTL_SET_LOCKPROXYFILE</a></li> +<li><a href='#sqlitefcntlsizehint'>SQLITE_FCNTL_SIZE_HINT</a></li> +<li><a href='#sqlitefcntlsizelimit'>SQLITE_FCNTL_SIZE_LIMIT</a></li> +<li><a href='#sqlitefcntlsync'>SQLITE_FCNTL_SYNC</a></li> +<li><a href='#sqlitefcntlsyncomitted'>SQLITE_FCNTL_SYNC_OMITTED</a></li> +<li><a href='#sqlitefcntltempfilename'>SQLITE_FCNTL_TEMPFILENAME</a></li> +<li><a href='#sqlitefcntltrace'>SQLITE_FCNTL_TRACE</a></li> +<li><a href='#sqlitefcntlvfsname'>SQLITE_FCNTL_VFSNAME</a></li> +<li><a href='#sqlitefcntlvfspointer'>SQLITE_FCNTL_VFS_POINTER</a></li> +<li><a href='#sqlitefcntlwalblock'>SQLITE_FCNTL_WAL_BLOCK</a></li> +<li><a href='#sqlitefcntlwin32avretry'>SQLITE_FCNTL_WIN32_AV_RETRY</a></li> +<li><a href='#sqlitefcntlwin32gethandle'>SQLITE_FCNTL_WIN32_GET_HANDLE</a></li> +<li><a href='#sqlitefcntlwin32sethandle'>SQLITE_FCNTL_WIN32_SET_HANDLE</a></li> +<li><a href='#sqlitefcntlzipvfs'>SQLITE_FCNTL_ZIPVFS</a></li> +<li><a href='#SQLITE_BLOB'>SQLITE_FLOAT</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_FORMAT</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_FULL</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_FUNCTION</a></li> +<li><a href='#SQLITE_DENY'>SQLITE_IGNORE</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_EQ</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_FUNCTION</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_GE</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_GLOB</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_GT</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_IS</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_ISNOT</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_ISNOTNULL</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_ISNULL</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LE</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LIKE</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LIMIT</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_LT</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_MATCH</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_NE</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_OFFSET</a></li> +<li><a href='#SQLITE_INDEX_CONSTRAINT_EQ'>SQLITE_INDEX_CONSTRAINT_REGEXP</a></li> +<li><a href='#SQLITE_INDEX_SCAN_UNIQUE'>SQLITE_INDEX_SCAN_UNIQUE</a></li> +<li><a href='#sqliteinnocuous'>SQLITE_INNOCUOUS</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_INSERT</a></li> +<li><a href='#SQLITE_BLOB'>SQLITE_INTEGER</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_INTERNAL</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_INTERRUPT</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC16K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC1K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC2K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC32K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC4K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC512</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC64K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_ATOMIC8K</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_BATCH_ATOMIC</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_IMMUTABLE</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_POWERSAFE_OVERWRITE</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_SAFE_APPEND</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_SEQUENTIAL</a></li> +<li><a href='#SQLITE_IOCAP_ATOMIC'>SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_IOERR</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_ACCESS</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_AUTH</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_BEGIN_ATOMIC</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_BLOCKED</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CHECKRESERVEDLOCK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CLOSE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_COMMIT_ATOMIC</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CONVPATH</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_CORRUPTFS</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DATA</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DELETE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DELETE_NOENT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DIR_CLOSE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_DIR_FSYNC</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_FSTAT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_FSYNC</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_GETTEMPPATH</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_IN_PAGE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_LOCK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_MMAP</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_NOMEM</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_RDLOCK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_READ</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_ROLLBACK_ATOMIC</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SEEK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMLOCK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMMAP</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMOPEN</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHMSIZE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_SHORT_READ</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_TRUNCATE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_UNLOCK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_VNODE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_IOERR_WRITE</a></li> +<li><a href='#sqlitelimitattached'>SQLITE_LIMIT_ATTACHED</a></li> +<li><a href='#sqlitelimitcolumn'>SQLITE_LIMIT_COLUMN</a></li> +<li><a href='#sqlitelimitcompoundselect'>SQLITE_LIMIT_COMPOUND_SELECT</a></li> +<li><a href='#sqlitelimitexprdepth'>SQLITE_LIMIT_EXPR_DEPTH</a></li> +<li><a href='#sqlitelimitfunctionarg'>SQLITE_LIMIT_FUNCTION_ARG</a></li> +<li><a href='#sqlitelimitlength'>SQLITE_LIMIT_LENGTH</a></li> +<li><a href='#sqlitelimitlikepatternlength'>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</a></li> +<li><a href='#sqlitelimitsqllength'>SQLITE_LIMIT_SQL_LENGTH</a></li> +<li><a href='#sqlitelimittriggerdepth'>SQLITE_LIMIT_TRIGGER_DEPTH</a></li> +<li><a href='#sqlitelimitvariablenumber'>SQLITE_LIMIT_VARIABLE_NUMBER</a></li> +<li><a href='#sqlitelimitvdbeop'>SQLITE_LIMIT_VDBE_OP</a></li> +<li><a href='#sqlitelimitworkerthreads'>SQLITE_LIMIT_WORKER_THREADS</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_LOCKED</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_LOCKED_SHAREDCACHE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_LOCKED_VTAB</a></li> +<li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_EXCLUSIVE</a></li> +<li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_NONE</a></li> +<li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_PENDING</a></li> +<li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_RESERVED</a></li> +<li><a href='#SQLITE_LOCK_EXCLUSIVE'>SQLITE_LOCK_SHARED</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_MISMATCH</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_MISUSE</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_FAST</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_RECURSIVE</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_APP1</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_APP2</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_APP3</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_LRU</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_LRU2</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_MAIN</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_MEM</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_MEM2</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_OPEN</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_PMEM</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_PRNG</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_VFS1</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_VFS2</a></li> +<li><a href='#SQLITE_MUTEX_FAST'>SQLITE_MUTEX_STATIC_VFS3</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_NOLFS</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_NOMEM</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_NOTADB</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_NOTFOUND</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_NOTICE</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_NOTICE_RBU</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_NOTICE_RECOVER_ROLLBACK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_NOTICE_RECOVER_WAL</a></li> +<li><a href='#SQLITE_BLOB'>SQLITE_NULL</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_OK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_OK_LOAD_PERMANENTLY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_OK_SYMLINK</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_AUTOPROXY</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_CREATE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_DELETEONCLOSE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_EXCLUSIVE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_EXRESCODE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_FULLMUTEX</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_MAIN_DB</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_MAIN_JOURNAL</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_MEMORY</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_NOFOLLOW</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_NOMUTEX</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_PRIVATECACHE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_READONLY</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_READWRITE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_SHAREDCACHE</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_SUBJOURNAL</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_SUPER_JOURNAL</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_TEMP_DB</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_TEMP_JOURNAL</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_TRANSIENT_DB</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_URI</a></li> +<li><a href='#SQLITE_OPEN_AUTOPROXY'>SQLITE_OPEN_WAL</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_PERM</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_PRAGMA</a></li> +<li><a href='#sqlitepreparenormalize'>SQLITE_PREPARE_NORMALIZE</a></li> +<li><a href='#sqlitepreparenovtab'>SQLITE_PREPARE_NO_VTAB</a></li> +<li><a href='#sqlitepreparepersistent'>SQLITE_PREPARE_PERSISTENT</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_PROTOCOL</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_RANGE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_READ</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_READONLY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_CANTINIT</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_CANTLOCK</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_DBMOVED</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_DIRECTORY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_RECOVERY</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_READONLY_ROLLBACK</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_RECURSIVE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_REINDEX</a></li> +<li><a href='#SQLITE_FAIL'>SQLITE_REPLACE</a></li> +<li><a href='#sqliteresultsubtype'>SQLITE_RESULT_SUBTYPE</a></li> +<li><a href='#SQLITE_FAIL'>SQLITE_ROLLBACK</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_ROW</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_SAVEPOINT</a></li> +<li><a href='#SQLITE_SCANSTAT_COMPLEX'>SQLITE_SCANSTAT_COMPLEX</a></li> +<li><a href='#sqlitescanstatest'>SQLITE_SCANSTAT_EST</a></li> +<li><a href='#sqlitescanstatexplain'>SQLITE_SCANSTAT_EXPLAIN</a></li> +<li><a href='#sqlitescanstatname'>SQLITE_SCANSTAT_NAME</a></li> +<li><a href='#sqlitescanstatncycle'>SQLITE_SCANSTAT_NCYCLE</a></li> +<li><a href='#sqlitescanstatnloop'>SQLITE_SCANSTAT_NLOOP</a></li> +<li><a href='#sqlitescanstatnvisit'>SQLITE_SCANSTAT_NVISIT</a></li> +<li><a href='#sqlitescanstatparentid'>SQLITE_SCANSTAT_PARENTID</a></li> +<li><a href='#sqlitescanstatselectid'>SQLITE_SCANSTAT_SELECTID</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_SCHEMA</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_SELECT</a></li> +<li><a href='#SQLITE_SERIALIZE_NOCOPY'>SQLITE_SERIALIZE_NOCOPY</a></li> +<li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_EXCLUSIVE</a></li> +<li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_LOCK</a></li> +<li><a href='#SQLITE_SHM_NLOCK'>SQLITE_SHM_NLOCK</a></li> +<li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_SHARED</a></li> +<li><a href='#SQLITE_SHM_EXCLUSIVE'>SQLITE_SHM_UNLOCK</a></li> +<li><a href='#SQLITE_SOURCE_ID'>SQLITE_SOURCE_ID</a></li> +<li><a href='#SQLITE_STATIC'>SQLITE_STATIC</a></li> +<li><a href='#sqlitestatusmalloccount'>SQLITE_STATUS_MALLOC_COUNT</a></li> +<li><a href='#sqlitestatusmallocsize'>SQLITE_STATUS_MALLOC_SIZE</a></li> +<li><a href='#sqlitestatusmemoryused'>SQLITE_STATUS_MEMORY_USED</a></li> +<li><a href='#sqlitestatuspagecacheoverflow'>SQLITE_STATUS_PAGECACHE_OVERFLOW</a></li> +<li><a href='#sqlitestatuspagecachesize'>SQLITE_STATUS_PAGECACHE_SIZE</a></li> +<li><a href='#sqlitestatuspagecacheused'>SQLITE_STATUS_PAGECACHE_USED</a></li> +<li><a href='#sqlitestatusparserstack'>SQLITE_STATUS_PARSER_STACK</a></li> +<li><a href='#sqlitestatusscratchoverflow'>SQLITE_STATUS_SCRATCH_OVERFLOW</a></li> +<li><a href='#sqlitestatusscratchsize'>SQLITE_STATUS_SCRATCH_SIZE</a></li> +<li><a href='#sqlitestatusscratchused'>SQLITE_STATUS_SCRATCH_USED</a></li> +<li><a href='#sqlitestmtstatusautoindex'>SQLITE_STMTSTATUS_AUTOINDEX</a></li> +<li><a href='#SQLITE_STMTSTATUS counter'>SQLITE_STMTSTATUS_FILTER_HIT</a></li> +<li><a href='#sqlitestmtstatusfiltermiss'>SQLITE_STMTSTATUS_FILTER_MISS</a></li> +<li><a href='#sqlitestmtstatusfullscanstep'>SQLITE_STMTSTATUS_FULLSCAN_STEP</a></li> +<li><a href='#sqlitestmtstatusmemused'>SQLITE_STMTSTATUS_MEMUSED</a></li> +<li><a href='#sqlitestmtstatusreprepare'>SQLITE_STMTSTATUS_REPREPARE</a></li> +<li><a href='#sqlitestmtstatusrun'>SQLITE_STMTSTATUS_RUN</a></li> +<li><a href='#sqlitestmtstatussort'>SQLITE_STMTSTATUS_SORT</a></li> +<li><a href='#sqlitestmtstatusvmstep'>SQLITE_STMTSTATUS_VM_STEP</a></li> +<li><a href='#sqlitesubtype'>SQLITE_SUBTYPE</a></li> +<li><a href='#SQLITE_SYNC_DATAONLY'>SQLITE_SYNC_DATAONLY</a></li> +<li><a href='#SQLITE_SYNC_DATAONLY'>SQLITE_SYNC_FULL</a></li> +<li><a href='#SQLITE_SYNC_DATAONLY'>SQLITE_SYNC_NORMAL</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ALWAYS</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ASSERT</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_BITVEC_TEST</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_BYTEORDER</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_EXPLAIN_STMT</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_FAULT_INSTALL</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_FIRST</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_FK_NO_ACTION</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_IMPOSTER</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_INTERNAL_FUNCTIONS</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ISINIT</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ISKEYWORD</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_JSON_SELFCHECK</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_LAST</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_LOCALTIME_FAULT</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_LOGEST</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_NEVER_CORRUPT</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_OPTIMIZATIONS</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PARSER_COVERAGE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PENDING_BYTE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_RESET</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_RESTORE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_SAVE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_PRNG_SEED</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_RESERVE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_RESULT_INTREAL</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_SCRATCHMALLOC</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_SEEK_COUNT</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_SORTER_MMAP</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_TRACEFLAGS</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_TUNE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_USELONGDOUBLE</a></li> +<li><a href='#SQLITE_TESTCTRL_ALWAYS'>SQLITE_TESTCTRL_VDBE_COVERAGE</a></li> +<li><a href='#SQLITE_BLOB'>SQLITE_TEXT</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_TOOBIG</a></li> +<li><a href='#SQLITE_TRACE'>SQLITE_TRACE</a></li> +<li><a href='#sqlitetraceclose'>SQLITE_TRACE_CLOSE</a></li> +<li><a href='#sqlitetraceprofile'>SQLITE_TRACE_PROFILE</a></li> +<li><a href='#sqlitetracerow'>SQLITE_TRACE_ROW</a></li> +<li><a href='#sqlitetracestmt'>SQLITE_TRACE_STMT</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_TRANSACTION</a></li> +<li><a href='#SQLITE_STATIC'>SQLITE_TRANSIENT</a></li> +<li><a href='#sqlitetxnnone'>SQLITE_TXN_NONE</a></li> +<li><a href='#sqlitetxnread'>SQLITE_TXN_READ</a></li> +<li><a href='#sqlitetxnwrite'>SQLITE_TXN_WRITE</a></li> +<li><a href='#SQLITE_ALTER_TABLE'>SQLITE_UPDATE</a></li> +<li><a href='#SQLITE_ANY'>SQLITE_UTF16</a></li> +<li><a href='#SQLITE_ANY'>SQLITE_UTF16BE</a></li> +<li><a href='#SQLITE_ANY'>SQLITE_UTF16LE</a></li> +<li><a href='#SQLITE_ANY'>SQLITE_UTF16_ALIGNED</a></li> +<li><a href='#SQLITE_ANY'>SQLITE_UTF8</a></li> +<li><a href='#SQLITE_SOURCE_ID'>SQLITE_VERSION</a></li> +<li><a href='#SQLITE_SOURCE_ID'>SQLITE_VERSION_NUMBER</a></li> +<li><a href='#sqlitevtabconstraintsupport'>SQLITE_VTAB_CONSTRAINT_SUPPORT</a></li> +<li><a href='#sqlitevtabdirectonly'>SQLITE_VTAB_DIRECTONLY</a></li> +<li><a href='#sqlitevtabinnocuous'>SQLITE_VTAB_INNOCUOUS</a></li> +<li><a href='#sqlitevtabusesallschemas'>SQLITE_VTAB_USES_ALL_SCHEMAS</a></li> +<li><a href='#SQLITE_ABORT'>SQLITE_WARNING</a></li> +<li><a href='#SQLITE_ABORT_ROLLBACK'>SQLITE_WARNING_AUTOINDEX</a></li> +<li><a href='#SQLITE_WIN32_DATA_DIRECTORY_TYPE'>SQLITE_WIN32_DATA_DIRECTORY_TYPE</a></li> +<li><a href='#SQLITE_WIN32_DATA_DIRECTORY_TYPE'>SQLITE_WIN32_TEMP_DIRECTORY_TYPE</a></li> +</ul> +</div> +<hr> + +<h2>List Of Functions:</h2> +<p>Note: Functions marked with "<small><i>(exp)</i></small>" +are <a href="capi3ref.html">experimental</a> and functions whose names are +<s>struck through</s> are <a href="capi3ref.html">deprecated</a>.</p> +<!-- number of functions: 290 --> +<!-- number of deprecated functions: 7 --> +<!-- number of experimental functions: 0 --> +<div class='columns' style='columns: 15em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_aggregate_context'>sqlite3_aggregate_context</a></li> +<li><s>sqlite3_aggregate_count</s></li> +<li><a href='#sqlite3_auto_extension'>sqlite3_auto_extension</a></li> +<li><a href='#sqlite3_autovacuum_pages'>sqlite3_autovacuum_pages</a></li> +<li><a href='#sqlite3backupfinish'>sqlite3_backup_finish</a></li> +<li><a href='#sqlite3backupinit'>sqlite3_backup_init</a></li> +<li><a href='#sqlite3backuppagecount'>sqlite3_backup_pagecount</a></li> +<li><a href='#sqlite3backupremaining'>sqlite3_backup_remaining</a></li> +<li><a href='#sqlite3backupstep'>sqlite3_backup_step</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob64</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_double</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_int</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_int64</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_null</a></li> +<li><a href='#sqlite3_bind_parameter_count'>sqlite3_bind_parameter_count</a></li> +<li><a href='#sqlite3_bind_parameter_index'>sqlite3_bind_parameter_index</a></li> +<li><a href='#sqlite3_bind_parameter_name'>sqlite3_bind_parameter_name</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_pointer</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_text</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_text16</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_text64</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_value</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob64</a></li> +<li><a href='#sqlite3_blob_bytes'>sqlite3_blob_bytes</a></li> +<li><a href='#sqlite3_blob_close'>sqlite3_blob_close</a></li> +<li><a href='#sqlite3_blob_open'>sqlite3_blob_open</a></li> +<li><a href='#sqlite3_blob_read'>sqlite3_blob_read</a></li> +<li><a href='#sqlite3_blob_reopen'>sqlite3_blob_reopen</a></li> +<li><a href='#sqlite3_blob_write'>sqlite3_blob_write</a></li> +<li><a href='#sqlite3_busy_handler'>sqlite3_busy_handler</a></li> +<li><a href='#sqlite3_busy_timeout'>sqlite3_busy_timeout</a></li> +<li><a href='#sqlite3_cancel_auto_extension'>sqlite3_cancel_auto_extension</a></li> +<li><a href='#sqlite3_changes'>sqlite3_changes</a></li> +<li><a href='#sqlite3_changes'>sqlite3_changes64</a></li> +<li><a href='#sqlite3_clear_bindings'>sqlite3_clear_bindings</a></li> +<li><a href='#sqlite3_close'>sqlite3_close</a></li> +<li><a href='#sqlite3_close'>sqlite3_close_v2</a></li> +<li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed</a></li> +<li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_blob</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_bytes</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_bytes16</a></li> +<li><a href='#sqlite3_column_count'>sqlite3_column_count</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name16</a></li> +<li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype</a></li> +<li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_double</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_int</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_int64</a></li> +<li><a href='#sqlite3_column_name'>sqlite3_column_name</a></li> +<li><a href='#sqlite3_column_name'>sqlite3_column_name16</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name16</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_text</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_text16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_type</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_value</a></li> +<li><a href='#sqlite3_commit_hook'>sqlite3_commit_hook</a></li> +<li><a href='#sqlite3_compileoption_get'>sqlite3_compileoption_get</a></li> +<li><a href='#sqlite3_compileoption_get'>sqlite3_compileoption_used</a></li> +<li><a href='#sqlite3_complete'>sqlite3_complete</a></li> +<li><a href='#sqlite3_complete'>sqlite3_complete16</a></li> +<li><a href='#sqlite3_config'>sqlite3_config</a></li> +<li><a href='#sqlite3_context_db_handle'>sqlite3_context_db_handle</a></li> +<li><a href='#sqlite3_create_collation'>sqlite3_create_collation</a></li> +<li><a href='#sqlite3_create_collation'>sqlite3_create_collation16</a></li> +<li><a href='#sqlite3_create_collation'>sqlite3_create_collation_v2</a></li> +<li><a href='#sqlite3_create_filename'>sqlite3_create_filename</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_function</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_function16</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_function_v2</a></li> +<li><a href='#sqlite3_create_module'>sqlite3_create_module</a></li> +<li><a href='#sqlite3_create_module'>sqlite3_create_module_v2</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_window_function</a></li> +<li><a href='#sqlite3_data_count'>sqlite3_data_count</a></li> +<li><a href='#sqlite3_database_file_object'>sqlite3_database_file_object</a></li> +<li><a href='#sqlite3_db_cacheflush'>sqlite3_db_cacheflush</a></li> +<li><a href='#sqlite3_db_config'>sqlite3_db_config</a></li> +<li><a href='#sqlite3_db_filename'>sqlite3_db_filename</a></li> +<li><a href='#sqlite3_db_handle'>sqlite3_db_handle</a></li> +<li><a href='#sqlite3_db_mutex'>sqlite3_db_mutex</a></li> +<li><a href='#sqlite3_db_name'>sqlite3_db_name</a></li> +<li><a href='#sqlite3_db_readonly'>sqlite3_db_readonly</a></li> +<li><a href='#sqlite3_db_release_memory'>sqlite3_db_release_memory</a></li> +<li><a href='#sqlite3_db_status'>sqlite3_db_status</a></li> +<li><a href='#sqlite3_declare_vtab'>sqlite3_declare_vtab</a></li> +<li><a href='#sqlite3_deserialize'>sqlite3_deserialize</a></li> +<li><a href='#sqlite3_drop_modules'>sqlite3_drop_modules</a></li> +<li><a href='#sqlite3_enable_load_extension'>sqlite3_enable_load_extension</a></li> +<li><a href='#sqlite3_enable_shared_cache'>sqlite3_enable_shared_cache</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errcode</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errmsg</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errmsg16</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_error_offset</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errstr</a></li> +<li><a href='#sqlite3_exec'>sqlite3_exec</a></li> +<li><a href='#sqlite3_expanded_sql'>sqlite3_expanded_sql</a></li> +<li><s>sqlite3_expired</s></li> +<li><a href='#sqlite3_errcode'>sqlite3_extended_errcode</a></li> +<li><a href='#sqlite3_extended_result_codes'>sqlite3_extended_result_codes</a></li> +<li><a href='#sqlite3_file_control'>sqlite3_file_control</a></li> +<li><a href='#sqlite3_filename_database'>sqlite3_filename_database</a></li> +<li><a href='#sqlite3_filename_database'>sqlite3_filename_journal</a></li> +<li><a href='#sqlite3_filename_database'>sqlite3_filename_wal</a></li> +<li><a href='#sqlite3_finalize'>sqlite3_finalize</a></li> +<li><a href='#sqlite3_free'>sqlite3_free</a></li> +<li><a href='#sqlite3_create_filename'>sqlite3_free_filename</a></li> +<li><a href='#sqlite3_free_table'>sqlite3_free_table</a></li> +<li><a href='#sqlite3_get_autocommit'>sqlite3_get_autocommit</a></li> +<li><a href='#sqlite3_get_auxdata'>sqlite3_get_auxdata</a></li> +<li><a href='#sqlite3_get_clientdata'>sqlite3_get_clientdata</a></li> +<li><a href='#sqlite3_free_table'>sqlite3_get_table</a></li> +<li><s>sqlite3_global_recover</s></li> +<li><a href='#sqlite3_hard_heap_limit64'>sqlite3_hard_heap_limit64</a></li> +<li><a href='#sqlite3_initialize'>sqlite3_initialize</a></li> +<li><a href='#sqlite3_interrupt'>sqlite3_interrupt</a></li> +<li><a href='#sqlite3_interrupt'>sqlite3_is_interrupted</a></li> +<li><a href='#sqlite3_keyword_check'>sqlite3_keyword_check</a></li> +<li><a href='#sqlite3_keyword_check'>sqlite3_keyword_count</a></li> +<li><a href='#sqlite3_keyword_check'>sqlite3_keyword_name</a></li> +<li><a href='#sqlite3_last_insert_rowid'>sqlite3_last_insert_rowid</a></li> +<li><a href='#sqlite3_libversion'>sqlite3_libversion</a></li> +<li><a href='#sqlite3_libversion'>sqlite3_libversion_number</a></li> +<li><a href='#sqlite3_limit'>sqlite3_limit</a></li> +<li><a href='#sqlite3_load_extension'>sqlite3_load_extension</a></li> +<li><a href='#sqlite3_log'>sqlite3_log</a></li> +<li><a href='#sqlite3_free'>sqlite3_malloc</a></li> +<li><a href='#sqlite3_free'>sqlite3_malloc64</a></li> +<li><s>sqlite3_memory_alarm</s></li> +<li><a href='#sqlite3_memory_highwater'>sqlite3_memory_highwater</a></li> +<li><a href='#sqlite3_memory_highwater'>sqlite3_memory_used</a></li> +<li><a href='#sqlite3_mprintf'>sqlite3_mprintf</a></li> +<li><a href='#sqlite3_free'>sqlite3_msize</a></li> +<li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_alloc</a></li> +<li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_enter</a></li> +<li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_free</a></li> +<li><a href='#sqlite3_mutex_held'>sqlite3_mutex_held</a></li> +<li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_leave</a></li> +<li><a href='#sqlite3_mutex_held'>sqlite3_mutex_notheld</a></li> +<li><a href='#sqlite3_mutex_alloc'>sqlite3_mutex_try</a></li> +<li><a href='#sqlite3_next_stmt'>sqlite3_next_stmt</a></li> +<li><a href='#sqlite3_expanded_sql'>sqlite3_normalized_sql</a></li> +<li><a href='#sqlite3_open'>sqlite3_open</a></li> +<li><a href='#sqlite3_open'>sqlite3_open16</a></li> +<li><a href='#sqlite3_open'>sqlite3_open_v2</a></li> +<li><a href='#sqlite3_initialize'>sqlite3_os_end</a></li> +<li><a href='#sqlite3_initialize'>sqlite3_os_init</a></li> +<li><a href='#sqlite3_overload_function'>sqlite3_overload_function</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16_v2</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16_v3</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare_v2</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare_v3</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_blobwrite</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_count</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_depth</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_hook</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_new</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_old</a></li> +<li><a href='#sqlite3_profile'>sqlite3_profile</a></li> +<li><a href='#sqlite3_progress_handler'>sqlite3_progress_handler</a></li> +<li><a href='#sqlite3_randomness'>sqlite3_randomness</a></li> +<li><a href='#sqlite3_free'>sqlite3_realloc</a></li> +<li><a href='#sqlite3_free'>sqlite3_realloc64</a></li> +<li><a href='#sqlite3_release_memory'>sqlite3_release_memory</a></li> +<li><a href='#sqlite3_reset'>sqlite3_reset</a></li> +<li><a href='#sqlite3_reset_auto_extension'>sqlite3_reset_auto_extension</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_blob</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_blob64</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_double</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error16</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error_code</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error_nomem</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error_toobig</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_int</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_int64</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_null</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_pointer</a></li> +<li><a href='#sqlite3_result_subtype'>sqlite3_result_subtype</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text16</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text16be</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text16le</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text64</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_value</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob64</a></li> +<li><a href='#sqlite3_commit_hook'>sqlite3_rollback_hook</a></li> +<li><a href='#sqlite3_serialize'>sqlite3_serialize</a></li> +<li><a href='#sqlite3_set_authorizer'>sqlite3_set_authorizer</a></li> +<li><a href='#sqlite3_get_auxdata'>sqlite3_set_auxdata</a></li> +<li><a href='#sqlite3_get_clientdata'>sqlite3_set_clientdata</a></li> +<li><a href='#sqlite3_set_last_insert_rowid'>sqlite3_set_last_insert_rowid</a></li> +<li><a href='#sqlite3_initialize'>sqlite3_shutdown</a></li> +<li><a href='#sqlite3_sleep'>sqlite3_sleep</a></li> +<li><a href='#sqlite3_snapshot_cmp'>sqlite3_snapshot_cmp</a></li> +<li><a href='#sqlite3_snapshot_free'>sqlite3_snapshot_free</a></li> +<li><a href='#sqlite3_snapshot_get'>sqlite3_snapshot_get</a></li> +<li><a href='#sqlite3_snapshot_open'>sqlite3_snapshot_open</a></li> +<li><a href='#sqlite3_snapshot_recover'>sqlite3_snapshot_recover</a></li> +<li><a href='#sqlite3_mprintf'>sqlite3_snprintf</a></li> +<li><s>sqlite3_soft_heap_limit</s></li> +<li><a href='#sqlite3_hard_heap_limit64'>sqlite3_soft_heap_limit64</a></li> +<li><a href='#sqlite3_libversion'>sqlite3_sourceid</a></li> +<li><a href='#sqlite3_expanded_sql'>sqlite3_sql</a></li> +<li><a href='#sqlite3_status'>sqlite3_status</a></li> +<li><a href='#sqlite3_status'>sqlite3_status64</a></li> +<li><a href='#sqlite3_step'>sqlite3_step</a></li> +<li><a href='#sqlite3_stmt_busy'>sqlite3_stmt_busy</a></li> +<li><a href='#sqlite3_stmt_explain'>sqlite3_stmt_explain</a></li> +<li><a href='#sqlite3_stmt_isexplain'>sqlite3_stmt_isexplain</a></li> +<li><a href='#sqlite3_stmt_readonly'>sqlite3_stmt_readonly</a></li> +<li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus</a></li> +<li><a href='#sqlite3_stmt_scanstatus_reset'>sqlite3_stmt_scanstatus_reset</a></li> +<li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus_v2</a></li> +<li><a href='#sqlite3_stmt_status'>sqlite3_stmt_status</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_append</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_appendall</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_appendchar</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_appendf</a></li> +<li><a href='#sqlite3_str_errcode'>sqlite3_str_errcode</a></li> +<li><a href='#sqlite3_str_finish'>sqlite3_str_finish</a></li> +<li><a href='#sqlite3_str_errcode'>sqlite3_str_length</a></li> +<li><a href='#sqlite3_str_new'>sqlite3_str_new</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_reset</a></li> +<li><a href='#sqlite3_str_errcode'>sqlite3_str_value</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_vappendf</a></li> +<li><a href='#sqlite3_strglob'>sqlite3_strglob</a></li> +<li><a href='#sqlite3_stricmp'>sqlite3_stricmp</a></li> +<li><a href='#sqlite3_strlike'>sqlite3_strlike</a></li> +<li><a href='#sqlite3_stricmp'>sqlite3_strnicmp</a></li> +<li><a href='#sqlite3_system_errno'>sqlite3_system_errno</a></li> +<li><a href='#sqlite3_table_column_metadata'>sqlite3_table_column_metadata</a></li> +<li><a href='#sqlite3_test_control'>sqlite3_test_control</a></li> +<li><s>sqlite3_thread_cleanup</s></li> +<li><a href='#sqlite3_threadsafe'>sqlite3_threadsafe</a></li> +<li><a href='#sqlite3_total_changes'>sqlite3_total_changes</a></li> +<li><a href='#sqlite3_total_changes'>sqlite3_total_changes64</a></li> +<li><a href='#sqlite3_profile'>sqlite3_trace</a></li> +<li><a href='#sqlite3_trace_v2'>sqlite3_trace_v2</a></li> +<li><s>sqlite3_transfer_bindings</s></li> +<li><a href='#sqlite3_txn_state'>sqlite3_txn_state</a></li> +<li><a href='#sqlite3_unlock_notify'>sqlite3_unlock_notify</a></li> +<li><a href='#sqlite3_update_hook'>sqlite3_update_hook</a></li> +<li><a href='#sqlite3_uri_boolean'>sqlite3_uri_boolean</a></li> +<li><a href='#sqlite3_uri_boolean'>sqlite3_uri_int64</a></li> +<li><a href='#sqlite3_uri_boolean'>sqlite3_uri_key</a></li> +<li><a href='#sqlite3_uri_boolean'>sqlite3_uri_parameter</a></li> +<li><a href='#sqlite3_user_data'>sqlite3_user_data</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_blob</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_bytes</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_bytes16</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_double</a></li> +<li><a href='#sqlite3_value_dup'>sqlite3_value_dup</a></li> +<li><a href='#sqlite3_value_encoding'>sqlite3_value_encoding</a></li> +<li><a href='#sqlite3_value_dup'>sqlite3_value_free</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_frombind</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_int</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_int64</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_nochange</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_numeric_type</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_pointer</a></li> +<li><a href='#sqlite3_value_subtype'>sqlite3_value_subtype</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text16</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text16be</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text16le</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_type</a></li> +<li><a href='#sqlite3_libversion'>sqlite3_version</a></li> +<li><a href='#sqlite3_vfs_find'>sqlite3_vfs_find</a></li> +<li><a href='#sqlite3_vfs_find'>sqlite3_vfs_register</a></li> +<li><a href='#sqlite3_vfs_find'>sqlite3_vfs_unregister</a></li> +<li><a href='#sqlite3_mprintf'>sqlite3_vmprintf</a></li> +<li><a href='#sqlite3_mprintf'>sqlite3_vsnprintf</a></li> +<li><a href='#sqlite3_vtab_collation'>sqlite3_vtab_collation</a></li> +<li><a href='#sqlite3_vtab_config'>sqlite3_vtab_config</a></li> +<li><a href='#sqlite3_vtab_distinct'>sqlite3_vtab_distinct</a></li> +<li><a href='#sqlite3_vtab_in'>sqlite3_vtab_in</a></li> +<li><a href='#sqlite3_vtab_in_first'>sqlite3_vtab_in_first</a></li> +<li><a href='#sqlite3_vtab_in_first'>sqlite3_vtab_in_next</a></li> +<li><a href='#sqlite3_vtab_nochange'>sqlite3_vtab_nochange</a></li> +<li><a href='#sqlite3_vtab_on_conflict'>sqlite3_vtab_on_conflict</a></li> +<li><a href='#sqlite3_vtab_rhs_value'>sqlite3_vtab_rhs_value</a></li> +<li><a href='#sqlite3_wal_autocheckpoint'>sqlite3_wal_autocheckpoint</a></li> +<li><a href='#sqlite3_wal_checkpoint'>sqlite3_wal_checkpoint</a></li> +<li><a href='#sqlite3_wal_checkpoint_v2'>sqlite3_wal_checkpoint_v2</a></li> +<li><a href='#sqlite3_wal_hook'>sqlite3_wal_hook</a></li> +<li><a href='#sqlite3_win32_set_directory'>sqlite3_win32_set_directory</a></li> +<li><a href='#sqlite3_win32_set_directory'>sqlite3_win32_set_directory16</a></li> +<li><a href='#sqlite3_win32_set_directory'>sqlite3_win32_set_directory8</a></li> +</ul> +</div> +<hr> +<a name="SQLITE_INDEX_SCAN_UNIQUE"></a> +<h2>Virtual Table Scan Flags</h2> +</div> +<blockquote><pre> +#define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */ +</pre></blockquote> +<p> +Virtual table implementations are allowed to set the +<a href="#sqlite3_index_info">sqlite3_index_info</a>.idxFlags field to some combination of +these bits. +</p><hr><a name="SQLITE_SERIALIZE_NOCOPY"></a> +<h2>Flags for sqlite3_serialize</h2> +</div> +<blockquote><pre> +#define SQLITE_SERIALIZE_NOCOPY 0x001 /* Do no memory allocations */ +</pre></blockquote> +<p> +Zero or more of the following constants can be OR-ed together for +the F argument to <a href="#sqlite3_serialize">sqlite3_serialize(D,S,P,F)</a>.</p> + +<p>SQLITE_SERIALIZE_NOCOPY means that <a href="#sqlite3_serialize">sqlite3_serialize()</a> will return +a pointer to contiguous in-memory database that it is currently using, +without making a copy of the database. If SQLite is not currently using +a contiguous in-memory database, then this option causes +<a href="#sqlite3_serialize">sqlite3_serialize()</a> to return a NULL pointer. SQLite will only be +using a contiguous in-memory database if it has been initialized by a +prior call to <a href="#sqlite3_deserialize">sqlite3_deserialize()</a>. +</p><hr><a name="SQLITE_SHM_NLOCK"></a> +<h2>Maximum xShmLock index</h2> +</div> +<blockquote><pre> +#define SQLITE_SHM_NLOCK 8 +</pre></blockquote> +<p> +The xShmLock method on <a href="#sqlite3_io_methods">sqlite3_io_methods</a> may use values +between 0 and this upper bound as its "offset" argument. +The SQLite core will never attempt to acquire or release a +lock outside of this range +</p><hr><a name="sqlite3_api_routines"></a> +<h2>Loadable Extension Thunk</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_api_routines sqlite3_api_routines; +</pre></blockquote> +<p> +A pointer to the opaque sqlite3_api_routines structure is passed as +the third parameter to entry points of <a href="loadext.html">loadable extensions</a>. This +structure must be typedefed in order to work around compiler warnings +on some platforms. +</p><hr><a name="sqlite3_backup"></a> +<h2>Online Backup Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_backup sqlite3_backup; +</pre></blockquote> +<p> +The sqlite3_backup object records state information about an ongoing +online backup operation. The sqlite3_backup object is created by +a call to <a href="#sqlite3backupinit">sqlite3_backup_init()</a> and is destroyed by a call to +<a href="#sqlite3backupfinish">sqlite3_backup_finish()</a>.</p> + +<p>See Also: <a href="backup.html">Using the SQLite Online Backup API</a> +</p><hr><a name="sqlite3_context"></a> +<h2>SQL Function Context Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_context sqlite3_context; +</pre></blockquote> +<p> +The context in which an SQL function executes is stored in an +sqlite3_context object. A pointer to an sqlite3_context object +is always first parameter to <a href="appfunc.html">application-defined SQL functions</a>. +The application-defined SQL function implementation will pass this +pointer through into calls to <a href="#sqlite3_result_blob">sqlite3_result()</a>, +<a href="#sqlite3_aggregate_context">sqlite3_aggregate_context()</a>, <a href="#sqlite3_user_data">sqlite3_user_data()</a>, +<a href="#sqlite3_context_db_handle">sqlite3_context_db_handle()</a>, <a href="#sqlite3_get_auxdata">sqlite3_get_auxdata()</a>, +and/or <a href="#sqlite3_get_auxdata">sqlite3_set_auxdata()</a>. +</p><p>26 Methods using this object: +<div class='columns' style='columns: 17em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_aggregate_context'>sqlite3_aggregate_context</a></li> +<li><a href='#sqlite3_context_db_handle'>sqlite3_context_db_handle</a></li> +<li><a href='#sqlite3_get_auxdata'>sqlite3_get_auxdata</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_blob</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_blob64</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_double</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error16</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error_code</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error_nomem</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_error_toobig</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_int</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_int64</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_null</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_pointer</a></li> +<li><a href='#sqlite3_result_subtype'>sqlite3_result_subtype</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text16</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text16be</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text16le</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_text64</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_value</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob</a></li> +<li><a href='#sqlite3_result_blob'>sqlite3_result_zeroblob64</a></li> +<li><a href='#sqlite3_get_auxdata'>sqlite3_set_auxdata</a></li> +<li><a href='#sqlite3_user_data'>sqlite3_user_data</a></li> +</ul> +</div> +</p> +<hr><a name="sqlite3_data_directory"></a> +<h2>Name Of The Folder Holding Database Files</h2> +</div> +<blockquote><pre> +SQLITE_EXTERN char *sqlite3_data_directory; +</pre></blockquote> +<p> +If this global variable is made to point to a string which is +the name of a folder (a.k.a. directory), then all database files +specified with a relative pathname and created or accessed by +SQLite when using a built-in windows <a href="#sqlite3_vfs">VFS</a> will be assumed +to be relative to that directory. If this variable is a NULL +pointer, then SQLite assumes that all database files specified +with a relative pathname are relative to the current directory +for the process. Only the windows VFS makes use of this global +variable; it is ignored by the unix VFS.</p> + +<p>Changing the value of this variable while a database connection is +open can result in a corrupt database.</p> + +<p>It is not safe to read or modify this variable in more than one +thread at a time. It is not safe to read or modify this variable +if a <a href="#sqlite3">database connection</a> is being used at the same time in a separate +thread. +It is intended that this variable be set once +as part of process initialization and before any SQLite interface +routines have been called and that this variable remain unchanged +thereafter.</p> + +<p>The <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> may modify this variable and cause +it to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>. Furthermore, +the <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> always assumes that any string +that this variable points to is held in memory obtained from +<a href="#sqlite3_free">sqlite3_malloc</a> and the pragma may attempt to free that memory +using <a href="#sqlite3_free">sqlite3_free</a>. +Hence, if this variable is modified directly, either it should be +made NULL or made to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a> +or else the use of the <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> should be avoided. +</p><hr><a name="sqlite3_file"></a> +<h2>OS Interface Open File Handle</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_file sqlite3_file; +struct sqlite3_file { + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ +}; +</pre></blockquote> +<p> +An <a href="#sqlite3_file">sqlite3_file</a> object represents an open file in the +<a href="#sqlite3_vfs">OS interface layer</a>. 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 +<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object that defines methods for performing +I/O operations on the open file. +</p><hr><a name="sqlite3_filename"></a> +<h2>File Name</h2> +</div> +<blockquote><pre> +typedef const char *sqlite3_filename; +</pre></blockquote> +<p> +Type <a href="#sqlite3_filename">sqlite3_filename</a> is used by SQLite to pass filenames to the +xOpen method of a <a href="vfs.html">VFS</a>. It may be cast to (const char*) and treated +as a normal, nul-terminated, UTF-8 buffer containing the filename, but +may also be passed to special APIs such as:</p> + +<p><ul> +<li> sqlite3_filename_database() +<li> sqlite3_filename_journal() +<li> sqlite3_filename_wal() +<li> sqlite3_uri_parameter() +<li> sqlite3_uri_boolean() +<li> sqlite3_uri_int64() +<li> sqlite3_uri_key() +</ul> +</p><hr><a name="sqlite3_index_info"></a> +<h2>Virtual Table Indexing Information</h2> +</div> +<blockquote><pre> +struct sqlite3_index_info { + /* Inputs */ + int nConstraint; /* Number of entries in aConstraint */ + struct sqlite3_index_constraint { + int iColumn; /* Column constrained. -1 for ROWID */ + unsigned char op; /* Constraint operator */ + unsigned char usable; /* True if this constraint is usable */ + int iTermOffset; /* Used internally - xBestIndex should ignore */ + } *aConstraint; /* Table of WHERE clause constraints */ + int nOrderBy; /* Number of terms in the ORDER BY clause */ + struct sqlite3_index_orderby { + int iColumn; /* Column number */ + unsigned char desc; /* True for DESC. False for ASC. */ + } *aOrderBy; /* The ORDER BY clause */ + /* Outputs */ + struct sqlite3_index_constraint_usage { + int argvIndex; /* if >0, constraint is part of argv to xFilter */ + unsigned char omit; /* Do not code a test for this constraint */ + } *aConstraintUsage; + int idxNum; /* Number used to identify the index */ + char *idxStr; /* String, possibly obtained from sqlite3_malloc */ + int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ + int orderByConsumed; /* True if output is already ordered */ + double estimatedCost; /* Estimated cost of using this index */ + /* Fields below are only available in SQLite 3.8.2 and later */ + sqlite3_int64 estimatedRows; /* Estimated number of rows returned */ + /* Fields below are only available in SQLite 3.9.0 and later */ + int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */ + /* Fields below are only available in SQLite 3.10.0 and later */ + sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ +}; +</pre></blockquote> +<p> +The sqlite3_index_info structure and its substructures is used as part +of the <a href="vtab.html">virtual table</a> interface to +pass information into and receive the reply from the <a href="vtab.html#xbestindex">xBestIndex</a> +method of a <a href="#sqlite3_module">virtual table module</a>. The fields under **Inputs** are the +inputs to xBestIndex and are read-only. xBestIndex inserts its +results into the **Outputs** fields.</p> + +<p>The aConstraint[] array records WHERE clause constraints of the form:</p> + +<p><blockquote>column OP expr</blockquote></p> + +<p>where OP is =, <, <=, >, or >=. The particular operator is +stored in aConstraint[].op using one of the +<a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ values</a>. +The index of the column is stored in +aConstraint[].iColumn. aConstraint[].usable is TRUE if the +expr on the right-hand side can be evaluated (and thus the constraint +is usable) and false if it cannot.</p> + +<p>The optimizer automatically inverts terms of the form "expr OP column" +and makes other simplifications to the WHERE clause in an attempt to +get as many WHERE clause terms into the form shown above as possible. +The aConstraint[] array only reports WHERE clause terms that are +relevant to the particular virtual table being queried.</p> + +<p>Information about the ORDER BY clause is stored in aOrderBy[]. +Each term of aOrderBy records a column of the ORDER BY clause.</p> + +<p>The colUsed field indicates which columns of the virtual table may be +required by the current scan. Virtual table columns are numbered from +zero in the order in which they appear within the CREATE TABLE statement +passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62), +the corresponding bit is set within the colUsed mask if the column may be +required by SQLite. If the table has at least 64 columns and any column +to the right of the first 63 is required, then bit 63 of colUsed is also +set. In other words, column iCol may be required if the expression +(colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to +non-zero.</p> + +<p>The <a href="vtab.html#xbestindex">xBestIndex</a> method must fill aConstraintUsage[] with information +about what parameters to pass to xFilter. If argvIndex>0 then +the right-hand side of the corresponding aConstraint[] is evaluated +and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit +is true, then the constraint is assumed to be fully handled by the +virtual table and might not be checked again by the byte code. The +aConstraintUsage[].omit flag is an optimization hint. When the omit flag +is left in its default setting of false, the constraint will always be +checked separately in byte code. If the omit flag is change to true, then +the constraint may or may not be checked in byte code. In other words, +when the omit flag is true there is no guarantee that the constraint will +not be checked again using byte code.</p> + +<p>The idxNum and idxStr values are recorded and passed into the +<a href="vtab.html#xfilter">xFilter</a> method. +<a href="#sqlite3_free">sqlite3_free()</a> is used to free idxStr if and only if +needToFreeIdxStr is true.</p> + +<p>The orderByConsumed means that output from <a href="vtab.html#xfilter">xFilter</a>/<a href="vtab.html#xnext">xNext</a> will occur in +the correct order to satisfy the ORDER BY clause so that no separate +sorting step is required.</p> + +<p>The estimatedCost value is an estimate of the cost of a particular +strategy. A cost of N indicates that the cost of the strategy is similar +to a linear scan of an SQLite table with N rows. A cost of log(N) +indicates that the expense of the operation is similar to that of a +binary search on a unique indexed field of an SQLite table with N rows.</p> + +<p>The estimatedRows value is an estimate of the number of rows that +will be returned by the strategy.</p> + +<p>The xBestIndex method may optionally populate the idxFlags field with a +mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag - +SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite +assumes that the strategy may visit at most one row.</p> + +<p>Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then +SQLite also assumes that if a call to the xUpdate() method is made as +part of the same statement to delete or update a virtual table row and the +implementation returns SQLITE_CONSTRAINT, then there is no need to rollback +any database changes. In other words, if the xUpdate() returns +SQLITE_CONSTRAINT, the database contents must be exactly as they were +before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not +set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by +the xUpdate method are automatically rolled back by SQLite.</p> + +<p>IMPORTANT: The estimatedRows field was added to the sqlite3_index_info +structure for SQLite <a href="releaselog/3_8_2.html">version 3.8.2</a> (2013-12-06). +If a virtual table extension is +used with an SQLite version earlier than 3.8.2, the results of attempting +to read or write the estimatedRows field are undefined (but are likely +to include crashing the application). The estimatedRows field should +therefore only be used if <a href="#sqlite3_libversion">sqlite3_libversion_number()</a> returns a +value greater than or equal to 3008002. Similarly, the idxFlags field +was added for <a href="releaselog/3_9_0.html">version 3.9.0</a> (2015-10-14). +It may therefore only be used if +sqlite3_libversion_number() returns a value greater than or equal to +3009000. +</p><p>3 Methods using this object: + <a href="#sqlite3_vtab_collation">sqlite3_vtab_collation()</a>, +<a href="#sqlite3_vtab_distinct">sqlite3_vtab_distinct()</a>, +<a href="#sqlite3_vtab_rhs_value">sqlite3_vtab_rhs_value()</a></p> +<hr><a name="sqlite3_io_methods"></a> +<h2>OS Interface File Virtual Methods Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_io_methods sqlite3_io_methods; +struct sqlite3_io_methods { + int iVersion; + int (*xClose)(sqlite3_file*); + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); + int (*xSync)(sqlite3_file*, int flags); + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); + int (*xLock)(sqlite3_file*, int); + int (*xUnlock)(sqlite3_file*, int); + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); + int (*xFileControl)(sqlite3_file*, int op, void *pArg); + int (*xSectorSize)(sqlite3_file*); + int (*xDeviceCharacteristics)(sqlite3_file*); + /* Methods above are valid for version 1 */ + int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); + int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); + void (*xShmBarrier)(sqlite3_file*); + int (*xShmUnmap)(sqlite3_file*, int deleteFlag); + /* Methods above are valid for version 2 */ + int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp); + int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p); + /* Methods above are valid for version 3 */ + /* Additional methods may be added in future releases */ +}; +</pre></blockquote> +<p> +Every file opened by the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method populates an +<a href="#sqlite3_file">sqlite3_file</a> object (or, more commonly, a subclass of the +<a href="#sqlite3_file">sqlite3_file</a> object) with a pointer to an instance of this object. +This object defines the methods used to perform various operations +against the open file represented by the <a href="#sqlite3_file">sqlite3_file</a> object.</p> + +<p>If the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method sets the sqlite3_file.pMethods element +to a non-NULL pointer, then the sqlite3_io_methods.xClose method +may be invoked even if the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> reported that it failed. The +only way to prevent a call to xClose following a failed <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> +is for the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> to set the sqlite3_file.pMethods element +to NULL.</p> + +<p>The flags argument to xSync may be one of <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_NORMAL</a> or +<a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_FULL</a>. The first choice is the normal fsync(). +The second choice is a Mac OS X style fullsync. The <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_DATAONLY</a> +flag may be ORed in to indicate that only the data of the file +and not its inode needs to be synced.</p> + +<p>The integer values to xLock() and xUnlock() are one of +<ul> +<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>, +<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>, +<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>, +<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or +<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>. +</ul> +xLock() upgrades the database file lock. In other words, xLock() moves the +database file lock in the direction NONE toward EXCLUSIVE. The argument to +xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never +SQLITE_LOCK_NONE. If the database file lock is already at or above the +requested lock, then the call to xLock() is a no-op. +xUnlock() downgrades the database file lock to either SHARED or NONE. +to xUnlock() is a no-op. +The xCheckReservedLock() method checks whether any database connection, +either in this process or in some other process, is holding a RESERVED, +PENDING, or EXCLUSIVE lock on the file. It returns true +if such a lock exists and false otherwise.</p> + +<p>The xFileControl() method is a generic interface that allows custom +VFS implementations to directly control an open file using the +<a href="#sqlite3_file_control">sqlite3_file_control()</a> interface. The second "op" argument is an +integer opcode. The third argument is a generic pointer intended to +point 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 all opcodes less than 100 for its own use. +A <a href="#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE">list of opcodes</a> less than 100 is available. +Applications that define a custom xFileControl method should use opcodes +greater than 100 to avoid conflicts. VFS implementations should +return <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a> for file control opcodes that they do not +recognize.</p> + +<p>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:</p> + +<p><ul> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC512</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC1K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC2K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC4K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC8K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC16K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC32K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC64K</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SAFE_APPEND</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SEQUENTIAL</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_IMMUTABLE</a> +<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_BATCH_ATOMIC</a> +</ul></p> + +<p>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 +that when data is appended to a file, the data is appended +first then the size of the file is extended, never the other +way around. The SQLITE_IOCAP_SEQUENTIAL property means that +information is written to disk in the same order as calls +to xWrite().</p> + +<p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill +in the unread portions of the buffer with zeros. A VFS that +fails to zero-fill short reads might seem to work. However, +failure to zero-fill short reads will eventually lead to +database corruption. +</p><hr><a name="sqlite3_mem_methods"></a> +<h2>Memory Allocation Routines</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_mem_methods sqlite3_mem_methods; +struct sqlite3_mem_methods { + void *(*xMalloc)(int); /* Memory allocation function */ + void (*xFree)(void*); /* Free a prior allocation */ + void *(*xRealloc)(void*,int); /* Resize an allocation */ + int (*xSize)(void*); /* Return the size of an allocation */ + int (*xRoundup)(int); /* Round up request size to allocation size */ + int (*xInit)(void*); /* Initialize the memory allocator */ + void (*xShutdown)(void*); /* Deinitialize the memory allocator */ + void *pAppData; /* Argument to xInit() and xShutdown() */ +}; +</pre></blockquote> +<p> +An instance of this object defines the interface between SQLite +and low-level memory allocation routines.</p> + +<p>This object is used in only one place in the SQLite interface. +A pointer to an instance of this object is the argument to +<a href="#sqlite3_config">sqlite3_config()</a> when the configuration option is +<a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> or <a href="#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a>. +By creating an instance of this object +and passing it to <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>) +during configuration, an application can specify an alternative +memory allocation subsystem for SQLite to use for all of its +dynamic memory needs.</p> + +<p>Note that SQLite comes with several <a href="malloc.html#altalloc">built-in memory allocators</a> +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 +memory allocator that simulates memory out-of-memory conditions in +order to verify that SQLite recovers gracefully from such +conditions.</p> + +<p>The xMalloc, xRealloc, and xFree methods must work like the +malloc(), realloc() and free() functions from the standard C library. +SQLite guarantees that the second argument to +xRealloc is always a value returned by a prior call to xRoundup.</p> + +<p>xSize should return the allocated size of a memory allocation +previously obtained from xMalloc or xRealloc. The allocated size +is always at least as big as the requested size but may be larger.</p> + +<p>The xRoundup method returns what would be the allocated size of +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 <a href="#sqlite3_free">sqlite3_malloc()</a> +or <a href="#sqlite3_free">sqlite3_realloc()</a> first calls xRoundup. If xRoundup returns 0, +that causes the corresponding memory allocation to fail.</p> + +<p>The xInit method initializes the memory allocator. For example, +it might allocate any required mutexes or initialize internal data +structures. The xShutdown method is invoked (indirectly) by +<a href="#sqlite3_initialize">sqlite3_shutdown()</a> and should deallocate any resources acquired +by xInit. The pAppData pointer is used as the only parameter to +xInit and xShutdown.</p> + +<p>SQLite holds the <a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MAIN</a> mutex when it invokes +the xInit method, so the xInit method need not be threadsafe. The +xShutdown method is only called from <a href="#sqlite3_initialize">sqlite3_shutdown()</a> so it does +not need to be threadsafe either. For all other methods, SQLite +holds the <a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MEM</a> mutex as long as the +<a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> configuration option is turned on (which +it is by default) and so the methods are automatically serialized. +However, if <a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled, then the other +methods must be threadsafe or else make their own arrangements for +serialization.</p> + +<p>SQLite will never invoke xInit() more than once without an intervening +call to xShutdown(). +</p><hr><a name="sqlite3_mutex"></a> +<h2>Mutex Handle</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_mutex sqlite3_mutex; +</pre></blockquote> +<p> +The mutex module within SQLite defines <a href="#sqlite3_mutex">sqlite3_mutex</a> to be an +abstract type for a mutex object. The SQLite core never looks +at the internal representation of an <a href="#sqlite3_mutex">sqlite3_mutex</a>. It only +deals with pointers to the <a href="#sqlite3_mutex">sqlite3_mutex</a> object.</p> + +<p>Mutexes are created using <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a>. +</p><hr><a name="sqlite3_mutex_methods"></a> +<h2>Mutex Methods Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; +struct sqlite3_mutex_methods { + int (*xMutexInit)(void); + int (*xMutexEnd)(void); + sqlite3_mutex *(*xMutexAlloc)(int); + void (*xMutexFree)(sqlite3_mutex *); + void (*xMutexEnter)(sqlite3_mutex *); + int (*xMutexTry)(sqlite3_mutex *); + void (*xMutexLeave)(sqlite3_mutex *); + int (*xMutexHeld)(sqlite3_mutex *); + int (*xMutexNotheld)(sqlite3_mutex *); +}; +</pre></blockquote> +<p> +An instance of this structure defines the low-level routines +used to allocate and use mutexes.</p> + +<p>Usually, the default mutex implementations provided by SQLite are +sufficient, however the application has the option of substituting a custom +implementation for specialized deployments or systems for which SQLite +does not provide a suitable implementation. In this case, the application +creates and populates an instance of this structure to pass +to sqlite3_config() along with the <a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option. +Additionally, an instance of this structure can be used as an +output variable when querying the system for the current mutex +implementation, using the <a href="#sqliteconfiggetmutex">SQLITE_CONFIG_GETMUTEX</a> option.</p> + +<p>The xMutexInit method defined by this structure is invoked as +part of system initialization by the sqlite3_initialize() function. +The xMutexInit routine is called by SQLite exactly once for each +effective call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>.</p> + +<p>The xMutexEnd method defined by this structure is invoked as +part of system shutdown by the sqlite3_shutdown() function. The +implementation of this method is expected to release all outstanding +resources obtained by the mutex methods implementation, especially +those obtained by the xMutexInit method. The xMutexEnd() +interface is invoked exactly once for each call to <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.</p> + +<p>The remaining seven methods defined by this structure (xMutexAlloc, +xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and +xMutexNotheld) implement the following interfaces (respectively):</p> + +<p><ul> +<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> </li> +<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_free()</a> </li> +<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter()</a> </li> +<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_try()</a> </li> +<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave()</a> </li> +<li> <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> </li> +<li> <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a> </li> +</ul></p> + +<p>The only difference is that the public sqlite3_XXX functions enumerated +above silently ignore any invocations that pass a NULL pointer instead +of a valid mutex handle. The implementations of the methods defined +by this structure are not required to handle this case. The results +of passing a NULL pointer instead of a valid mutex handle are undefined +(i.e. it is acceptable to provide an implementation that segfaults if +it is passed a NULL pointer).</p> + +<p>The xMutexInit() method must be threadsafe. It must be harmless to +invoke xMutexInit() multiple times within the same process and without +intervening calls to xMutexEnd(). Second and subsequent calls to +xMutexInit() must be no-ops.</p> + +<p>xMutexInit() must not use SQLite memory allocation (<a href="#sqlite3_free">sqlite3_malloc()</a> +and its associates). Similarly, xMutexAlloc() must not use SQLite memory +allocation for a static mutex. However xMutexAlloc() may use SQLite +memory allocation for a fast or recursive mutex.</p> + +<p>SQLite will invoke the xMutexEnd() method when <a href="#sqlite3_initialize">sqlite3_shutdown()</a> is +called, but only if the prior call to xMutexInit returned SQLITE_OK. +If xMutexInit fails in any way, it is expected to clean up after itself +prior to returning. +</p><hr><a name="sqlite3_pcache"></a> +<h2>Custom Page Cache Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_pcache sqlite3_pcache; +</pre></blockquote> +<p> +The sqlite3_pcache type is opaque. It is implemented by +the pluggable module. The SQLite core has no knowledge of +its size or internal structure and never deals with the +sqlite3_pcache object except by holding and passing pointers +to the object.</p> + +<p>See <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> for additional information. +</p><hr><a name="sqlite3_pcache_page"></a> +<h2>Custom Page Cache Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_pcache_page sqlite3_pcache_page; +struct sqlite3_pcache_page { + void *pBuf; /* The content of the page */ + void *pExtra; /* Extra information associated with the page */ +}; +</pre></blockquote> +<p> +The sqlite3_pcache_page object represents a single page in the +page cache. The page cache will allocate instances of this +object. Various methods of the page cache use pointers to instances +of this object as parameters or as their return value.</p> + +<p>See <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> for additional information. +</p><hr><a name="sqlite3_temp_directory"></a> +<h2>Name Of The Folder Holding Temporary Files</h2> +</div> +<blockquote><pre> +SQLITE_EXTERN char *sqlite3_temp_directory; +</pre></blockquote> +<p> +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 +created by SQLite when using a built-in <a href="#sqlite3_vfs">VFS</a> +will be placed in that directory. If this variable +is a NULL pointer, then SQLite performs a search for an appropriate +temporary file directory.</p> + +<p>Applications are strongly discouraged from using this global variable. +It is required to set a temporary folder on Windows Runtime (WinRT). +But for all other platforms, it is highly recommended that applications +neither read nor write this variable. This global variable is a relic +that exists for backwards compatibility of legacy applications and should +be avoided in new projects.</p> + +<p>It is not safe to read or modify this variable in more than one +thread at a time. It is not safe to read or modify this variable +if a <a href="#sqlite3">database connection</a> is being used at the same time in a separate +thread. +It is intended that this variable be set once +as part of process initialization and before any SQLite interface +routines have been called and that this variable remain unchanged +thereafter.</p> + +<p>The <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> may modify this variable and cause +it to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>. Furthermore, +the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> always assumes that any string +that this variable points to is held in memory obtained from +<a href="#sqlite3_free">sqlite3_malloc</a> and the pragma may attempt to free that memory +using <a href="#sqlite3_free">sqlite3_free</a>. +Hence, if this variable is modified directly, either it should be +made NULL or made to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a> +or else the use of the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> should be avoided. +Except when requested by the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a>, SQLite +does not free the memory that sqlite3_temp_directory points to. If +the application wants that memory to be freed, it must do +so itself, taking care to only do so after all <a href="#sqlite3">database connection</a> +objects have been destroyed.</p> + +<p><b>Note to Windows Runtime users:</b> The temporary directory must be set +prior to calling <a href="#sqlite3_open">sqlite3_open</a> or <a href="#sqlite3_open">sqlite3_open_v2</a>. Otherwise, various +features that require the use of temporary files may fail. Here is an +example of how to do this using C++ with the Windows Runtime:</p> + +<p><blockquote><pre> +LPCWSTR zPath = Windows::Storage::ApplicationData::Current-> + TemporaryFolder->Path->Data(); +char zPathBuf[MAX_PATH + 1]; +memset(zPathBuf, 0, sizeof(zPathBuf)); +WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf), + NULL, NULL); +sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf); +</pre></blockquote> +</p><hr><a name="sqlite3_vfs"></a> +<h2>OS Interface Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_vfs sqlite3_vfs; +typedef void (*sqlite3_syscall_ptr)(void); +struct sqlite3_vfs { + int iVersion; /* Structure version number (currently 3) */ + int szOsFile; /* Size of subclassed sqlite3_file */ + int mxPathname; /* Maximum file pathname length */ + sqlite3_vfs *pNext; /* Next registered VFS */ + const char *zName; /* Name of this virtual file system */ + void *pAppData; /* Pointer to application-specific data */ + int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*, + int flags, int *pOutFlags); + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); + void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); + void (*xDlClose)(sqlite3_vfs*, void*); + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); + int (*xSleep)(sqlite3_vfs*, int microseconds); + int (*xCurrentTime)(sqlite3_vfs*, double*); + int (*xGetLastError)(sqlite3_vfs*, int, char *); + /* + ** The methods above are in version 1 of the sqlite_vfs object + ** definition. Those that follow are added in version 2 or later + */ + int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); + /* + ** The methods above are in versions 1 and 2 of the sqlite_vfs object. + ** Those below are for version 3 and greater. + */ + int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); + sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); + const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); + /* + ** The methods above are in versions 1 through 3 of the sqlite_vfs object. + ** New fields may be appended in future versions. The iVersion + ** value will increment whenever this happens. + */ +}; +</pre></blockquote> +<p> +An instance of the sqlite3_vfs object defines the interface between +the SQLite core and the underlying operating system. The "vfs" +in the name of the object stands for "virtual file system". See +the <a href="vfs.html">VFS documentation</a> for further information.</p> + +<p>The VFS interface is sometimes extended by adding new methods onto +the end. Each time such an extension occurs, the iVersion field +is incremented. The iVersion value started out as 1 in +SQLite <a href="releaselog/3_5_0.html">version 3.5.0</a> on 2007-09-04, then increased to 2 +with SQLite <a href="releaselog/3_7_0.html">version 3.7.0</a> on 2010-07-21, and then increased +to 3 with SQLite <a href="releaselog/3_7_6.html">version 3.7.6</a> on 2011-04-12. Additional fields +may be appended to the sqlite3_vfs object and the iVersion value +may increase again in future versions of SQLite. +Note that due to an oversight, the structure +of the sqlite3_vfs object changed in the transition from +SQLite <a href="releaselog/3_5_9.html">version 3.5.9</a> to <a href="releaselog/3_6_0.html">version 3.6.0</a> on 2008-07-16 +and yet the iVersion field was not increased.</p> + +<p>The szOsFile field is the size of the subclassed <a href="#sqlite3_file">sqlite3_file</a> +structure used by this VFS. mxPathname is the maximum length of +a pathname in this VFS.</p> + +<p>Registered sqlite3_vfs objects are kept on a linked list formed by +the pNext pointer. The <a href="#sqlite3_vfs_find">sqlite3_vfs_register()</a> +and <a href="#sqlite3_vfs_find">sqlite3_vfs_unregister()</a> interfaces manage this list +in a thread-safe way. The <a href="#sqlite3_vfs_find">sqlite3_vfs_find()</a> interface +searches the list. Neither the application code nor the VFS +implementation should use the pNext pointer.</p> + +<p>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.</p> + +<p>The zName field holds the name of the VFS module. The name must +be unique across all VFS modules.</p> + +<p><a name="sqlite3vfsxopen"></a> + +SQLite guarantees that the zFilename parameter to xOpen +is either a NULL pointer or string obtained +from xFullPathname() with an optional suffix added. +If a suffix is added to the zFilename parameter, it will +consist of a single "-" character followed by no more than +11 alphanumeric and/or "-" characters. +SQLite further guarantees that +the string will be valid and unchanged until xClose() is +called. Because of the previous sentence, +the <a href="#sqlite3_file">sqlite3_file</a> can safely store a pointer to the +filename if it needs to remember the filename for some reason. +If the zFilename parameter to xOpen is a NULL pointer then xOpen +must invent its own temporary name for the file. Whenever the +xFilename parameter is NULL it will also be the case that the +flags parameter will include <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>.</p> + +<p>The flags argument to xOpen() includes all bits set in +the flags argument to <a href="#sqlite3_open">sqlite3_open_v2()</a>. Or if <a href="#sqlite3_open">sqlite3_open()</a> +or <a href="#sqlite3_open">sqlite3_open16()</a> is used, then flags includes at least +<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a> | <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a>. +If xOpen() opens a file read-only then it sets *pOutFlags to +include <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be set.</p> + +<p>SQLite will also add one of the following flags to the xOpen() +call, depending on the object being opened:</p> + +<p><ul> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_DB</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_JOURNAL</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_DB</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_JOURNAL</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TRANSIENT_DB</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SUBJOURNAL</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SUPER_JOURNAL</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_WAL</a> +</ul></p> + +<p>The file I/O implementation can use the object type flags to +change 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.</p> + +<p>SQLite might also add one of the following flags to the xOpen method:</p> + +<p><ul> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a> +<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a> +</ul></p> + +<p>The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be +deleted when it is closed. The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a> +will be set for TEMP databases and their journals, transient +databases, and subjournals.</p> + +<p>The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a> flag is always used in conjunction +with the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a> flag, which are both directly +analogous to the O_EXCL and O_CREAT flags of the POSIX open() +API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the +SQLITE_OPEN_CREATE, is used to indicate that file should always +be created, and that it is an error if it already exists. +It is <i>not</i> used to indicate the file should be opened +for exclusive access.</p> + +<p>At least szOsFile bytes of memory are allocated by SQLite +to hold the <a href="#sqlite3_file">sqlite3_file</a> structure passed as the third +argument to xOpen. The xOpen method does not have to +allocate the structure; it should just fill it in. Note that +the xOpen method must set the sqlite3_file.pMethods to either +a valid <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object or to NULL. xOpen must do +this even if the open fails. SQLite expects that the sqlite3_file.pMethods +element will be valid after xOpen returns regardless of the success +or failure of the xOpen call.</p> + +<p><a name="sqlite3vfsxaccess"></a> + +The flags argument to xAccess() may be <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_EXISTS</a> +to test for the existence of a file, or <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READWRITE</a> to +test whether a file is readable and writable, or <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READ</a> +to test whether a file is at least readable. The SQLITE_ACCESS_READ +flag is never actually used and is not implemented in the built-in +VFSes of SQLite. The file is named by the second argument and can be a +directory. The xAccess method returns <a href="#SQLITE_ABORT">SQLITE_OK</a> on success or some +non-zero error code if there is an I/O error or if the name of +the file given in the second argument is illegal. If SQLITE_OK +is returned, then non-zero or zero is written into *pResOut to indicate +whether or not the file is accessible.</p> + +<p>SQLite will always allocate at least mxPathname+1 bytes for the +output buffer xFullPathname. The exact size of the output buffer +is also passed as a parameter to both methods. If the output buffer +is not large enough, <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a> 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.</p> + +<p>The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() +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 as +a floating point value. +The xCurrentTimeInt64() method returns, as an integer, the Julian +Day Number multiplied by 86400000 (the number of milliseconds in +a 24-hour day). +SQLite will use the xCurrentTimeInt64() method to get the current +date and time if that method is available (if iVersion is 2 or +greater and the function pointer is not NULL) and will fall back +to xCurrentTime() if xCurrentTimeInt64() is unavailable.</p> + +<p>The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces +are not used by the SQLite core. These optional interfaces are provided +by some VFSes to facilitate testing of the VFS code. By overriding +system calls with functions under its control, a test program can +simulate faults and error conditions that would otherwise be difficult +or impossible to induce. The set of system calls that can be overridden +varies from one VFS to another, and from one version of the same VFS to the +next. Applications that use these interfaces must be prepared for any +or all of these interfaces to be NULL or for their behavior to change +from one release to the next. Applications must not attempt to access +any of these methods if the iVersion of the VFS is less than 3. +</p><hr><a name="sqlite3_vtab"></a> +<h2>Virtual Table Instance Object</h2> +</div> +<blockquote><pre> +struct sqlite3_vtab { + const sqlite3_module *pModule; /* The module for this virtual table */ + int nRef; /* Number of open cursors */ + char *zErrMsg; /* Error message from sqlite3_mprintf() */ + /* Virtual table implementations will typically add additional fields */ +}; +</pre></blockquote> +<p> +Every <a href="#sqlite3_module">virtual table module</a> implementation uses a subclass +of this object to describe a particular instance +of the <a href="vtab.html">virtual table</a>. Each subclass will +be tailored to the specific needs of the module implementation. +The purpose of this superclass is to define certain fields that are +common to all module implementations.</p> + +<p>Virtual tables methods can set an error message by assigning a +string obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a> to zErrMsg. The method should +take care that any prior string is freed by a call to <a href="#sqlite3_free">sqlite3_free()</a> +prior to assigning a new string to zErrMsg. After the error message +is delivered up to the client application, the string will be automatically +freed by sqlite3_free() and the zErrMsg field will be zeroed. +</p><hr><a name="sqlite3_aggregate_context"></a> +<h2>Obtain Aggregate Function Context</h2> +</div> +<blockquote><pre> +void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); +</pre></blockquote> +<p> +Implementations of aggregate SQL functions use this +routine to allocate memory for storing their state.</p> + +<p>The first time the sqlite3_aggregate_context(C,N) routine is called +for a particular aggregate function, SQLite allocates +N bytes of memory, zeroes out that memory, and returns a pointer +to the new memory. On second and subsequent calls to +sqlite3_aggregate_context() for the same aggregate function instance, +the same buffer is returned. Sqlite3_aggregate_context() is normally +called once for each invocation of the xStep callback and then one +last time when the xFinal callback is invoked. When no rows match +an aggregate query, the xStep() callback of the aggregate function +implementation is never called and xFinal() is called exactly once. +In those cases, sqlite3_aggregate_context() might be called for the +first time from within xFinal().</p> + +<p>The sqlite3_aggregate_context(C,N) routine returns a NULL pointer +when first called if N is less than or equal to zero or if a memory +allocation error occurs.</p> + +<p>The amount of space allocated by sqlite3_aggregate_context(C,N) is +determined by the N parameter on first successful call. Changing the +value of N in any subsequent call to sqlite3_aggregate_context() within +the same aggregate function instance will not resize the memory +allocation. Within the xFinal callback, it is customary to set +N=0 in calls to sqlite3_aggregate_context(C,N) so that no +pointless memory allocations occur.</p> + +<p>SQLite automatically frees the memory allocated by +sqlite3_aggregate_context() when the aggregate query concludes.</p> + +<p>The first parameter must be a copy of the +<a href="#sqlite3_context">SQL function context</a> that is the first parameter +to the xStep or xFinal callback routine that implements the aggregate +function.</p> + +<p>This routine must be called from the same thread in which +the aggregate SQL function is running. +</p><hr><a name="sqlite3_auto_extension"></a> +<h2>Automatically Load Statically Linked Extensions</h2> +</div> +<blockquote><pre> +int sqlite3_auto_extension(void(*xEntryPoint)(void)); +</pre></blockquote> +<p> +This interface causes the xEntryPoint() function to be invoked for +each new <a href="#sqlite3">database connection</a> that is created. The idea here is that +xEntryPoint() is the entry point for a statically linked <a href="loadext.html">SQLite extension</a> +that is to be automatically loaded into all new database connections.</p> + +<p>Even though the function prototype shows that xEntryPoint() takes +no arguments and returns void, SQLite invokes xEntryPoint() with three +arguments and expects an integer result as if the signature of the +entry point where as follows:</p> + +<p><blockquote><pre> + int xEntryPoint( + sqlite3 *db, + const char **pzErrMsg, + const struct sqlite3_api_routines *pThunk + ); +</pre></blockquote></p> + +<p>If the xEntryPoint routine encounters an error, it should make *pzErrMsg +point to an appropriate error message (obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a>) +and return an appropriate <a href="rescode.html">error code</a>. SQLite ensures that *pzErrMsg +is NULL before calling the xEntryPoint(). SQLite will invoke +<a href="#sqlite3_free">sqlite3_free()</a> on *pzErrMsg after xEntryPoint() returns. If any +xEntryPoint() returns an error, the <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, +or <a href="#sqlite3_open">sqlite3_open_v2()</a> call that provoked the xEntryPoint() will fail.</p> + +<p>Calling sqlite3_auto_extension(X) with an entry point X that is already +on the list of automatic extensions is a harmless no-op. No entry point +will be called more than once for each database connection that is opened.</p> + +<p>See also: <a href="#sqlite3_reset_auto_extension">sqlite3_reset_auto_extension()</a> +and <a href="#sqlite3_cancel_auto_extension">sqlite3_cancel_auto_extension()</a> +</p><hr><a name="sqlite3_autovacuum_pages"></a> +<h2>Autovacuum Compaction Amount Callback</h2> +</div> +<blockquote><pre> +int sqlite3_autovacuum_pages( + sqlite3 *db, + unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int), + void*, + void(*)(void*) +); +</pre></blockquote> +<p> +The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback +function C that is invoked prior to each autovacuum of the database +file. The callback is passed a copy of the generic data pointer (P), +the schema-name of the attached database that is being autovacuumed, +the size of the database file in pages, the number of free pages, +and the number of bytes per page, respectively. The callback should +return the number of free pages that should be removed by the +autovacuum. If the callback returns zero, then no autovacuum happens. +If the value returned is greater than or equal to the number of +free pages, then a complete autovacuum happens.</p> + +<p><p>If there are multiple ATTACH-ed database files that are being +modified as part of a transaction commit, then the autovacuum pages +callback is invoked separately for each file.</p> + +<p><p><b>The callback is not reentrant.</b> The callback function should +not attempt to invoke any other SQLite interface. If it does, bad +things may happen, including segmentation faults and corrupt database +files. The callback function should be a simple function that +does some arithmetic on its input parameters and returns a result.</p> + +<p>The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional +destructor for the P parameter. If X is not NULL, then X(P) is +invoked whenever the database connection closes or when the callback +is overwritten by another invocation of sqlite3_autovacuum_pages().</p> + +<p><p>There is only one autovacuum pages callback per database connection. +Each call to the sqlite3_autovacuum_pages() interface overrides all +previous invocations for that database connection. If the callback +argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer, +then the autovacuum steps callback is canceled. The return value +from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might +be some other error code if something goes wrong. The current +implementation will only return SQLITE_OK or SQLITE_MISUSE, but other +return codes might be added in future releases.</p> + +<p><p>If no autovacuum pages callback is specified (the usual case) or +a NULL pointer is provided for the callback, +then the default behavior is to vacuum all free pages. So, in other +words, the default behavior is the same as if the callback function +were something like this:</p> + +<p><blockquote><pre> + unsigned int demonstration_autovac_pages_callback( + void *pClientData, + const char *zSchema, + unsigned int nDbPage, + unsigned int nFreePage, + unsigned int nBytePerPage + ){ + return nFreePage; + } +</pre></blockquote> +</p><hr><a name="sqlite3_bind_parameter_count"></a> +<h2>Number Of SQL Parameters</h2> +</div> +<blockquote><pre> +int sqlite3_bind_parameter_count(sqlite3_stmt*); +</pre></blockquote> +<p> +This routine can be used to find the number of <a href="#sqlite3_bind_blob">SQL parameters</a> +in a <a href="#sqlite3_stmt">prepared statement</a>. SQL parameters are tokens of the +form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as +placeholders for values that are <a href="#sqlite3_bind_blob">bound</a> +to the parameters at a later time.</p> + +<p>This routine actually returns the index of the largest (rightmost) +parameter. For all forms except ?NNN, this will correspond to the +number of unique parameters. If parameters of the ?NNN form are used, +there may be gaps in the list.</p> + +<p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>, +<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and +<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>. +</p><hr><a name="sqlite3_bind_parameter_index"></a> +<h2>Index Of A Parameter With A Given Name</h2> +</div> +<blockquote><pre> +int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); +</pre></blockquote> +<p> +Return the index of an SQL parameter given its name. The +index value returned is suitable for use as the second +parameter to <a href="#sqlite3_bind_blob">sqlite3_bind()</a>. A zero +is returned if no matching parameter is found. The parameter +name must be given in UTF-8 even if the original statement +was prepared from UTF-16 text using <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or +<a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>.</p> + +<p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>, +<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and +<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>. +</p><hr><a name="sqlite3_bind_parameter_name"></a> +<h2>Name Of A Host Parameter</h2> +</div> +<blockquote><pre> +const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); +</pre></blockquote> +<p> +The sqlite3_bind_parameter_name(P,N) interface returns +the name of the N-th <a href="#sqlite3_bind_blob">SQL parameter</a> in the <a href="#sqlite3_stmt">prepared statement</a> P. +SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" +have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" +respectively. +In other words, the initial ":" or "$" or "@" or "?" +is included as part of the name. +Parameters of the form "?" without a following integer have no name +and are referred to as "nameless" or "anonymous parameters".</p> + +<p>The first host parameter has an index of 1, not 0.</p> + +<p>If the value N is out of range or if the N-th parameter is +nameless, then NULL is returned. The returned string is +always in UTF-8 encoding even if the named parameter was +originally specified as UTF-16 in <a href="#sqlite3_prepare">sqlite3_prepare16()</a>, +<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>, or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>.</p> + +<p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>, +<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and +<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>. +</p><hr><a name="sqlite3_blob_bytes"></a> +<h2>Return The Size Of An Open BLOB</h2> +</div> +<blockquote><pre> +int sqlite3_blob_bytes(sqlite3_blob *); +</pre></blockquote> +<p> +Returns the size in bytes of the BLOB accessible via the +successfully opened <a href="#sqlite3_blob">BLOB handle</a> in its only argument. The +incremental blob I/O routines can only read or overwriting existing +blob content; they cannot change the size of a blob.</p> + +<p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created +by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not +been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in +to this routine results in undefined and probably undesirable behavior. +</p><hr><a name="sqlite3_blob_close"></a> +<h2>Close A BLOB Handle</h2> +</div> +<blockquote><pre> +int sqlite3_blob_close(sqlite3_blob *); +</pre></blockquote> +<p> +This function closes an open <a href="#sqlite3_blob">BLOB handle</a>. The BLOB handle is closed +unconditionally. Even if this routine returns an error code, the +handle is still closed.</p> + +<p>If the blob handle being closed was opened for read-write access, and if +the database is in auto-commit mode and there are no other open read-write +blob handles or active write statements, the current transaction is +committed. If an error occurs while committing the transaction, an error +code is returned and the transaction rolled back.</p> + +<p>Calling this function with an argument that is not a NULL pointer or an +open blob handle results in undefined behavior. Calling this routine +with a null pointer (such as would be returned by a failed call to +<a href="#sqlite3_blob_open">sqlite3_blob_open()</a>) is a harmless no-op. Otherwise, if this function +is passed a valid open blob handle, the values returned by the +sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. +</p><hr><a name="sqlite3_blob_open"></a> +<h2>Open A BLOB For Incremental I/O</h2> +</div> +<blockquote><pre> +int sqlite3_blob_open( + sqlite3*, + const char *zDb, + const char *zTable, + const char *zColumn, + sqlite3_int64 iRow, + int flags, + sqlite3_blob **ppBlob +); +</pre></blockquote> +<p> +This interfaces opens a <a href="#sqlite3_blob">handle</a> 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:</p> + +<p><pre> +SELECT zColumn FROM zDb.zTable WHERE <a href="lang_createtable.html#rowid">rowid</a> = iRow; +</pre></p> + +<p>Parameter zDb is not the filename that contains the database, but +rather the symbolic name of the database. For attached databases, this is +the name that appears after the AS keyword in the <a href="lang_attach.html">ATTACH</a> statement. +For the main database file, the database name is "main". For TEMP +tables, the database name is "temp".</p> + +<p>If the flags parameter is non-zero, then the BLOB is opened for read +and write access. If the flags parameter is zero, the BLOB is opened for +read-only access.</p> + +<p>On success, <a href="#SQLITE_ABORT">SQLITE_OK</a> is returned and the new <a href="#sqlite3_blob">BLOB handle</a> is stored +in *ppBlob. Otherwise an <a href="rescode.html">error code</a> is returned and, unless the error +code is SQLITE_MISUSE, *ppBlob is set to NULL. This means that, provided +the API is not misused, it is always safe to call <a href="#sqlite3_blob_close">sqlite3_blob_close()</a> +on *ppBlob after this function it returns.</p> + +<p>This function fails with SQLITE_ERROR if any of the following are true: +<ul> +<li> Database zDb does not exist, +<li> Table zTable does not exist within database zDb, +<li> Table zTable is a WITHOUT ROWID table, +<li> Column zColumn does not exist, +<li> Row iRow is not present in the table, +<li> The specified column of row iRow contains a value that is not +a TEXT or BLOB value, +<li> Column zColumn is part of an index, PRIMARY KEY or UNIQUE +constraint and the blob is being opened for read/write access, +<li> <a href="foreignkeys.html">Foreign key constraints</a> are enabled, +column zColumn is part of a <a href="foreignkeys.html#parentchild">child key</a> definition and the blob is +being opened for read/write access. +</ul></p> + +<p>Unless it returns SQLITE_MISUSE, this function sets the +<a href="#sqlite3">database connection</a> error code and message accessible via +<a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> and related functions.</p> + +<p>A BLOB referenced by sqlite3_blob_open() may be read using the +<a href="#sqlite3_blob_read">sqlite3_blob_read()</a> interface and modified by using +<a href="#sqlite3_blob_write">sqlite3_blob_write()</a>. The <a href="#sqlite3_blob">BLOB handle</a> can be moved to a +different row of the same table using the <a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a> +interface. However, the column, table, or database of a <a href="#sqlite3_blob">BLOB handle</a> +cannot be changed after the <a href="#sqlite3_blob">BLOB handle</a> is opened.</p> + +<p>If the row that a BLOB handle points to is modified by an +<a href="lang_update.html">UPDATE</a>, <a href="lang_delete.html">DELETE</a>, or by <a href="lang_conflict.html">ON CONFLICT</a> side-effects +then the BLOB handle is marked as "expired". +This is true if any column of the row is changed, even a column +other than the one the BLOB handle is open on. +Calls to <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> for +an expired BLOB handle fail with a return code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>. +Changes written into a BLOB prior to the BLOB expiring are not +rolled back by the expiration of the BLOB. Such changes will eventually +commit if the transaction continues to completion.</p> + +<p>Use the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface to determine the size of +the opened blob. The size of a blob may not be changed by this +interface. Use the <a href="lang_update.html">UPDATE</a> SQL command to change the size of a +blob.</p> + +<p>The <a href="#sqlite3_bind_blob">sqlite3_bind_zeroblob()</a> and <a href="#sqlite3_result_blob">sqlite3_result_zeroblob()</a> interfaces +and the built-in <a href="lang_corefunc.html#zeroblob">zeroblob</a> SQL function may be used to create a +zero-filled blob to read or write using the incremental-blob interface.</p> + +<p>To avoid a resource leak, every open <a href="#sqlite3_blob">BLOB handle</a> should eventually +be released by a call to <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.</p> + +<p>See also: <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>, +<a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a>, <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>, +<a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a>, <a href="#sqlite3_blob_write">sqlite3_blob_write()</a>. +</p><hr><a name="sqlite3_blob_read"></a> +<h2>Read Data From A BLOB Incrementally</h2> +</div> +<blockquote><pre> +int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); +</pre></blockquote> +<p> +This function is used to read data from an open <a href="#sqlite3_blob">BLOB handle</a> into a +caller-supplied buffer. N bytes of data are copied into buffer Z +from the open BLOB, starting at offset iOffset.</p> + +<p>If offset iOffset is less than N bytes from the end of the BLOB, +<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read. If N or iOffset is +less than zero, <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read. +The size of the blob (and hence the maximum value of N+iOffset) +can be determined using the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface.</p> + +<p>An attempt to read from an expired <a href="#sqlite3_blob">BLOB handle</a> fails with an +error code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>.</p> + +<p>On success, sqlite3_blob_read() returns SQLITE_OK. +Otherwise, an <a href="rescode.html">error code</a> or an <a href="rescode.html#extrc">extended error code</a> is returned.</p> + +<p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created +by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not +been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in +to this routine results in undefined and probably undesirable behavior.</p> + +<p>See also: <a href="#sqlite3_blob_write">sqlite3_blob_write()</a>. +</p><hr><a name="sqlite3_blob_reopen"></a> +<h2>Move a BLOB Handle to a New Row</h2> +</div> +<blockquote><pre> +int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); +</pre></blockquote> +<p> +This function is used to move an existing <a href="#sqlite3_blob">BLOB handle</a> so that it points +to a different row of the same database table. The new row is identified +by the rowid value passed as the second argument. Only the row can be +changed. The database, table and column on which the blob handle is open +remain the same. Moving an existing <a href="#sqlite3_blob">BLOB handle</a> to a new row is +faster than closing the existing handle and opening a new one.</p> + +<p>The new row must meet the same criteria as for <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> - +it must exist and there must be either a blob or text value stored in +the nominated column. If the new row is not present in the table, or if +it does not contain a blob or text value, or if another error occurs, an +SQLite error code is returned and the blob handle is considered aborted. +All subsequent calls to <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>, <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> or +<a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a> on an aborted blob handle immediately return +SQLITE_ABORT. Calling <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> on an aborted blob handle +always returns zero.</p> + +<p>This function sets the database handle error code and message. +</p><hr><a name="sqlite3_blob_write"></a> +<h2>Write Data Into A BLOB Incrementally</h2> +</div> +<blockquote><pre> +int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); +</pre></blockquote> +<p> +This function is used to write data into an open <a href="#sqlite3_blob">BLOB handle</a> from a +caller-supplied buffer. N bytes of data are copied from the buffer Z +into the open BLOB, starting at offset iOffset.</p> + +<p>On success, sqlite3_blob_write() returns SQLITE_OK. +Otherwise, an <a href="rescode.html">error code</a> or an <a href="rescode.html#extrc">extended error code</a> is returned. +Unless SQLITE_MISUSE is returned, this function sets the +<a href="#sqlite3">database connection</a> error code and message accessible via +<a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> and related functions.</p> + +<p>If the <a href="#sqlite3_blob">BLOB handle</a> passed as the first argument was not opened for +writing (the flags parameter to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> was zero), +this function returns <a href="#SQLITE_ABORT">SQLITE_READONLY</a>.</p> + +<p>This function may only modify the contents of the BLOB; it is +not possible to increase the size of a BLOB using this API. +If offset iOffset is less than N bytes from the end of the BLOB, +<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written. The size of the +BLOB (and hence the maximum value of N+iOffset) can be determined +using the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface. If N or iOffset are less +than zero <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written.</p> + +<p>An attempt to write to an expired <a href="#sqlite3_blob">BLOB handle</a> fails with an +error code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>. Writes to the BLOB that occurred +before the <a href="#sqlite3_blob">BLOB handle</a> expired are not rolled back by the +expiration of the handle, though of course those changes might +have been overwritten by the statement that expired the BLOB handle +or by other independent statements.</p> + +<p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created +by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not +been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in +to this routine results in undefined and probably undesirable behavior.</p> + +<p>See also: <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>. +</p><hr><a name="sqlite3_busy_timeout"></a> +<h2>Set A Busy Timeout</h2> +</div> +<blockquote><pre> +int sqlite3_busy_timeout(sqlite3*, int ms); +</pre></blockquote> +<p> +This routine sets a <a href="#sqlite3_busy_handler">busy handler</a> that sleeps +for a specified amount of time when a table is locked. The handler +will sleep multiple times until at least "ms" milliseconds of sleeping +have accumulated. After at least "ms" milliseconds of sleeping, +the handler returns 0 which causes <a href="#sqlite3_step">sqlite3_step()</a> to return +<a href="#SQLITE_ABORT">SQLITE_BUSY</a>.</p> + +<p>Calling this routine with an argument less than or equal to zero +turns off all busy handlers.</p> + +<p>There can only be a single busy handler for a particular +<a href="#sqlite3">database connection</a> at any given moment. If another busy handler +was defined (using <a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a>) prior to calling +this routine, that other busy handler is cleared.</p> + +<p>See also: <a href="pragma.html#pragma_busy_timeout">PRAGMA busy_timeout</a> +</p><hr><a name="sqlite3_cancel_auto_extension"></a> +<h2>Cancel Automatic Extension Loading</h2> +</div> +<blockquote><pre> +int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); +</pre></blockquote> +<p> +The <a href="#sqlite3_cancel_auto_extension">sqlite3_cancel_auto_extension(X)</a> interface unregisters the +initialization routine X that was registered using a prior call to +<a href="#sqlite3_auto_extension">sqlite3_auto_extension(X)</a>. The <a href="#sqlite3_cancel_auto_extension">sqlite3_cancel_auto_extension(X)</a> +routine returns 1 if initialization routine X was successfully +unregistered and it returns 0 if X was not on the list of initialization +routines. +</p><hr><a name="sqlite3_clear_bindings"></a> +<h2>Reset All Bindings On A Prepared Statement</h2> +</div> +<blockquote><pre> +int sqlite3_clear_bindings(sqlite3_stmt*); +</pre></blockquote> +<p> +Contrary to the intuition of many, <a href="#sqlite3_reset">sqlite3_reset()</a> does not reset +the <a href="#sqlite3_bind_blob">bindings</a> on a <a href="#sqlite3_stmt">prepared statement</a>. +Use this routine to reset all host parameters to NULL. +</p><hr><a name="sqlite3_column_count"></a> +<h2>Number Of Columns In A Result Set</h2> +</div> +<blockquote><pre> +int sqlite3_column_count(sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +Return the number of columns in the result set returned by the +<a href="#sqlite3_stmt">prepared statement</a>. If this routine returns 0, that means the +<a href="#sqlite3_stmt">prepared statement</a> returns no data (for example an <a href="lang_update.html">UPDATE</a>). +However, just because this routine returns a positive number does not +mean that one or more rows of data will be returned. A SELECT statement +will always have a positive sqlite3_column_count() but depending on the +WHERE clause constraints and the table content, it might return no rows.</p> + +<p>See also: <a href="#sqlite3_data_count">sqlite3_data_count()</a> +</p><hr><a name="sqlite3_config"></a> +<h2>Configuring The SQLite Library</h2> +</div> +<blockquote><pre> +int sqlite3_config(int, ...); +</pre></blockquote> +<p> +The sqlite3_config() interface is used to make global configuration +changes to SQLite in order to tune SQLite to the specific needs of +the application. The default configuration is recommended for most +applications and so this routine is usually not necessary. It is +provided to support rare applications with unusual needs.</p> + +<p><b>The sqlite3_config() interface is not threadsafe. The application +must ensure that no other SQLite interfaces are invoked by other +threads while sqlite3_config() is running.</b></p> + +<p>The first argument to sqlite3_config() is an integer +<a href="#SQLITE_CONFIG_COVERING_INDEX_SCAN">configuration option</a> that determines +what property of SQLite is to be configured. Subsequent arguments +vary depending on the <a href="#SQLITE_CONFIG_COVERING_INDEX_SCAN">configuration option</a> +in the first argument.</p> + +<p>For most configuration options, the sqlite3_config() interface +may only be invoked prior to library initialization using +<a href="#sqlite3_initialize">sqlite3_initialize()</a> or after shutdown by <a href="#sqlite3_initialize">sqlite3_shutdown()</a>. +The exceptional configuration options that may be invoked at any time +are called "anytime configuration options". +If sqlite3_config() is called after <a href="#sqlite3_initialize">sqlite3_initialize()</a> and before +<a href="#sqlite3_initialize">sqlite3_shutdown()</a> with a first argument that is not an anytime +configuration option, then the sqlite3_config() call will return SQLITE_MISUSE. +Note, however, that sqlite3_config() can be called as part of the +implementation of an application-defined <a href="#sqlite3_initialize">sqlite3_os_init()</a>.</p> + +<p>When a configuration option is set, sqlite3_config() returns <a href="#SQLITE_ABORT">SQLITE_OK</a>. +If the option is unknown or SQLite is unable to set the option +then this routine returns a non-zero <a href="rescode.html">error code</a>. +</p><hr><a name="sqlite3_context_db_handle"></a> +<h2>Database Connection For Functions</h2> +</div> +<blockquote><pre> +sqlite3 *sqlite3_context_db_handle(sqlite3_context*); +</pre></blockquote> +<p> +The sqlite3_context_db_handle() interface returns a copy of +the pointer to the <a href="#sqlite3">database connection</a> (the 1st parameter) +of the <a href="#sqlite3_create_function">sqlite3_create_function()</a> +and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> routines that originally +registered the application defined function. +</p><hr><a name="sqlite3_data_count"></a> +<h2>Number of columns in a result set</h2> +</div> +<blockquote><pre> +int sqlite3_data_count(sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +The sqlite3_data_count(P) interface returns the number of columns in the +current row of the result set of <a href="#sqlite3_stmt">prepared statement</a> P. +If prepared statement P does not have results ready to return +(via calls to the <a href="#sqlite3_column_blob">sqlite3_column()</a> family of +interfaces) then sqlite3_data_count(P) returns 0. +The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. +The sqlite3_data_count(P) routine returns 0 if the previous call to +<a href="#sqlite3_step">sqlite3_step</a>(P) returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>. The sqlite3_data_count(P) +will return non-zero if previous call to <a href="#sqlite3_step">sqlite3_step</a>(P) returned +<a href="#SQLITE_ABORT">SQLITE_ROW</a>, except in the case of the <a href="pragma.html#pragma_incremental_vacuum">PRAGMA incremental_vacuum</a> +where it always returns zero since each step of that multi-step +pragma returns 0 columns of data.</p> + +<p>See also: <a href="#sqlite3_column_count">sqlite3_column_count()</a> +</p><hr><a name="sqlite3_database_file_object"></a> +<h2>Database File Corresponding To A Journal</h2> +</div> +<blockquote><pre> +sqlite3_file *sqlite3_database_file_object(const char*); +</pre></blockquote> +<p> +If X is the name of a rollback or WAL-mode journal file that is +passed into the xOpen method of <a href="#sqlite3_vfs">sqlite3_vfs</a>, then +sqlite3_database_file_object(X) returns a pointer to the <a href="#sqlite3_file">sqlite3_file</a> +object that represents the main database file.</p> + +<p>This routine is intended for use in custom <a href="vfs.html">VFS</a> implementations +only. It is not a general-purpose interface. +The argument sqlite3_file_object(X) must be a filename pointer that +has been passed into <a href="#sqlite3_vfs">sqlite3_vfs</a>.xOpen method where the +flags parameter to xOpen contains one of the bits +<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_JOURNAL</a> or <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_WAL</a>. Any other use +of this routine results in undefined and probably undesirable +behavior. +</p><hr><a name="sqlite3_db_cacheflush"></a> +<h2>Flush caches to disk mid-transaction</h2> +</div> +<blockquote><pre> +int sqlite3_db_cacheflush(sqlite3*); +</pre></blockquote> +<p> +If a write-transaction is open on <a href="#sqlite3">database connection</a> D when the +<a href="#sqlite3_db_cacheflush">sqlite3_db_cacheflush(D)</a> interface invoked, any dirty +pages in the pager-cache that are not currently in use are written out +to disk. A dirty page may be in use if a database cursor created by an +active SQL statement is reading from it, or if it is page 1 of a database +file (page 1 is always "in use"). The <a href="#sqlite3_db_cacheflush">sqlite3_db_cacheflush(D)</a> +interface flushes caches for all schemas - "main", "temp", and +any <a href="lang_attach.html">attached</a> databases.</p> + +<p>If this function needs to obtain extra database locks before dirty pages +can be flushed to disk, it does so. If those locks cannot be obtained +immediately and there is a busy-handler callback configured, it is invoked +in the usual manner. If the required lock still cannot be obtained, then +the database is skipped and an attempt made to flush any dirty pages +belonging to the next (if any) database. If any databases are skipped +because locks cannot be obtained, but no other error occurs, this +function returns SQLITE_BUSY.</p> + +<p>If any other error occurs while flushing dirty pages to disk (for +example an IO error or out-of-memory condition), then processing is +abandoned and an SQLite <a href="rescode.html">error code</a> is returned to the caller immediately.</p> + +<p>Otherwise, if no error occurs, <a href="#sqlite3_db_cacheflush">sqlite3_db_cacheflush()</a> returns SQLITE_OK.</p> + +<p>This function does not set the database handle error code or message +returned by the <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> functions. +</p><hr><a name="sqlite3_db_config"></a> +<h2>Configure database connections</h2> +</div> +<blockquote><pre> +int sqlite3_db_config(sqlite3*, int op, ...); +</pre></blockquote> +<p> +The sqlite3_db_config() interface is used to make configuration +changes to a <a href="#sqlite3">database connection</a>. The interface is similar to +<a href="#sqlite3_config">sqlite3_config()</a> except that the changes apply to a single +<a href="#sqlite3">database connection</a> (specified in the first argument).</p> + +<p>The second argument to sqlite3_db_config(D,V,...) is the +<a href="#sqlitedbconfiglookaside">configuration verb</a> - an integer code +that indicates what aspect of the <a href="#sqlite3">database connection</a> is being configured. +Subsequent arguments vary depending on the configuration verb.</p> + +<p>Calls to sqlite3_db_config() return SQLITE_OK if and only if +the call is considered successful. +</p><hr><a name="sqlite3_db_filename"></a> +<h2>Return The Filename For A Database Connection</h2> +</div> +<blockquote><pre> +sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName); +</pre></blockquote> +<p> +The sqlite3_db_filename(D,N) interface returns a pointer to the filename +associated with database N of connection D. +If there is no attached database N on the database +connection D, or if database N is a temporary or in-memory database, then +this function will return either a NULL pointer or an empty string.</p> + +<p>The string value returned by this routine is owned and managed by +the database connection. The value will be valid until the database N +is <a href="lang_detach.html">DETACH</a>-ed or until the database connection closes.</p> + +<p>The filename returned by this function is the output of the +xFullPathname method of the <a href="vfs.html">VFS</a>. In other words, the filename +will be an absolute pathname, even if the filename used +to open the database originally was a URI or relative pathname.</p> + +<p>If the filename pointer returned by this routine is not NULL, then it +can be used as the filename input parameter to these routines: +<ul> +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_parameter()</a> +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_boolean()</a> +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_int64()</a> +<li> <a href="#sqlite3_filename_database">sqlite3_filename_database()</a> +<li> <a href="#sqlite3_filename_database">sqlite3_filename_journal()</a> +<li> <a href="#sqlite3_filename_database">sqlite3_filename_wal()</a> +</ul> +</p><hr><a name="sqlite3_db_handle"></a> +<h2>Find The Database Handle Of A Prepared Statement</h2> +</div> +<blockquote><pre> +sqlite3 *sqlite3_db_handle(sqlite3_stmt*); +</pre></blockquote> +<p> +The sqlite3_db_handle interface returns the <a href="#sqlite3">database connection</a> handle +to which a <a href="#sqlite3_stmt">prepared statement</a> belongs. The <a href="#sqlite3">database connection</a> +returned by sqlite3_db_handle is the same <a href="#sqlite3">database connection</a> +that was the first argument +to the <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> call (or its variants) that was used to +create the statement in the first place. +</p><hr><a name="sqlite3_db_mutex"></a> +<h2>Retrieve the mutex for a database connection</h2> +</div> +<blockquote><pre> +sqlite3_mutex *sqlite3_db_mutex(sqlite3*); +</pre></blockquote> +<p> +This interface returns a pointer the <a href="#sqlite3_mutex">sqlite3_mutex</a> object that +serializes access to the <a href="#sqlite3">database connection</a> given in the argument +when the <a href="threadsafe.html">threading mode</a> is Serialized. +If the <a href="threadsafe.html">threading mode</a> is Single-thread or Multi-thread then this +routine returns a NULL pointer. +</p><hr><a name="sqlite3_db_name"></a> +<h2>Return The Schema Name For A Database Connection</h2> +</div> +<blockquote><pre> +const char *sqlite3_db_name(sqlite3 *db, int N); +</pre></blockquote> +<p> +The sqlite3_db_name(D,N) interface returns a pointer to the schema name +for the N-th database on database connection D, or a NULL pointer of N is +out of range. An N value of 0 means the main database file. An N of 1 is +the "temp" schema. Larger values of N correspond to various ATTACH-ed +databases.</p> + +<p>Space to hold the string that is returned by sqlite3_db_name() is managed +by SQLite itself. The string might be deallocated by any operation that +changes the schema, including <a href="lang_attach.html">ATTACH</a> or <a href="lang_detach.html">DETACH</a> or calls to +<a href="#sqlite3_serialize">sqlite3_serialize()</a> or <a href="#sqlite3_deserialize">sqlite3_deserialize()</a>, even operations that +occur on a different thread. Applications that need to +remember the string long-term should make their own copy. Applications that +are accessing the same database connection simultaneously on multiple +threads should mutex-protect calls to this API and should make their own +private copy of the result prior to releasing the mutex. +</p><hr><a name="sqlite3_db_readonly"></a> +<h2>Determine if a database is read-only</h2> +</div> +<blockquote><pre> +int sqlite3_db_readonly(sqlite3 *db, const char *zDbName); +</pre></blockquote> +<p> +The sqlite3_db_readonly(D,N) interface returns 1 if the database N +of connection D is read-only, 0 if it is read/write, or -1 if N is not +the name of a database on connection D. +</p><hr><a name="sqlite3_db_release_memory"></a> +<h2>Free Memory Used By A Database Connection</h2> +</div> +<blockquote><pre> +int sqlite3_db_release_memory(sqlite3*); +</pre></blockquote> +<p> +The sqlite3_db_release_memory(D) interface attempts to free as much heap +memory as possible from database connection D. Unlike the +<a href="#sqlite3_release_memory">sqlite3_release_memory()</a> interface, this interface is in effect even +when the <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a> compile-time option is +omitted.</p> + +<p>See also: <a href="#sqlite3_release_memory">sqlite3_release_memory()</a> +</p><hr><a name="sqlite3_db_status"></a> +<h2>Database Connection Status</h2> +</div> +<blockquote><pre> +int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); +</pre></blockquote> +<p> +This interface is used to retrieve runtime status information +about a single <a href="#sqlite3">database connection</a>. The first argument is the +database connection object to be interrogated. The second argument +is an integer constant, taken from the set of +<a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS options</a>, that +determines the parameter to interrogate. The set of +<a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS options</a> is likely +to grow in future releases of SQLite.</p> + +<p>The current value of the requested parameter is written into *pCur +and the highest instantaneous value is written into *pHiwtr. If +the resetFlg is true, then the highest instantaneous value is +reset back down to the current value.</p> + +<p>The sqlite3_db_status() routine returns SQLITE_OK on success and a +non-zero <a href="rescode.html">error code</a> on failure.</p> + +<p>See also: <a href="#sqlite3_status">sqlite3_status()</a> and <a href="#sqlite3_stmt_status">sqlite3_stmt_status()</a>. +</p><hr><a name="sqlite3_declare_vtab"></a> +<h2>Declare The Schema Of A Virtual Table</h2> +</div> +<blockquote><pre> +int sqlite3_declare_vtab(sqlite3*, const char *zSQL); +</pre></blockquote> +<p> +The <a href="vtab.html#xcreate">xCreate</a> and <a href="vtab.html#xconnect">xConnect</a> methods of a +<a href="#sqlite3_module">virtual table module</a> call this interface +to declare the format (the names and datatypes of the columns) of +the virtual tables they implement. +</p><hr><a name="sqlite3_deserialize"></a> +<h2>Deserialize a database</h2> +</div> +<blockquote><pre> +int sqlite3_deserialize( + sqlite3 *db, /* The database connection */ + const char *zSchema, /* Which DB to reopen with the deserialization */ + unsigned char *pData, /* The serialized database content */ + sqlite3_int64 szDb, /* Number bytes in the deserialization */ + sqlite3_int64 szBuf, /* Total size of buffer pData[] */ + unsigned mFlags /* Zero or more SQLITE_DESERIALIZE_* flags */ +); +</pre></blockquote> +<p> +The sqlite3_deserialize(D,S,P,N,M,F) interface causes the +<a href="#sqlite3">database connection</a> D to disconnect from database S and then +reopen S as an in-memory database based on the serialization contained +in P. The serialized database P is N bytes in size. M is the size of +the buffer P, which might be larger than N. If M is larger than N, and +the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is +permitted to add content to the in-memory database as long as the total +size does not exceed M bytes.</p> + +<p>If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will +invoke sqlite3_free() on the serialization buffer when the database +connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then +SQLite will try to increase the buffer size using sqlite3_realloc64() +if writes on the database cause it to grow larger than M bytes.</p> + +<p>Applications must not modify the buffer P or invalidate it before +the database connection D is closed.</p> + +<p>The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the +database is currently in a read transaction or is involved in a backup +operation.</p> + +<p>It is not possible to deserialized into the TEMP database. If the +S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the +function returns SQLITE_ERROR.</p> + +<p>The deserialized database should not be in <a href="wal.html">WAL mode</a>. If the database +is in WAL mode, then any attempt to use the database file will result +in an <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a> error. The application can set the +<a href="fileformat2.html#vnums">file format version numbers</a> (bytes 18 and 19) of the input database P +to 0x01 prior to invoking sqlite3_deserialize(D,S,P,N,M,F) to force the +database file into rollback mode and work around this limitation.</p> + +<p>If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the +SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then +<a href="#sqlite3_free">sqlite3_free()</a> is invoked on argument P prior to returning.</p> + +<p>This interface is omitted if SQLite is compiled with the +<a href="compile.html#omit_deserialize">SQLITE_OMIT_DESERIALIZE</a> option. +</p><hr><a name="sqlite3_drop_modules"></a> +<h2>Remove Unnecessary Virtual Table Implementations</h2> +</div> +<blockquote><pre> +int sqlite3_drop_modules( + sqlite3 *db, /* Remove modules from this connection */ + const char **azKeep /* Except, do not remove the ones named here */ +); +</pre></blockquote> +<p> +The sqlite3_drop_modules(D,L) interface removes all virtual +table modules from database connection D except those named on list L. +The L parameter must be either NULL or a pointer to an array of pointers +to strings where the array is terminated by a single NULL pointer. +If the L parameter is NULL, then all virtual table modules are removed.</p> + +<p>See also: <a href="#sqlite3_create_module">sqlite3_create_module()</a> +</p><hr><a name="sqlite3_enable_load_extension"></a> +<h2>Enable Or Disable Extension Loading</h2> +</div> +<blockquote><pre> +int sqlite3_enable_load_extension(sqlite3 *db, int onoff); +</pre></blockquote> +<p> +So as not to open security holes in older applications that are +unprepared to deal with <a href="loadext.html">extension loading</a>, and as a means of disabling +<a href="loadext.html">extension loading</a> while evaluating user-entered SQL, the following API +is provided to turn the <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> mechanism on and off.</p> + +<p>Extension loading is off by default. +Call the sqlite3_enable_load_extension() routine with onoff==1 +to turn extension loading on and call it with onoff==0 to turn +it back off again.</p> + +<p>This interface enables or disables both the C-API +<a href="#sqlite3_load_extension">sqlite3_load_extension()</a> and the SQL function <a href="lang_corefunc.html#load_extension">load_extension()</a>. +Use <a href="#sqlite3_db_config">sqlite3_db_config</a>(db,<a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a>,..) +to enable or disable only the C-API.</p> + +<p><b>Security warning:</b> It is recommended that extension loading +be enabled using the <a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a> method +rather than this interface, so the <a href="lang_corefunc.html#load_extension">load_extension()</a> SQL function +remains disabled. This will prevent SQL injections from giving attackers +access to extension loading capabilities. +</p><hr><a name="sqlite3_enable_shared_cache"></a> +<h2>Enable Or Disable Shared Pager Cache</h2> +</div> +<blockquote><pre> +int sqlite3_enable_shared_cache(int); +</pre></blockquote> +<p> +This routine enables or disables the sharing of the database cache +and schema data structures between <a href="#sqlite3">connections</a> +to the same database. Sharing is enabled if the argument is true +and disabled if the argument is false.</p> + +<p>This interface is omitted if SQLite is compiled with +<a href="compile.html#omit_shared_cache">-DSQLITE_OMIT_SHARED_CACHE</a>. The <a href="compile.html#omit_shared_cache">-DSQLITE_OMIT_SHARED_CACHE</a> +compile-time option is recommended because the +<a href="sharedcache.html#dontuse">use of shared cache mode is discouraged</a>.</p> + +<p>Cache sharing is enabled and disabled for an entire process. +This is a change as of SQLite <a href="releaselog/3_5_0.html">version 3.5.0</a> (2007-09-04). +In prior versions of SQLite, +sharing was enabled or disabled for each thread separately.</p> + +<p>The cache sharing mode set by this interface effects all subsequent +calls to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a>, and <a href="#sqlite3_open">sqlite3_open16()</a>. +Existing database connections continue to use the sharing mode +that was in effect at the time they were opened.</p> + +<p>This routine returns <a href="#SQLITE_ABORT">SQLITE_OK</a> if shared cache was enabled or disabled +successfully. An <a href="rescode.html">error code</a> is returned otherwise.</p> + +<p>Shared cache is disabled by default. It is recommended that it stay +that way. In other words, do not use this routine. This interface +continues to be provided for historical compatibility, but its use is +discouraged. Any use of shared cache is discouraged. If shared cache +must be used, it is recommended that shared cache only be enabled for +individual database connections using the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface +with the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a> flag.</p> + +<p>Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 +and will always return SQLITE_MISUSE. On those systems, +shared cache mode should be enabled per-database connection via +<a href="#sqlite3_open">sqlite3_open_v2()</a> with <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a>.</p> + +<p>This interface is threadsafe on processors where writing a +32-bit integer is atomic.</p> + +<p>See Also: <a href="sharedcache.html">SQLite Shared-Cache Mode</a> +</p><hr><a name="sqlite3_exec"></a> +<h2>One-Step Query Execution Interface</h2> +</div> +<blockquote><pre> +int sqlite3_exec( + sqlite3*, /* An open database */ + const char *sql, /* SQL to be evaluated */ + int (*callback)(void*,int,char**,char**), /* Callback function */ + void *, /* 1st argument to callback */ + char **errmsg /* Error msg written here */ +); +</pre></blockquote> +<p> +The sqlite3_exec() interface is a convenience wrapper around +<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_step">sqlite3_step()</a>, and <a href="#sqlite3_finalize">sqlite3_finalize()</a>, +that allows an application to run multiple statements of SQL +without having to use a lot of C code.</p> + +<p>The sqlite3_exec() interface runs zero or more UTF-8 encoded, +semicolon-separate SQL statements passed into its 2nd argument, +in the context of the <a href="#sqlite3">database connection</a> passed in as its 1st +argument. If the callback function of the 3rd argument to +sqlite3_exec() is not NULL, then it is invoked for each result row +coming out of the evaluated SQL statements. The 4th argument to +sqlite3_exec() is relayed through to the 1st argument of each +callback invocation. If the callback pointer to sqlite3_exec() +is NULL, then no callback is ever invoked and result rows are +ignored.</p> + +<p>If an error occurs while evaluating the SQL statements passed into +sqlite3_exec(), then execution of the current statement stops and +subsequent statements are skipped. If the 5th parameter to sqlite3_exec() +is not NULL then any error message is written into memory obtained +from <a href="#sqlite3_free">sqlite3_malloc()</a> and passed back through the 5th parameter. +To avoid memory leaks, the application should invoke <a href="#sqlite3_free">sqlite3_free()</a> +on error message strings returned through the 5th parameter of +sqlite3_exec() after the error message string is no longer needed. +If the 5th parameter to sqlite3_exec() is not NULL and no errors +occur, then sqlite3_exec() sets the pointer in its 5th parameter to +NULL before returning.</p> + +<p>If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() +routine returns SQLITE_ABORT without invoking the callback again and +without running any subsequent SQL statements.</p> + +<p>The 2nd argument to the sqlite3_exec() callback function is the +number of columns in the result. The 3rd argument to the sqlite3_exec() +callback is an array of pointers to strings obtained as if from +<a href="#sqlite3_column_blob">sqlite3_column_text()</a>, one for each column. If an element of a +result row is NULL then the corresponding string pointer for the +sqlite3_exec() callback is a NULL pointer. The 4th argument to the +sqlite3_exec() callback is an array of pointers to strings where each +entry represents the name of corresponding result column as obtained +from <a href="#sqlite3_column_name">sqlite3_column_name()</a>.</p> + +<p>If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer +to an empty string, or a pointer that contains only whitespace and/or +SQL comments, then no SQL statements are evaluated and the database +is not changed.</p> + +<p>Restrictions:</p> + +<p><ul> +<li> The application must ensure that the 1st parameter to sqlite3_exec() +is a valid and open <a href="#sqlite3">database connection</a>. +<li> The application must not close the <a href="#sqlite3">database connection</a> specified by +the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. +<li> The application must not modify the SQL statement text passed into +the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. +</ul> +</p><hr><a name="sqlite3_extended_result_codes"></a> +<h2>Enable Or Disable Extended Result Codes</h2> +</div> +<blockquote><pre> +int sqlite3_extended_result_codes(sqlite3*, int onoff); +</pre></blockquote> +<p> +The sqlite3_extended_result_codes() routine enables or disables the +<a href="rescode.html#extrc">extended result codes</a> feature of SQLite. The extended result +codes are disabled by default for historical compatibility. +</p><hr><a name="sqlite3_finalize"></a> +<h2>Destroy A Prepared Statement Object</h2> +</div> +<blockquote><pre> +int sqlite3_finalize(sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +The sqlite3_finalize() function is called to delete a <a href="#sqlite3_stmt">prepared statement</a>. +If the most recent evaluation of the statement encountered no errors +or if the statement is never been evaluated, then sqlite3_finalize() returns +SQLITE_OK. If the most recent evaluation of statement S failed, then +sqlite3_finalize(S) returns the appropriate <a href="rescode.html">error code</a> or +<a href="rescode.html#extrc">extended error code</a>.</p> + +<p>The sqlite3_finalize(S) routine can be called at any point during +the life cycle of <a href="#sqlite3_stmt">prepared statement</a> S: +before statement S is ever evaluated, after +one or more calls to <a href="#sqlite3_reset">sqlite3_reset()</a>, or after any call +to <a href="#sqlite3_step">sqlite3_step()</a> regardless of whether or not the statement has +completed execution.</p> + +<p>Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.</p> + +<p>The application must finalize every <a href="#sqlite3_stmt">prepared statement</a> in order to avoid +resource leaks. It is a grievous error for the application to try to use +a prepared statement after it has been finalized. Any use of a prepared +statement after it has been finalized can result in undefined and +undesirable behavior such as segfaults and heap corruption. +</p><hr><a name="sqlite3_last_insert_rowid"></a> +<h2>Last Insert Rowid</h2> +</div> +<blockquote><pre> +sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); +</pre></blockquote> +<p> +Each entry in most SQLite tables (except for <a href="withoutrowid.html">WITHOUT ROWID</a> tables) +has a unique 64-bit signed +integer key called the <a href="lang_createtable.html#rowid">"rowid"</a>. 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 <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> then that column +is another alias for the rowid.</p> + +<p>The sqlite3_last_insert_rowid(D) interface usually returns the <a href="lang_createtable.html#rowid">rowid</a> of +the most recent successful <a href="lang_insert.html">INSERT</a> into a rowid table or <a href="vtab.html">virtual table</a> +on database connection D. Inserts into <a href="withoutrowid.html">WITHOUT ROWID</a> tables are not +recorded. If no successful <a href="lang_insert.html">INSERT</a>s into rowid tables have ever occurred +on the database connection D, then sqlite3_last_insert_rowid(D) returns +zero.</p> + +<p>As well as being set automatically as rows are inserted into database +tables, the value returned by this function may be set explicitly by +<a href="#sqlite3_set_last_insert_rowid">sqlite3_set_last_insert_rowid()</a></p> + +<p>Some virtual table implementations may INSERT rows into rowid tables as +part of committing a transaction (e.g. to flush data accumulated in memory +to disk). In this case subsequent calls to this function return the rowid +associated with these internal INSERT operations, which leads to +unintuitive results. Virtual table implementations that do write to rowid +tables in this way can avoid this problem by restoring the original +rowid value using <a href="#sqlite3_set_last_insert_rowid">sqlite3_set_last_insert_rowid()</a> before returning +control to the user.</p> + +<p>If an <a href="lang_insert.html">INSERT</a> occurs within a trigger then this routine will +return the <a href="lang_createtable.html#rowid">rowid</a> of the inserted row as long as the trigger is +running. Once the trigger program ends, the value returned +by this routine reverts to what it was before the trigger was fired.</p> + +<p>An <a href="lang_insert.html">INSERT</a> that fails due to a constraint violation is not a +successful <a href="lang_insert.html">INSERT</a> and does not change the value returned by this +routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, +and INSERT OR ABORT make no changes to the return value of this +routine when their insertion fails. When INSERT OR REPLACE +encounters a constraint violation, it does not fail. The +INSERT continues to completion after deleting rows that caused +the constraint problem so INSERT OR REPLACE will always change +the return value of this interface.</p> + +<p>For the purposes of this routine, an <a href="lang_insert.html">INSERT</a> is considered to +be successful even if it is subsequently rolled back.</p> + +<p>This function is accessible to SQL statements via the +<a href="lang_corefunc.html#last_insert_rowid">last_insert_rowid() SQL function</a>.</p> + +<p>If a separate thread performs a new <a href="lang_insert.html">INSERT</a> on the same +database connection while the <a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid()</a> +function is running and thus changes the last insert <a href="lang_createtable.html#rowid">rowid</a>, +then the value returned by <a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid()</a> is +unpredictable and might not equal either the old or the new +last insert <a href="lang_createtable.html#rowid">rowid</a>. +</p><hr><a name="sqlite3_limit"></a> +<h2>Run-time Limits</h2> +</div> +<blockquote><pre> +int sqlite3_limit(sqlite3*, int id, int newVal); +</pre></blockquote> +<p> +This interface allows the size of various constructs to be limited +on a connection by connection basis. The first parameter is the +<a href="#sqlite3">database connection</a> whose limit is to be set or queried. The +second parameter is one of the <a href="#SQLITE_LIMIT_ATTACHED">limit categories</a> that define a +class of constructs to be size limited. The third parameter is the +new limit for that construct.</p> + +<p>If the new limit is a negative number, the limit is unchanged. +For each limit category SQLITE_LIMIT_<i>NAME</i> there is a +<a href="limits.html">hard upper bound</a> +set at compile-time by a C preprocessor macro called +<a href="limits.html">SQLITE_MAX_<i>NAME</i></a>. +(The "_LIMIT_" in the name is changed to "_MAX_".) +Attempts to increase a limit above its hard upper bound are +silently truncated to the hard upper bound.</p> + +<p>Regardless of whether or not the limit was changed, the +<a href="#sqlite3_limit">sqlite3_limit()</a> interface returns the prior value of the limit. +Hence, to find the current value of a limit without changing it, +simply invoke this interface with the third parameter set to -1.</p> + +<p>Run-time limits are intended for use in applications that manage +both their own internal database and also databases that are controlled +by untrusted external sources. An example application might be a +web browser that has its own databases for storing history and +separate databases controlled by JavaScript applications downloaded +off the Internet. The internal databases can be given the +large, default limits. Databases managed by external sources can +be given much smaller limits designed to prevent a denial of service +attack. Developers might also want to use the <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> +interface to further control untrusted SQL. The size of the database +created by an untrusted script can be contained using the +<a href="pragma.html#pragma_max_page_count">max_page_count</a> <a href="pragma.html#syntax">PRAGMA</a>.</p> + +<p>New run-time limit categories may be added in future releases. +</p><hr><a name="sqlite3_load_extension"></a> +<h2>Load An Extension</h2> +</div> +<blockquote><pre> +int sqlite3_load_extension( + sqlite3 *db, /* Load the extension into this database connection */ + const char *zFile, /* Name of the shared library containing extension */ + const char *zProc, /* Entry point. Derived from zFile if 0 */ + char **pzErrMsg /* Put error message here if not 0 */ +); +</pre></blockquote> +<p> +This interface loads an SQLite extension library from the named file.</p> + +<p>The sqlite3_load_extension() interface attempts to load an +<a href="loadext.html">SQLite extension</a> library contained in the file zFile. If +the file cannot be loaded directly, attempts are made to load +with various operating-system specific extensions added. +So for example, if "samplelib" cannot be loaded, then names like +"samplelib.so" or "samplelib.dylib" or "samplelib.dll" might +be tried also.</p> + +<p>The entry point is zProc. +zProc may be 0, in which case SQLite will try to come up with an +entry point name on its own. It first tries "sqlite3_extension_init". +If that does not work, it constructs a name "sqlite3_X_init" where the +X is consists of the lower-case equivalent of all ASCII alphabetic +characters in the filename from the last "/" to the first following +"." and omitting any initial "lib". +The sqlite3_load_extension() interface returns +<a href="#SQLITE_ABORT">SQLITE_OK</a> on success and <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if something goes wrong. +If an error occurs and pzErrMsg is not 0, then the +<a href="#sqlite3_load_extension">sqlite3_load_extension()</a> interface shall attempt to +fill *pzErrMsg with error message text stored in memory +obtained from <a href="#sqlite3_free">sqlite3_malloc()</a>. The calling function +should free this memory by calling <a href="#sqlite3_free">sqlite3_free()</a>.</p> + +<p>Extension loading must be enabled using +<a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> or +<a href="#sqlite3_db_config">sqlite3_db_config</a>(db,<a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a>,1,NULL) +prior to calling this API, +otherwise an error will be returned.</p> + +<p><b>Security warning:</b> It is recommended that the +<a href="#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a> method be used to enable only this +interface. The use of the <a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> interface +should be avoided. This will keep the SQL function <a href="lang_corefunc.html#load_extension">load_extension()</a> +disabled and prevent SQL injections from giving attackers +access to extension loading capabilities.</p> + +<p>See also the <a href="lang_corefunc.html#load_extension">load_extension() SQL function</a>. +</p><hr><a name="sqlite3_log"></a> +<h2>Error Logging Interface</h2> +</div> +<blockquote><pre> +void sqlite3_log(int iErrCode, const char *zFormat, ...); +</pre></blockquote> +<p> +The <a href="#sqlite3_log">sqlite3_log()</a> interface writes a message into the <a href="errlog.html">error log</a> +established by the <a href="#sqliteconfiglog">SQLITE_CONFIG_LOG</a> option to <a href="#sqlite3_config">sqlite3_config()</a>. +If logging is enabled, the zFormat string and subsequent arguments are +used with <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to generate the final output string.</p> + +<p>The sqlite3_log() interface is intended for use by extensions such as +virtual tables, collating functions, and SQL functions. While there is +nothing to prevent an application from calling sqlite3_log(), doing so +is considered bad form.</p> + +<p>The zFormat string must not be NULL.</p> + +<p>To avoid deadlocks and other threading problems, the sqlite3_log() routine +will not use dynamically allocated memory. The log message is stored in +a fixed-length buffer on the stack. If the log message is longer than +a few hundred characters, it will be truncated to the length of the +buffer. +</p><hr><a name="sqlite3_next_stmt"></a> +<h2>Find the next prepared statement</h2> +</div> +<blockquote><pre> +sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +This interface returns a pointer to the next <a href="#sqlite3_stmt">prepared statement</a> after +pStmt associated with the <a href="#sqlite3">database connection</a> pDb. If pStmt is NULL +then this interface returns a pointer to the first prepared statement +associated with the database connection pDb. If no prepared statement +satisfies the conditions of this routine, it returns NULL.</p> + +<p>The <a href="#sqlite3">database connection</a> pointer D in a call to +<a href="#sqlite3_next_stmt">sqlite3_next_stmt(D,S)</a> must refer to an open database +connection and in particular must not be a NULL pointer. +</p><hr><a name="sqlite3_overload_function"></a> +<h2>Overload A Function For A Virtual Table</h2> +</div> +<blockquote><pre> +int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); +</pre></blockquote> +<p> +Virtual tables can provide alternative implementations of functions +using the <a href="vtab.html#xfindfunction">xFindFunction</a> method of the <a href="#sqlite3_module">virtual table module</a>. +But global versions of those functions +must exist in order to be overloaded.</p> + +<p>This API makes sure a global version of a function with a particular +name and number of parameters exists. If no such function exists +before this API is called, a new function is created. The implementation +of the new function always causes an exception to be thrown. So +the new function is not good for anything by itself. Its only +purpose is to be a placeholder function that can be overloaded +by a <a href="vtab.html">virtual table</a>. +</p><hr><a name="sqlite3_progress_handler"></a> +<h2>Query Progress Callbacks</h2> +</div> +<blockquote><pre> +void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); +</pre></blockquote> +<p> +The sqlite3_progress_handler(D,N,X,P) interface causes the callback +function X to be invoked periodically during long running calls to +<a href="#sqlite3_step">sqlite3_step()</a> and <a href="#sqlite3_prepare">sqlite3_prepare()</a> and similar for +database connection D. An example use for this +interface is to keep a GUI updated during a large query.</p> + +<p>The parameter P is passed through as the only parameter to the +callback function X. The parameter N is the approximate number of +<a href="opcode.html">virtual machine instructions</a> that are evaluated between successive +invocations of the callback X. If N is less than one then the progress +handler is disabled.</p> + +<p>Only a single progress handler may be defined at one time per +<a href="#sqlite3">database connection</a>; setting a new progress handler cancels the +old one. Setting parameter X to NULL disables the progress handler. +The progress handler is also disabled by setting N to a value less +than 1.</p> + +<p>If the progress callback returns non-zero, the operation is +interrupted. This feature can be used to implement a +"Cancel" button on a GUI progress dialog box.</p> + +<p>The progress handler callback must not do anything that will modify +the database connection that invoked the progress handler. +Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their +database connections for the meaning of "modify" in this paragraph.</p> + +<p>The progress handler callback would originally only be invoked from the +bytecode engine. It still might be invoked during <a href="#sqlite3_prepare">sqlite3_prepare()</a> +and similar because those routines might force a reparse of the schema +which involves running the bytecode engine. However, beginning with +SQLite version 3.41.0, the progress handler callback might also be +invoked directly from <a href="#sqlite3_prepare">sqlite3_prepare()</a> while analyzing and generating +code for complex queries. +</p><hr><a name="sqlite3_randomness"></a> +<h2>Pseudo-Random Number Generator</h2> +</div> +<blockquote><pre> +void sqlite3_randomness(int N, void *P); +</pre></blockquote> +<p> +SQLite contains a high-quality pseudo-random number generator (PRNG) used to +select random <a href="lang_createtable.html#rowid">ROWIDs</a> when inserting new records into a table that +already uses the largest possible <a href="lang_createtable.html#rowid">ROWID</a>. The PRNG is also used for +the built-in random() and randomblob() SQL functions. This interface allows +applications to access the same PRNG for other purposes.</p> + +<p>A call to this routine stores N bytes of randomness into buffer P. +The P parameter can be a NULL pointer.</p> + +<p>If this routine has not been previously called or if the previous +call had N less than one or a NULL pointer for P, then the PRNG is +seeded using randomness obtained from the xRandomness method of +the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object. +If the previous call to this routine had an N of 1 or more and a +non-NULL P then the pseudo-randomness is generated +internally and without recourse to the <a href="#sqlite3_vfs">sqlite3_vfs</a> xRandomness +method. +</p><hr><a name="sqlite3_release_memory"></a> +<h2>Attempt To Free Heap Memory</h2> +</div> +<blockquote><pre> +int sqlite3_release_memory(int); +</pre></blockquote> +<p> +The sqlite3_release_memory() interface attempts to free N bytes +of heap memory by deallocating non-essential memory allocations +held by the database library. 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() routine is a no-op returning zero +if SQLite is not compiled with <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>.</p> + +<p>See also: <a href="#sqlite3_db_release_memory">sqlite3_db_release_memory()</a> +</p><hr><a name="sqlite3_reset"></a> +<h2>Reset A Prepared Statement Object</h2> +</div> +<blockquote><pre> +int sqlite3_reset(sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +The sqlite3_reset() function is called to reset a <a href="#sqlite3_stmt">prepared statement</a> +object back to its initial state, ready to be re-executed. +Any SQL statement variables that had values bound to them using +the <a href="#sqlite3_bind_blob">sqlite3_bind_*() API</a> retain their values. +Use <a href="#sqlite3_clear_bindings">sqlite3_clear_bindings()</a> to reset the bindings.</p> + +<p>The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface resets the <a href="#sqlite3_stmt">prepared statement</a> S +back to the beginning of its program.</p> + +<p>The return code from <a href="#sqlite3_reset">sqlite3_reset(S)</a> indicates whether or not +the previous evaluation of prepared statement S completed successfully. +If <a href="#sqlite3_step">sqlite3_step(S)</a> has never before been called on S or if +<a href="#sqlite3_step">sqlite3_step(S)</a> has not been called since the previous call +to <a href="#sqlite3_reset">sqlite3_reset(S)</a>, then <a href="#sqlite3_reset">sqlite3_reset(S)</a> will return +<a href="#SQLITE_ABORT">SQLITE_OK</a>.</p> + +<p>If the most recent call to <a href="#sqlite3_step">sqlite3_step(S)</a> for the +<a href="#sqlite3_stmt">prepared statement</a> S indicated an error, then +<a href="#sqlite3_reset">sqlite3_reset(S)</a> returns an appropriate <a href="rescode.html">error code</a>. +The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface might also return an <a href="rescode.html">error code</a> +if there were no prior errors but the process of resetting +the prepared statement caused a new error. For example, if an +<a href="lang_insert.html">INSERT</a> statement with a <a href="lang_returning.html">RETURNING</a> clause is only stepped one time, +that one call to <a href="#sqlite3_step">sqlite3_step(S)</a> might return SQLITE_ROW but +the overall statement might still fail and the <a href="#sqlite3_reset">sqlite3_reset(S)</a> call +might return SQLITE_BUSY if locking constraints prevent the +database change from committing. Therefore, it is important that +applications check the return code from <a href="#sqlite3_reset">sqlite3_reset(S)</a> even if +no prior call to <a href="#sqlite3_step">sqlite3_step(S)</a> indicated a problem.</p> + +<p>The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface does not change the values +of any <a href="#sqlite3_bind_blob">bindings</a> on the <a href="#sqlite3_stmt">prepared statement</a> S. +</p><hr><a name="sqlite3_reset_auto_extension"></a> +<h2>Reset Automatic Extension Loading</h2> +</div> +<blockquote><pre> +void sqlite3_reset_auto_extension(void); +</pre></blockquote> +<p> +This interface disables all automatic extensions previously +registered using <a href="#sqlite3_auto_extension">sqlite3_auto_extension()</a>. +</p><hr><a name="sqlite3_result_subtype"></a> +<h2>Setting The Subtype Of An SQL Function</h2> +</div> +<blockquote><pre> +void sqlite3_result_subtype(sqlite3_context*,unsigned int); +</pre></blockquote> +<p> +The sqlite3_result_subtype(C,T) function causes the subtype of +the result from the <a href="appfunc.html">application-defined SQL function</a> with +<a href="#sqlite3_context">sqlite3_context</a> C to be the value T. Only the lower 8 bits +of the subtype T are preserved in current versions of SQLite; +higher order bits are discarded. +The number of subtype bytes preserved by SQLite might increase +in future releases of SQLite.</p> + +<p>Every <a href="appfunc.html">application-defined SQL function</a> that invokes this interface +should include the <a href="#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> property in its +text encoding argument when the SQL function is +<a href="#sqlite3_create_function">registered</a>. If the <a href="#sqliteresultsubtype">SQLITE_RESULT_SUBTYPE</a> +property is omitted from the function that invokes sqlite3_result_subtype(), +then in some cases the sqlite3_result_subtype() might fail to set +the result subtype.</p> + +<p>If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any +SQL function that invokes the sqlite3_result_subtype() interface +and that does not have the SQLITE_RESULT_SUBTYPE property will raise +an error. Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=1 +by default. +</p><hr><a name="sqlite3_serialize"></a> +<h2>Serialize a database</h2> +</div> +<blockquote><pre> +unsigned char *sqlite3_serialize( + sqlite3 *db, /* The database connection */ + const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */ + sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */ + unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */ +); +</pre></blockquote> +<p> +The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory +that is a serialization of the S database on <a href="#sqlite3">database connection</a> D. +If P is not a NULL pointer, then the size of the database in bytes +is written into *P.</p> + +<p>For an ordinary on-disk database file, the serialization is just a +copy of the disk file. For an in-memory database or a "TEMP" database, +the serialization is the same sequence of bytes which would be written +to disk if that database where backed up to disk.</p> + +<p>The usual case is that sqlite3_serialize() copies the serialization of +the database into memory obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a> and returns +a pointer to that memory. The caller is responsible for freeing the +returned value to avoid a memory leak. However, if the F argument +contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations +are made, and the sqlite3_serialize() function will return a pointer +to the contiguous memory representation of the database that SQLite +is currently using for that database, or NULL if the no such contiguous +memory representation of the database exists. A contiguous memory +representation of the database will usually only exist if there has +been a prior call to <a href="#sqlite3_deserialize">sqlite3_deserialize(D,S,...)</a> with the same +values of D and S. +The size of the database is written into *P even if the +SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy +of the database exists.</p> + +<p>After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set, +the returned buffer content will remain accessible and unchanged +until either the next write operation on the connection or when +the connection is closed, and applications must not modify the +buffer. If the bit had been clear, the returned buffer will not +be accessed by SQLite after the call.</p> + +<p>A call to sqlite3_serialize(D,S,P,F) might return NULL even if the +SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory +allocation error occurs.</p> + +<p>This interface is omitted if SQLite is compiled with the +<a href="compile.html#omit_deserialize">SQLITE_OMIT_DESERIALIZE</a> option. +</p><hr><a name="sqlite3_set_last_insert_rowid"></a> +<h2>Set the Last Insert Rowid value.</h2> +</div> +<blockquote><pre> +void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64); +</pre></blockquote> +<p> +The sqlite3_set_last_insert_rowid(D, R) method allows the application to +set the value returned by calling sqlite3_last_insert_rowid(D) to R +without inserting a row into the database. +</p><hr><a name="sqlite3_sleep"></a> +<h2>Suspend Execution For A Short Time</h2> +</div> +<blockquote><pre> +int sqlite3_sleep(int); +</pre></blockquote> +<p> +The sqlite3_sleep() function causes the current thread to suspend execution +for at least a number of milliseconds specified in its parameter.</p> + +<p>If the operating system does not support sleep requests with +millisecond time resolution, then the time will be rounded up to +the nearest second. The number of milliseconds of sleep actually +requested from the operating system is returned.</p> + +<p>SQLite implements this interface by calling the xSleep() +method of the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object. If the xSleep() method +of the default VFS is not implemented correctly, or not implemented at +all, then the behavior of sqlite3_sleep() may deviate from the description +in the previous paragraphs.</p> + +<p>If a negative argument is passed to sqlite3_sleep() the results vary by +VFS and operating system. Some system treat a negative argument as an +instruction to sleep forever. Others understand it to mean do not sleep +at all. In SQLite version 3.42.0 and later, a negative +argument passed into sqlite3_sleep() is changed to zero before it is relayed +down into the xSleep method of the VFS. +</p><hr><a name="sqlite3_snapshot_cmp"></a> +<h2>Compare the ages of two snapshot handles.</h2> +</div> +<blockquote><pre> +int sqlite3_snapshot_cmp( + sqlite3_snapshot *p1, + sqlite3_snapshot *p2 +); +</pre></blockquote> +<p> +The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages +of two valid snapshot handles.</p> + +<p>If the two snapshot handles are not associated with the same database +file, the result of the comparison is undefined.</p> + +<p>Additionally, the result of the comparison is only valid if both of the +snapshot handles were obtained by calling sqlite3_snapshot_get() since the +last time the wal file was deleted. The wal file is deleted when the +database is changed back to rollback mode or when the number of database +clients drops to zero. If either snapshot handle was obtained before the +wal file was last deleted, the value returned by this function +is undefined.</p> + +<p>Otherwise, this API returns a negative value if P1 refers to an older +snapshot than P2, zero if the two handles refer to the same database +snapshot, and a positive value if P1 is a newer snapshot than P2.</p> + +<p>This interface is only available if SQLite is compiled with the +<a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> option. +</p><hr><a name="sqlite3_snapshot_free"></a> +<h2>Destroy a snapshot</h2> +</div> +<blockquote><pre> +void sqlite3_snapshot_free(sqlite3_snapshot*); +</pre></blockquote> +<p> +The <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free(P)</a> interface destroys <a href="#sqlite3_snapshot">sqlite3_snapshot</a> P. +The application must eventually free every <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object +using this routine to avoid a memory leak.</p> + +<p>The <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free()</a> interface is only available when the +<a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> compile-time option is used. +</p><hr><a name="sqlite3_snapshot_get"></a> +<h2>Record A Database Snapshot</h2> +</div> +<blockquote><pre> +int sqlite3_snapshot_get( + sqlite3 *db, + const char *zSchema, + sqlite3_snapshot **ppSnapshot +); +</pre></blockquote> +<p> +The <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get(D,S,P)</a> interface attempts to make a +new <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object that records the current state of +schema S in database connection D. On success, the +<a href="#sqlite3_snapshot_get">sqlite3_snapshot_get(D,S,P)</a> interface writes a pointer to the newly +created <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object into *P and returns SQLITE_OK. +If there is not already a read-transaction open on schema S when +this function is called, one is opened automatically.</p> + +<p>The following must be true for this function to succeed. If any of +the following statements are false when sqlite3_snapshot_get() is +called, SQLITE_ERROR is returned. The final value of *P is undefined +in this case.</p> + +<p><ul> +<li> The database handle must not be in <a href="#sqlite3_get_autocommit">autocommit mode</a>.</p> + +<p><li> Schema S of <a href="#sqlite3">database connection</a> D must be a <a href="wal.html">WAL mode</a> database.</p> + +<p><li> There must not be a write transaction open on schema S of database +connection D.</p> + +<p><li> One or more transactions must have been written to the current wal +file since it was created on disk (by any connection). This means +that a snapshot cannot be taken on a wal mode database with no wal +file immediately after it is first opened. At least one transaction +must be written to it first. +</ul></p> + +<p>This function may also return SQLITE_NOMEM. If it is called with the +database handle in autocommit mode but fails for some other reason, +whether or not a read transaction is opened on schema S is undefined.</p> + +<p>The <a href="#sqlite3_snapshot">sqlite3_snapshot</a> object returned from a successful call to +<a href="#sqlite3_snapshot_get">sqlite3_snapshot_get()</a> must be freed using <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free()</a> +to avoid a memory leak.</p> + +<p>The <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get()</a> interface is only available when the +<a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> compile-time option is used. +</p><hr><a name="sqlite3_snapshot_open"></a> +<h2>Start a read transaction on an historical snapshot</h2> +</div> +<blockquote><pre> +int sqlite3_snapshot_open( + sqlite3 *db, + const char *zSchema, + sqlite3_snapshot *pSnapshot +); +</pre></blockquote> +<p> +The <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open(D,S,P)</a> interface either starts a new read +transaction or upgrades an existing one for schema S of +<a href="#sqlite3">database connection</a> D such that the read transaction refers to +historical <a href="#sqlite3_snapshot">snapshot</a> P, rather than the most recent change to the +database. The <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a> interface returns SQLITE_OK +on success or an appropriate <a href="rescode.html">error code</a> if it fails.</p> + +<p>In order to succeed, the database connection must not be in +<a href="#sqlite3_get_autocommit">autocommit mode</a> when <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open(D,S,P)</a> is called. If there +is already a read transaction open on schema S, then the database handle +must have no active statements (SELECT statements that have been passed +to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()). +SQLITE_ERROR is returned if either of these conditions is violated, or +if schema S does not exist, or if the snapshot object is invalid.</p> + +<p>A call to sqlite3_snapshot_open() will fail to open if the specified +snapshot has been overwritten by a <a href="wal.html#ckpt">checkpoint</a>. In this case +SQLITE_ERROR_SNAPSHOT is returned.</p> + +<p>If there is already a read transaction open when this function is +invoked, then the same read transaction remains open (on the same +database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT +is returned. If another error code - for example SQLITE_PROTOCOL or an +SQLITE_IOERR error code - is returned, then the final state of the +read transaction is undefined. If SQLITE_OK is returned, then the +read transaction is now open on database snapshot P.</p> + +<p>A call to <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open(D,S,P)</a> will fail if the +database connection D does not know that the database file for +schema S is in <a href="wal.html">WAL mode</a>. A database connection might not know +that the database file is in <a href="wal.html">WAL mode</a> if there has been no prior +I/O on that database connection, or if the database entered <a href="wal.html">WAL mode</a> +after the most recent I/O on the database connection. +(Hint: Run "<a href="pragma.html#pragma_application_id">PRAGMA application_id</a>" against a newly opened +database connection in order to make it ready to use snapshots.)</p> + +<p>The <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a> interface is only available when the +<a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> compile-time option is used. +</p><hr><a name="sqlite3_snapshot_recover"></a> +<h2>Recover snapshots from a wal file</h2> +</div> +<blockquote><pre> +int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb); +</pre></blockquote> +<p> +If a <a href="wal.html#walfile">WAL file</a> remains on disk after all database connections close +(either through the use of the <a href="#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> <a href="#sqlite3_file_control">file control</a> +or because the last process to have the database opened exited without +calling <a href="#sqlite3_close">sqlite3_close()</a>) and a new connection is subsequently opened +on that database and <a href="wal.html#walfile">WAL file</a>, the <a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a> interface +will only be able to open the last transaction added to the WAL file +even though the WAL file contains other valid transactions.</p> + +<p>This function attempts to scan the WAL file associated with database zDb +of database handle db and make all valid snapshots available to +sqlite3_snapshot_open(). It is an error if there is already a read +transaction open on the database, or if the database is not a WAL mode +database.</p> + +<p>SQLITE_OK is returned if successful, or an SQLite error code otherwise.</p> + +<p>This interface is only available if SQLite is compiled with the +<a href="compile.html#enable_snapshot">SQLITE_ENABLE_SNAPSHOT</a> option. +</p><hr><a name="sqlite3_soft_heap_limit"></a> +<h2>Deprecated Soft Heap Limit Interface</h2> +</div> +<blockquote><pre> +void sqlite3_soft_heap_limit(int N); +</pre></blockquote> +<p> +This is a deprecated version of the <a href="#sqlite3_hard_heap_limit64">sqlite3_soft_heap_limit64()</a> +interface. This routine is provided for historical compatibility +only. All new applications should use the +<a href="#sqlite3_hard_heap_limit64">sqlite3_soft_heap_limit64()</a> interface rather than this one. +</p><hr><a name="sqlite3_step"></a> +<h2>Evaluate An SQL Statement</h2> +</div> +<blockquote><pre> +int sqlite3_step(sqlite3_stmt*); +</pre></blockquote> +<p> +After a <a href="#sqlite3_stmt">prepared statement</a> has been prepared using any of +<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>, +or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> or one of the legacy +interfaces <a href="#sqlite3_prepare">sqlite3_prepare()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16()</a>, this function +must be called one or more times to evaluate the statement.</p> + +<p>The details of the behavior of the sqlite3_step() interface depend +on whether the statement was prepared using the newer "vX" interfaces +<a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>, +<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or the older legacy +interfaces <a href="#sqlite3_prepare">sqlite3_prepare()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16()</a>. The use of the +new "vX" interface is recommended for new applications but the legacy +interface will continue to be supported.</p> + +<p>In the legacy interface, the return value will be either <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, +<a href="#SQLITE_ABORT">SQLITE_DONE</a>, <a href="#SQLITE_ABORT">SQLITE_ROW</a>, <a href="#SQLITE_ABORT">SQLITE_ERROR</a>, or <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. +With the "v2" interface, any of the other <a href="rescode.html">result codes</a> or +<a href="rescode.html#extrc">extended result codes</a> might be returned as well.</p> + +<p><a href="#SQLITE_ABORT">SQLITE_BUSY</a> means that the database engine was unable to acquire the +database locks it needs to do its job. If the statement is a <a href="lang_transaction.html">COMMIT</a> +or occurs outside of an explicit transaction, then you can retry the +statement. If the statement is not a <a href="lang_transaction.html">COMMIT</a> and occurs within an +explicit transaction then you should rollback the transaction before +continuing.</p> + +<p><a href="#SQLITE_ABORT">SQLITE_DONE</a> means that the statement has finished executing +successfully. sqlite3_step() should not be called again on this virtual +machine without first calling <a href="#sqlite3_reset">sqlite3_reset()</a> to reset the virtual +machine back to its initial state.</p> + +<p>If the SQL statement being executed returns any data, then <a href="#SQLITE_ABORT">SQLITE_ROW</a> +is returned each time a new row of data is ready for processing by the +caller. The values may be accessed using the <a href="#sqlite3_column_blob">column access functions</a>. +sqlite3_step() is called again to retrieve the next row of data.</p> + +<p><a href="#SQLITE_ABORT">SQLITE_ERROR</a> means that a run-time error (such as a constraint +violation) has occurred. sqlite3_step() should not be called again on +the VM. More information may be found by calling <a href="#sqlite3_errcode">sqlite3_errmsg()</a>. +With the legacy interface, a more specific error code (for example, +<a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>, <a href="#SQLITE_ABORT">SQLITE_SCHEMA</a>, <a href="#SQLITE_ABORT">SQLITE_CORRUPT</a>, and so forth) +can be obtained by calling <a href="#sqlite3_reset">sqlite3_reset()</a> on the +<a href="#sqlite3_stmt">prepared statement</a>. In the "v2" interface, +the more specific error code is returned directly by sqlite3_step().</p> + +<p><a href="#SQLITE_ABORT">SQLITE_MISUSE</a> means that the this routine was called inappropriately. +Perhaps it was called on a <a href="#sqlite3_stmt">prepared statement</a> that has +already been <a href="#sqlite3_finalize">finalized</a> or on one that had +previously returned <a href="#SQLITE_ABORT">SQLITE_ERROR</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>. Or it could +be the case that the same database connection is being used by two or +more threads at the same moment in time.</p> + +<p>For all versions of SQLite up to and including 3.6.23.1, a call to +<a href="#sqlite3_reset">sqlite3_reset()</a> was required after sqlite3_step() returned anything +other than <a href="#SQLITE_ABORT">SQLITE_ROW</a> before any subsequent invocation of +sqlite3_step(). Failure to reset the prepared statement using +<a href="#sqlite3_reset">sqlite3_reset()</a> would result in an <a href="#SQLITE_ABORT">SQLITE_MISUSE</a> return from +sqlite3_step(). But after <a href="releaselog/3_6_23_1.html">version 3.6.23.1</a> (2010-03-26, +sqlite3_step() began +calling <a href="#sqlite3_reset">sqlite3_reset()</a> automatically in this circumstance rather +than returning <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. This is not considered a compatibility +break because any application that ever receives an SQLITE_MISUSE error +is broken by definition. The <a href="compile.html#omit_autoreset">SQLITE_OMIT_AUTORESET</a> compile-time option +can be used to restore the legacy behavior.</p> + +<p><b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() +API always returns a generic error code, <a href="#SQLITE_ABORT">SQLITE_ERROR</a>, following any +error other than <a href="#SQLITE_ABORT">SQLITE_BUSY</a> and <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. You must call +<a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a> in order to find one of the +specific <a href="rescode.html">error codes</a> that better describes the error. +We admit that this is a goofy design. The problem has been fixed +with the "v2" interface. If you prepare all of your SQL statements +using <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> or <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> +or <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> instead +of the legacy <a href="#sqlite3_prepare">sqlite3_prepare()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16()</a> interfaces, +then the more specific <a href="rescode.html">error codes</a> are returned directly +by sqlite3_step(). The use of the "vX" interfaces is recommended. +</p><hr><a name="sqlite3_stmt_busy"></a> +<h2>Determine If A Prepared Statement Has Been Reset</h2> +</div> +<blockquote><pre> +int sqlite3_stmt_busy(sqlite3_stmt*); +</pre></blockquote> +<p> +The sqlite3_stmt_busy(S) interface returns true (non-zero) if the +<a href="#sqlite3_stmt">prepared statement</a> S has been stepped at least once using +<a href="#sqlite3_step">sqlite3_step(S)</a> but has neither run to completion (returned +<a href="#SQLITE_ABORT">SQLITE_DONE</a> from <a href="#sqlite3_step">sqlite3_step(S)</a>) nor +been reset using <a href="#sqlite3_reset">sqlite3_reset(S)</a>. The sqlite3_stmt_busy(S) +interface returns false if S is a NULL pointer. If S is not a +NULL pointer and is not a pointer to a valid <a href="#sqlite3_stmt">prepared statement</a> +object, then the behavior is undefined and probably undesirable.</p> + +<p>This interface can be used in combination <a href="#sqlite3_next_stmt">sqlite3_next_stmt()</a> +to locate all prepared statements associated with a database +connection that are in need of being reset. This can be used, +for example, in diagnostic routines to search for prepared +statements that are holding a transaction open. +</p><hr><a name="sqlite3_stmt_explain"></a> +<h2>Change The EXPLAIN Setting For A Prepared Statement</h2> +</div> +<blockquote><pre> +int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode); +</pre></blockquote> +<p> +The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN +setting for <a href="#sqlite3_stmt">prepared statement</a> S. If E is zero, then S becomes +a normal prepared statement. If E is 1, then S behaves as if +its SQL text began with "<a href="lang_explain.html">EXPLAIN</a>". If E is 2, then S behaves as if +its SQL text began with "<a href="eqp.html">EXPLAIN QUERY PLAN</a>".</p> + +<p>Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared. +SQLite tries to avoid a reprepare, but a reprepare might be necessary +on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.</p> + +<p>Because of the potential need to reprepare, a call to +sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be +reprepared because it was created using <a href="#sqlite3_prepare">sqlite3_prepare()</a> instead of +the newer <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> interfaces and +hence has no saved SQL text with which to reprepare.</p> + +<p>Changing the explain setting for a prepared statement does not change +the original SQL text for the statement. Hence, if the SQL text originally +began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0) +is called to convert the statement into an ordinary statement, the EXPLAIN +or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S) +output, even though the statement now acts like a normal SQL statement.</p> + +<p>This routine returns SQLITE_OK if the explain mode is successfully +changed, or an error code if the explain mode could not be changed. +The explain mode cannot be changed while a statement is active. +Hence, it is good practice to call <a href="#sqlite3_reset">sqlite3_reset(S)</a> +immediately prior to calling sqlite3_stmt_explain(S,E). +</p><hr><a name="sqlite3_stmt_isexplain"></a> +<h2>Query The EXPLAIN Setting For A Prepared Statement</h2> +</div> +<blockquote><pre> +int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +The sqlite3_stmt_isexplain(S) interface returns 1 if the +prepared statement S is an EXPLAIN statement, or 2 if the +statement S is an EXPLAIN QUERY PLAN. +The sqlite3_stmt_isexplain(S) interface returns 0 if S is +an ordinary statement or a NULL pointer. +</p><hr><a name="sqlite3_stmt_readonly"></a> +<h2>Determine If An SQL Statement Writes The Database</h2> +</div> +<blockquote><pre> +int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); +</pre></blockquote> +<p> +The sqlite3_stmt_readonly(X) interface returns true (non-zero) if +and only if the <a href="#sqlite3_stmt">prepared statement</a> X makes no direct changes to +the content of the database file.</p> + +<p>Note that <a href="appfunc.html">application-defined SQL functions</a> or +<a href="vtab.html">virtual tables</a> might change the database indirectly as a side effect. +For example, if an application defines a function "eval()" that +calls <a href="#sqlite3_exec">sqlite3_exec()</a>, then the following SQL statement would +change the database file through side-effects:</p> + +<p><blockquote><pre> +SELECT eval('DELETE FROM t1') FROM t2; +</pre></blockquote></p> + +<p>But because the <a href="lang_select.html">SELECT</a> statement does not change the database file +directly, sqlite3_stmt_readonly() would still return true.</p> + +<p>Transaction control statements such as <a href="lang_transaction.html">BEGIN</a>, <a href="lang_transaction.html">COMMIT</a>, <a href="lang_transaction.html">ROLLBACK</a>, +<a href="lang_savepoint.html">SAVEPOINT</a>, and <a href="lang_savepoint.html">RELEASE</a> cause sqlite3_stmt_readonly() to return true, +since the statements themselves do not actually modify the database but +rather they control the timing of when other statements modify the +database. The <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> statements also cause +sqlite3_stmt_readonly() to return true since, while those statements +change the configuration of a database connection, they do not make +changes to the content of the database files on disk. +The sqlite3_stmt_readonly() interface returns true for <a href="lang_transaction.html">BEGIN</a> since +<a href="lang_transaction.html">BEGIN</a> merely sets internal flags, but the <a href="lang_transaction.html">BEGIN IMMEDIATE</a> and +<a href="lang_transaction.html">BEGIN EXCLUSIVE</a> commands do touch the database and so +sqlite3_stmt_readonly() returns false for those commands.</p> + +<p>This routine returns false if there is any possibility that the +statement might change the database file. A false return does +not guarantee that the statement will change the database file. +For example, an UPDATE statement might have a WHERE clause that +makes it a no-op, but the sqlite3_stmt_readonly() result would still +be false. Similarly, a CREATE TABLE IF NOT EXISTS statement is a +read-only no-op if the table already exists, but +sqlite3_stmt_readonly() still returns false for such a statement.</p> + +<p>If prepared statement X is an <a href="lang_explain.html">EXPLAIN</a> or <a href="eqp.html">EXPLAIN QUERY PLAN</a> +statement, then sqlite3_stmt_readonly(X) returns the same value as +if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted. +</p><hr><a name="sqlite3_stmt_scanstatus_reset"></a> +<h2>Zero Scan-Status Counters</h2> +</div> +<blockquote><pre> +void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); +</pre></blockquote> +<p> +Zero all <a href="#sqlite3_stmt_scanstatus">sqlite3_stmt_scanstatus()</a> related event counters.</p> + +<p>This API is only available if the library is built with pre-processor +symbol <a href="compile.html#enable_stmt_scanstatus">SQLITE_ENABLE_STMT_SCANSTATUS</a> defined. +</p><hr><a name="sqlite3_stmt_status"></a> +<h2>Prepared Statement Status</h2> +</div> +<blockquote><pre> +int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); +</pre></blockquote> +<p> +Each prepared statement maintains various +<a href="#SQLITE_STMTSTATUS counter">SQLITE_STMTSTATUS counters</a> that measure the number +of times it has performed specific operations. These counters can +be used to monitor the performance characteristics of the prepared +statements. For example, if the number of table steps greatly exceeds +the number of table searches or result rows, that would tend to indicate +that the prepared statement is using a full table scan rather than +an index.</p> + +<p>This interface is used to retrieve and reset counter values from +a <a href="#sqlite3_stmt">prepared statement</a>. The first argument is the prepared statement +object to be interrogated. The second argument +is an integer code for a specific <a href="#SQLITE_STMTSTATUS counter">SQLITE_STMTSTATUS counter</a> +to be interrogated. +The current value of the requested counter is returned. +If the resetFlg is true, then the counter is reset to zero after this +interface call returns.</p> + +<p>See also: <a href="#sqlite3_status">sqlite3_status()</a> and <a href="#sqlite3_db_status">sqlite3_db_status()</a>. +</p><hr><a name="sqlite3_str_finish"></a> +<h2>Finalize A Dynamic String</h2> +</div> +<blockquote><pre> +char *sqlite3_str_finish(sqlite3_str*); +</pre></blockquote> +<p> +The <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a> interface destroys the sqlite3_str object X +and returns a pointer to a memory buffer obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a> +that contains the constructed string. The calling application should +pass the returned value to <a href="#sqlite3_free">sqlite3_free()</a> to avoid a memory leak. +The <a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a> interface may return a NULL pointer if any +errors were encountered during construction of the string. The +<a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a> interface will also return a NULL pointer if the +string in <a href="#sqlite3_str">sqlite3_str</a> object X is zero bytes long. +</p><hr><a name="sqlite3_str_new"></a> +<h2>Create A New Dynamic String Object</h2> +</div> +<blockquote><pre> +sqlite3_str *sqlite3_str_new(sqlite3*); +</pre></blockquote> +<p> +The <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> interface allocates and initializes +a new <a href="#sqlite3_str">sqlite3_str</a> object. To avoid memory leaks, the object returned by +<a href="#sqlite3_str_new">sqlite3_str_new()</a> must be freed by a subsequent call to +<a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a>.</p> + +<p>The <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> interface always returns a pointer to a +valid <a href="#sqlite3_str">sqlite3_str</a> object, though in the event of an out-of-memory +error the returned object might be a special singleton that will +silently reject new text, always return SQLITE_NOMEM from +<a href="#sqlite3_str_errcode">sqlite3_str_errcode()</a>, always return 0 for +<a href="#sqlite3_str_errcode">sqlite3_str_length()</a>, and always return NULL from +<a href="#sqlite3_str_finish">sqlite3_str_finish(X)</a>. It is always safe to use the value +returned by <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> as the sqlite3_str parameter +to any of the other <a href="#sqlite3_str">sqlite3_str</a> methods.</p> + +<p>The D parameter to <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> may be NULL. If the +D parameter in <a href="#sqlite3_str_new">sqlite3_str_new(D)</a> is not NULL, then the maximum +length of the string contained in the <a href="#sqlite3_str">sqlite3_str</a> object will be +the value set for <a href="#sqlite3_limit">sqlite3_limit</a>(D,<a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>) instead +of <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a>. +</p><hr><a name="sqlite3_strglob"></a> +<h2>String Globbing</h2> +</div> +<blockquote><pre> +int sqlite3_strglob(const char *zGlob, const char *zStr); +</pre></blockquote> +<p>The <a href="#sqlite3_strglob">sqlite3_strglob(P,X)</a> interface returns zero if and only if +string X matches the <a href="lang_expr.html#glob">GLOB</a> pattern P. +The definition of <a href="lang_expr.html#glob">GLOB</a> pattern matching used in +<a href="#sqlite3_strglob">sqlite3_strglob(P,X)</a> is the same as for the "X GLOB P" operator in the +SQL dialect understood by SQLite. The <a href="#sqlite3_strglob">sqlite3_strglob(P,X)</a> function +is case sensitive.</p> + +<p>Note that this routine returns zero on a match and non-zero if the strings +do not match, the same as <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a>.</p> + +<p>See also: <a href="#sqlite3_strlike">sqlite3_strlike()</a>. +</p><hr><a name="sqlite3_strlike"></a> +<h2>String LIKE Matching</h2> +</div> +<blockquote><pre> +int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc); +</pre></blockquote> +<p>The <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> interface returns zero if and only if +string X matches the <a href="lang_expr.html#like">LIKE</a> pattern P with escape character E. +The definition of <a href="lang_expr.html#like">LIKE</a> pattern matching used in +<a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> is the same as for the "X LIKE P ESCAPE E" +operator in the SQL dialect understood by SQLite. For "X LIKE P" without +the ESCAPE clause, set the E parameter of <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> to 0. +As with the LIKE operator, the <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> function is case +insensitive - equivalent upper and lower case ASCII characters match +one another.</p> + +<p>The <a href="#sqlite3_strlike">sqlite3_strlike(P,X,E)</a> function matches Unicode characters, though +only ASCII characters are case folded.</p> + +<p>Note that this routine returns zero on a match and non-zero if the strings +do not match, the same as <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a>.</p> + +<p>See also: <a href="#sqlite3_strglob">sqlite3_strglob()</a>. +</p><hr><a name="sqlite3_system_errno"></a> +<h2>Low-level system error code</h2> +</div> +<blockquote><pre> +int sqlite3_system_errno(sqlite3*); +</pre></blockquote> +<p> +Attempt to return the underlying operating system error code or error +number that caused the most recent I/O error or failure to open a file. +The return value is OS-dependent. For example, on unix systems, after +<a href="#sqlite3_open">sqlite3_open_v2()</a> returns <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a>, this interface could be +called to get back the underlying "errno" that caused the problem, such +as ENOSPC, EAUTH, EISDIR, and so forth. +</p><hr><a name="sqlite3_table_column_metadata"></a> +<h2>Extract Metadata About A Column Of A Table</h2> +</div> +<blockquote><pre> +int sqlite3_table_column_metadata( + sqlite3 *db, /* Connection handle */ + const char *zDbName, /* Database name or NULL */ + const char *zTableName, /* Table name */ + const char *zColumnName, /* Column name */ + char const **pzDataType, /* OUTPUT: Declared data type */ + char const **pzCollSeq, /* OUTPUT: Collation sequence name */ + int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ + int *pPrimaryKey, /* OUTPUT: True if column part of PK */ + int *pAutoinc /* OUTPUT: True if column is auto-increment */ +); +</pre></blockquote> +<p> +The sqlite3_table_column_metadata(X,D,T,C,....) routine returns +information about column C of table T in database D +on <a href="#sqlite3">database connection</a> X. The sqlite3_table_column_metadata() +interface returns SQLITE_OK and fills in the non-NULL pointers in +the final five arguments with appropriate values if the specified +column exists. The sqlite3_table_column_metadata() interface returns +SQLITE_ERROR if the specified column does not exist. +If the column-name parameter to sqlite3_table_column_metadata() is a +NULL pointer, then this routine simply checks for the existence of the +table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it +does not. If the table name parameter T in a call to +sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is +undefined behavior.</p> + +<p>The column is identified by the second, third and fourth parameters to +this function. The second parameter is either the name of the database +(i.e. "main", "temp", or an attached database) containing the specified +table or NULL. If it is NULL, then all attached databases are searched +for the table using the same algorithm used by the database engine to +resolve unqualified table references.</p> + +<p>The third and fourth parameters to this function are the table and column +name of the desired column, respectively.</p> + +<p>Metadata is returned by writing to the memory locations passed as the 5th +and subsequent parameters to this function. Any of these arguments may be +NULL, in which case the corresponding element of metadata is omitted.</p> + +<p><blockquote> +<table border="1"> +<tr><th> Parameter <th> Output<br>Type <th> Description</p> + +<p><tr><td> 5th <td> const char* <td> Data type +<tr><td> 6th <td> const char* <td> Name of default collation sequence +<tr><td> 7th <td> int <td> True if column has a NOT NULL constraint +<tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY +<tr><td> 9th <td> int <td> True if column is <a href="autoinc.html">AUTOINCREMENT</a> +</table> +</blockquote></p> + +<p>The memory pointed to by the character pointers returned for the +declaration type and collation sequence is valid until the next +call to any SQLite API function.</p> + +<p>If the specified table is actually a view, an <a href="rescode.html">error code</a> is returned.</p> + +<p>If the specified column is "rowid", "oid" or "_rowid_" and the table +is not a <a href="withoutrowid.html">WITHOUT ROWID</a> table and an +<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> column has been explicitly declared, then the output +parameters are set for the explicitly declared column. If there is no +<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> column, then the outputs +for the <a href="lang_createtable.html#rowid">rowid</a> are set as follows:</p> + +<p><pre> +data type: "INTEGER" +collation sequence: "BINARY" +not null: 0 +primary key: 1 +auto increment: 0 +</pre></p> + +<p>This function causes all database schemas to be read from disk and +parsed, if that has not already been done, and returns an error if +any errors are encountered while loading the schema. +</p><hr><a name="sqlite3_test_control"></a> +<h2>Testing Interface</h2> +</div> +<blockquote><pre> +int sqlite3_test_control(int op, ...); +</pre></blockquote> +<p> +The sqlite3_test_control() interface is used to read out internal +state of SQLite and to inject faults into SQLite for testing +purposes. The first parameter is an operation code that determines +the number, meaning, and operation of all subsequent parameters.</p> + +<p>This interface is not for use by applications. It exists solely +for verifying the correct operation of the SQLite library. Depending +on how the SQLite library is compiled, this interface might not exist.</p> + +<p>The details of the operation codes, their meanings, the parameters +they take, and what they do are all subject to change without notice. +Unlike most of the SQLite API, this function is not guaranteed to +operate consistently from one release to the next. +</p><hr><a name="sqlite3_threadsafe"></a> +<h2>Test To See If The Library Is Threadsafe</h2> +</div> +<blockquote><pre> +int sqlite3_threadsafe(void); +</pre></blockquote> +<p> +The sqlite3_threadsafe() function returns zero if and only if +SQLite was compiled with mutexing code omitted due to the +<a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> compile-time option being set to 0.</p> + +<p>SQLite can be compiled with or without mutexes. When +the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> C preprocessor macro is 1 or 2, mutexes +are enabled and SQLite is threadsafe. When the +<a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> macro is 0, +the mutexes are omitted. Without the mutexes, it is not safe +to use SQLite concurrently from more than one thread.</p> + +<p>Enabling mutexes incurs a measurable performance penalty. +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.</p> + +<p>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 <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> macro.</p> + +<p>This interface only reports on the compile-time mutex setting +of the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> flag. If SQLite is compiled with +SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but +can be fully or partially disabled using a call to <a href="#sqlite3_config">sqlite3_config()</a> +with the verbs <a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a>, <a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>, +or <a href="#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a>. The return value of the +sqlite3_threadsafe() function shows only the compile-time setting of +thread safety, not any run-time changes to that setting made by +sqlite3_config(). In other words, the return value from sqlite3_threadsafe() +is unchanged by calls to sqlite3_config().</p> + +<p>See the <a href="threadsafe.html">threading mode</a> documentation for additional information. +</p><hr><a name="sqlite3_trace_v2"></a> +<h2>SQL Trace Hook</h2> +</div> +<blockquote><pre> +int sqlite3_trace_v2( + sqlite3*, + unsigned uMask, + int(*xCallback)(unsigned,void*,void*,void*), + void *pCtx +); +</pre></blockquote> +<p> +The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback +function X against <a href="#sqlite3">database connection</a> D, using property mask M +and context pointer P. If the X callback is +NULL or if the M mask is zero, then tracing is disabled. The +M argument should be the bitwise OR-ed combination of +zero or more <a href="#SQLITE_TRACE">SQLITE_TRACE</a> constants.</p> + +<p>Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P) +overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or +sqlite3_trace_v2(D,M,X,P) for the <a href="#sqlite3">database connection</a> D. Each +database connection may have at most one trace callback.</p> + +<p>The X callback is invoked whenever any of the events identified by +mask M occur. The integer return value from the callback is currently +ignored, though this may change in future releases. Callback +implementations should return zero to ensure future compatibility.</p> + +<p>A trace callback is invoked with four arguments: callback(T,C,P,X). +The T argument is one of the <a href="#SQLITE_TRACE">SQLITE_TRACE</a> +constants to indicate why the callback was invoked. +The C argument is a copy of the context pointer. +The P and X arguments are pointers whose meanings depend on T.</p> + +<p>The sqlite3_trace_v2() interface is intended to replace the legacy +interfaces <a href="#sqlite3_profile">sqlite3_trace()</a> and <a href="#sqlite3_profile">sqlite3_profile()</a>, both of which +are deprecated. +</p><hr><a name="sqlite3_txn_state"></a> +<h2>Determine the transaction state of a database</h2> +</div> +<blockquote><pre> +int sqlite3_txn_state(sqlite3*,const char *zSchema); +</pre></blockquote> +<p> +The sqlite3_txn_state(D,S) interface returns the current +<a href="#SQLITE_TXN_NONE">transaction state</a> of schema S in database connection D. If S is NULL, +then the highest transaction state of any schema on database connection D +is returned. Transaction states are (in order of lowest to highest): +<ol> +<li value="0"> SQLITE_TXN_NONE +<li value="1"> SQLITE_TXN_READ +<li value="2"> SQLITE_TXN_WRITE +</ol> +If the S argument to sqlite3_txn_state(D,S) is not the name of +a valid schema, then -1 is returned. +</p><hr><a name="sqlite3_unlock_notify"></a> +<h2>Unlock Notification</h2> +</div> +<blockquote><pre> +int sqlite3_unlock_notify( + sqlite3 *pBlocked, /* Waiting connection */ + void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ + void *pNotifyArg /* Argument to pass to xNotify */ +); +</pre></blockquote> +<p> +When running in shared-cache mode, a database operation may fail with +an <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> error if the required locks on the shared-cache or +individual tables within the shared-cache cannot be obtained. See +<a href="sharedcache.html">SQLite Shared-Cache Mode</a> for a description of shared-cache locking. +This API may be used to register a callback that SQLite will invoke +when the connection currently holding the required lock relinquishes it. +This API is only available if the library was compiled with the +<a href="compile.html#enable_unlock_notify">SQLITE_ENABLE_UNLOCK_NOTIFY</a> C-preprocessor symbol defined.</p> + +<p>See Also: <a href="unlock_notify.html">Using the SQLite Unlock Notification Feature</a>.</p> + +<p>Shared-cache locks are released when a database connection concludes +its current transaction, either by committing it or rolling it back.</p> + +<p>When a connection (known as the blocked connection) fails to obtain a +shared-cache lock and SQLITE_LOCKED is returned to the caller, the +identity of the database connection (the blocking connection) that +has locked the required resource is stored internally. After an +application receives an SQLITE_LOCKED error, it may call the +sqlite3_unlock_notify() method with the blocked connection handle as +the first argument to register for a callback that will be invoked +when the blocking connections current transaction is concluded. The +callback is invoked from within the <a href="#sqlite3_step">sqlite3_step</a> or <a href="#sqlite3_close">sqlite3_close</a> +call that concludes the blocking connection's transaction.</p> + +<p>If sqlite3_unlock_notify() is called in a multi-threaded application, +there is a chance that the blocking connection will have already +concluded its transaction by the time sqlite3_unlock_notify() is invoked. +If this happens, then the specified callback is invoked immediately, +from within the call to sqlite3_unlock_notify().</p> + +<p>If the blocked connection is attempting to obtain a write-lock on a +shared-cache table, and more than one other connection currently holds +a read-lock on the same table, then SQLite arbitrarily selects one of +the other connections to use as the blocking connection.</p> + +<p>There may be at most one unlock-notify callback registered by a +blocked connection. If sqlite3_unlock_notify() is called when the +blocked connection already has a registered unlock-notify callback, +then the new callback replaces the old. If sqlite3_unlock_notify() is +called with a NULL pointer as its second argument, then any existing +unlock-notify callback is canceled. The blocked connections +unlock-notify callback may also be canceled by closing the blocked +connection using <a href="#sqlite3_close">sqlite3_close()</a>.</p> + +<p>The unlock-notify callback is not reentrant. If an application invokes +any sqlite3_xxx API functions from within an unlock-notify callback, a +crash or deadlock may be the result.</p> + +<p>Unless deadlock is detected (see below), sqlite3_unlock_notify() always +returns SQLITE_OK.</p> + +<p><b>Callback Invocation Details</b></p> + +<p>When an unlock-notify callback is registered, the application provides a +single void* pointer that is passed to the callback when it is invoked. +However, the signature of the callback function allows SQLite to pass +it an array of void* context pointers. The first argument passed to +an unlock-notify callback is a pointer to an array of void* pointers, +and the second is the number of entries in the array.</p> + +<p>When a blocking connection's transaction is concluded, there may be +more than one blocked connection that has registered for an unlock-notify +callback. If two or more such blocked connections have specified the +same callback function, then instead of invoking the callback function +multiple times, it is invoked once with the set of void* context pointers +specified by the blocked connections bundled together into an array. +This gives the application an opportunity to prioritize any actions +related to the set of unblocked database connections.</p> + +<p><b>Deadlock Detection</b></p> + +<p>Assuming that after registering for an unlock-notify callback a +database waits for the callback to be issued before taking any further +action (a reasonable assumption), then using this API may cause the +application to deadlock. For example, if connection X is waiting for +connection Y's transaction to be concluded, and similarly connection +Y is waiting on connection X's transaction, then neither connection +will proceed and the system may remain deadlocked indefinitely.</p> + +<p>To avoid this scenario, the sqlite3_unlock_notify() performs deadlock +detection. If a given call to sqlite3_unlock_notify() would put the +system in a deadlocked state, then SQLITE_LOCKED is returned and no +unlock-notify callback is registered. The system is said to be in +a deadlocked state if connection A has registered for an unlock-notify +callback on the conclusion of connection B's transaction, and connection +B has itself registered for an unlock-notify callback when connection +A's transaction is concluded. Indirect deadlock is also detected, so +the system is also considered to be deadlocked if connection B has +registered for an unlock-notify callback on the conclusion of connection +C's transaction, where connection C is waiting on connection A. Any +number of levels of indirection are allowed.</p> + +<p><b>The "DROP TABLE" Exception</b></p> + +<p>When a call to <a href="#sqlite3_step">sqlite3_step()</a> returns SQLITE_LOCKED, it is almost +always appropriate to call sqlite3_unlock_notify(). There is however, +one exception. When executing a "DROP TABLE" or "DROP INDEX" statement, +SQLite checks if there are any currently executing SELECT statements +that belong to the same connection. If there are, SQLITE_LOCKED is +returned. In this case there is no "blocking connection", so invoking +sqlite3_unlock_notify() results in the unlock-notify callback being +invoked immediately. If the application then re-attempts the "DROP TABLE" +or "DROP INDEX" query, an infinite loop might be the result.</p> + +<p>One way around this problem is to check the extended error code returned +by an sqlite3_step() call. If there is a blocking connection, then the +extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in +the special "DROP TABLE/INDEX" case, the extended error code is just +SQLITE_LOCKED. +</p><hr><a name="sqlite3_update_hook"></a> +<h2>Data Change Notification Callbacks</h2> +</div> +<blockquote><pre> +void *sqlite3_update_hook( + sqlite3*, + void(*)(void *,int ,char const *,char const *,sqlite3_int64), + void* +); +</pre></blockquote> +<p> +The sqlite3_update_hook() interface registers a callback function +with the <a href="#sqlite3">database connection</a> identified by the first argument +to be invoked whenever a row is updated, inserted or deleted in +a <a href="rowidtable.html">rowid table</a>. +Any callback set by a previous call to this function +for the same database connection is overridden.</p> + +<p>The second argument is a pointer to the function to invoke when a +row is updated, inserted or deleted in a rowid table. +The first argument to the callback is a copy of the third argument +to sqlite3_update_hook(). +The second callback argument is one of <a href="#SQLITE_ALTER_TABLE">SQLITE_INSERT</a>, <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a>, +or <a href="#SQLITE_ALTER_TABLE">SQLITE_UPDATE</a>, depending on the operation that caused the callback +to be invoked. +The third and fourth arguments to the callback contain pointers to the +database and table name containing the affected row. +The final callback parameter is the <a href="lang_createtable.html#rowid">rowid</a> of the row. +In the case of an update, this is the <a href="lang_createtable.html#rowid">rowid</a> after the update takes place.</p> + +<p>The update hook is not invoked when internal system tables are +modified (i.e. sqlite_sequence). +The update hook is not invoked when <a href="withoutrowid.html">WITHOUT ROWID</a> tables are modified.</p> + +<p>In the current implementation, the update hook +is not invoked when conflicting rows are deleted because of an +<a href="lang_conflict.html">ON CONFLICT REPLACE</a> clause. Nor is the update hook +invoked when rows are deleted using the <a href="lang_delete.html#truncateopt">truncate optimization</a>. +The exceptions defined in this paragraph might change in a future +release of SQLite.</p> + +<p>The update hook implementation must not do anything that will modify +the database connection that invoked the update hook. Any actions +to modify the database connection must be deferred until after the +completion of the <a href="#sqlite3_step">sqlite3_step()</a> call that triggered the update hook. +Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their +database connections for the meaning of "modify" in this paragraph.</p> + +<p>The sqlite3_update_hook(D,C,P) function +returns the P argument from the previous call +on the same <a href="#sqlite3">database connection</a> D, or NULL for +the first call on D.</p> + +<p>See also the <a href="#sqlite3_commit_hook">sqlite3_commit_hook()</a>, <a href="#sqlite3_commit_hook">sqlite3_rollback_hook()</a>, +and <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> interfaces. +</p><hr><a name="sqlite3_user_data"></a> +<h2>User Data For Functions</h2> +</div> +<blockquote><pre> +void *sqlite3_user_data(sqlite3_context*); +</pre></blockquote> +<p> +The sqlite3_user_data() interface returns a copy of +the pointer that was the pUserData parameter (the 5th parameter) +of the <a href="#sqlite3_create_function">sqlite3_create_function()</a> +and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> routines that originally +registered the application defined function.</p> + +<p>This routine must be called from the same thread in which +the application-defined function is running. +</p><hr><a name="sqlite3_value_encoding"></a> +<h2>Report the internal text encoding state of an sqlite3_value object</h2> +</div> +<blockquote><pre> +int sqlite3_value_encoding(sqlite3_value*); +</pre></blockquote> +<p> +The sqlite3_value_encoding(X) interface returns one of <a href="#SQLITE_ANY">SQLITE_UTF8</a>, +<a href="#SQLITE_ANY">SQLITE_UTF16BE</a>, or <a href="#SQLITE_ANY">SQLITE_UTF16LE</a> according to the current text encoding +of the value X, assuming that X has type TEXT. If sqlite3_value_type(X) +returns something other than SQLITE_TEXT, then the return value from +sqlite3_value_encoding(X) is meaningless. Calls to +<a href="#sqlite3_value_blob">sqlite3_value_text(X)</a>, <a href="#sqlite3_value_blob">sqlite3_value_text16(X)</a>, <a href="#sqlite3_value_blob">sqlite3_value_text16be(X)</a>, +<a href="#sqlite3_value_blob">sqlite3_value_text16le(X)</a>, <a href="#sqlite3_value_blob">sqlite3_value_bytes(X)</a>, or +<a href="#sqlite3_value_blob">sqlite3_value_bytes16(X)</a> might change the encoding of the value X and +thus change the return from subsequent calls to sqlite3_value_encoding(X).</p> + +<p>This routine is intended for used by applications that test and validate +the SQLite implementation. This routine is inquiring about the opaque +internal state of an <a href="#sqlite3_value">sqlite3_value</a> object. Ordinary applications should +not need to know what the internal state of an sqlite3_value object is and +hence should not need to use this interface. +</p><hr><a name="sqlite3_value_subtype"></a> +<h2>Finding The Subtype Of SQL Values</h2> +</div> +<blockquote><pre> +unsigned int sqlite3_value_subtype(sqlite3_value*); +</pre></blockquote> +<p> +The sqlite3_value_subtype(V) function returns the subtype for +an <a href="appfunc.html">application-defined SQL function</a> argument V. The subtype +information can be used to pass a limited amount of context from +one SQL function to another. Use the <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> +routine to set the subtype for the return value of an SQL function.</p> + +<p>Every <a href="appfunc.html">application-defined SQL function</a> that invoke this interface +should include the <a href="#sqlitesubtype">SQLITE_SUBTYPE</a> property in the text +encoding argument when the function is <a href="#sqlite3_create_function">registered</a>. +If the <a href="#sqlitesubtype">SQLITE_SUBTYPE</a> property is omitted, then sqlite3_value_subtype() +might return zero instead of the upstream subtype in some corner cases. +</p><hr><a name="sqlite3_vtab_collation"></a> +<h2>Determine The Collation For a Virtual Table Constraint</h2> +</div> +<blockquote><pre> +const char *sqlite3_vtab_collation(sqlite3_index_info*,int); +</pre></blockquote> +<p> +This function may only be called from within a call to the <a href="vtab.html#xbestindex">xBestIndex</a> +method of a <a href="vtab.html">virtual table</a>. This function returns a pointer to a string +that is the name of the appropriate collation sequence to use for text +comparisons on the constraint identified by its arguments.</p> + +<p>The first argument must be the pointer to the <a href="#sqlite3_index_info">sqlite3_index_info</a> object +that is the first parameter to the xBestIndex() method. The second argument +must be an index into the aConstraint[] array belonging to the +sqlite3_index_info structure passed to xBestIndex.</p> + +<p>Important: +The first parameter must be the same pointer that is passed into the +xBestMethod() method. The first parameter may not be a pointer to a +different <a href="#sqlite3_index_info">sqlite3_index_info</a> object, even an exact copy.</p> + +<p>The return value is computed as follows:</p> + +<p><ol> +<li><p> If the constraint comes from a WHERE clause expression that contains +a <a href="lang_expr.html#collateop">COLLATE operator</a>, then the name of the collation specified by +that COLLATE operator is returned. +<li><p> If there is no COLLATE operator, but the column that is the subject +of the constraint specifies an alternative collating sequence via +a <a href="lang_createtable.html#collateclause">COLLATE clause</a> on the column definition within the CREATE TABLE +statement that was passed into <a href="#sqlite3_declare_vtab">sqlite3_declare_vtab()</a>, then the +name of that alternative collating sequence is returned. +<li><p> Otherwise, "BINARY" is returned. +</ol> +</p><hr><a name="sqlite3_vtab_config"></a> +<h2>Virtual Table Interface Configuration</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_config(sqlite3*, int op, ...); +</pre></blockquote> +<p> +This function may be called by either the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> method +of a <a href="vtab.html">virtual table</a> implementation to configure +various facets of the virtual table interface.</p> + +<p>If this interface is invoked outside the context of an xConnect or +xCreate virtual table method then the behavior is undefined.</p> + +<p>In the call sqlite3_vtab_config(D,C,...) the D parameter is the +<a href="#sqlite3">database connection</a> in which the virtual table is being created and +which is passed in as the first argument to the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> +method that is invoking sqlite3_vtab_config(). The C parameter is one +of the <a href="#SQLITE_VTAB_CONSTRAINT_SUPPORT">virtual table configuration options</a>. The presence and meaning +of parameters after C depend on which <a href="#SQLITE_VTAB_CONSTRAINT_SUPPORT">virtual table configuration option</a> +is used. +</p><hr><a name="sqlite3_vtab_distinct"></a> +<h2>Determine if a virtual table query is DISTINCT</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_distinct(sqlite3_index_info*); +</pre></blockquote> +<p> +This API may only be used from within an <a href="vtab.html#xbestindex">xBestIndex method</a> +of a <a href="vtab.html">virtual table</a> implementation. The result of calling this +interface from outside of xBestIndex() is undefined and probably harmful.</p> + +<p>The sqlite3_vtab_distinct() interface returns an integer between 0 and +3. The integer returned by sqlite3_vtab_distinct() +gives the virtual table additional information about how the query +planner wants the output to be ordered. As long as the virtual table +can meet the ordering requirements of the query planner, it may set +the "orderByConsumed" flag.</p> + +<p><ol><li value="0"><p> +If the sqlite3_vtab_distinct() interface returns 0, that means +that the query planner needs the virtual table to return all rows in the +sort order defined by the "nOrderBy" and "aOrderBy" fields of the +<a href="#sqlite3_index_info">sqlite3_index_info</a> object. This is the default expectation. If the +virtual table outputs all rows in sorted order, then it is always safe for +the xBestIndex method to set the "orderByConsumed" flag, regardless of +the return value from sqlite3_vtab_distinct(). +<li value="1"><p> +If the sqlite3_vtab_distinct() interface returns 1, that means +that the query planner does not need the rows to be returned in sorted order +as long as all rows with the same values in all columns identified by the +"aOrderBy" field are adjacent. This mode is used when the query planner +is doing a GROUP BY. +<li value="2"><p> +If the sqlite3_vtab_distinct() interface returns 2, that means +that the query planner does not need the rows returned in any particular +order, as long as rows with the same values in all "aOrderBy" columns +are adjacent. Furthermore, only a single row for each particular +combination of values in the columns identified by the "aOrderBy" field +needs to be returned. It is always ok for two or more rows with the same +values in all "aOrderBy" columns to be returned, as long as all such rows +are adjacent. The virtual table may, if it chooses, omit extra rows +that have the same value for all columns identified by "aOrderBy". +However omitting the extra rows is optional. +This mode is used for a DISTINCT query. +<li value="3"><p> +If the sqlite3_vtab_distinct() interface returns 3, that means +that the query planner needs only distinct rows but it does need the +rows to be sorted. The virtual table implementation is free to omit +rows that are identical in all aOrderBy columns, if it wants to, but +it is not required to omit any rows. This mode is used for queries +that have both DISTINCT and ORDER BY clauses. +</ol></p> + +<p>For the purposes of comparing virtual table output values to see if the +values are same value for sorting purposes, two NULL values are considered +to be the same. In other words, the comparison operator is "IS" +(or "IS NOT DISTINCT FROM") and not "==".</p> + +<p>If a virtual table implementation is unable to meet the requirements +specified above, then it must not set the "orderByConsumed" flag in the +<a href="#sqlite3_index_info">sqlite3_index_info</a> object or an incorrect answer may result.</p> + +<p>A virtual table implementation is always free to return rows in any order +it wants, as long as the "orderByConsumed" flag is not set. When the +the "orderByConsumed" flag is unset, the query planner will add extra +<a href="opcode.html">bytecode</a> to ensure that the final results returned by the SQL query are +ordered correctly. The use of the "orderByConsumed" flag and the +sqlite3_vtab_distinct() interface is merely an optimization. Careful +use of the sqlite3_vtab_distinct() interface and the "orderByConsumed" +flag might help queries against a virtual table to run faster. Being +overly aggressive and setting the "orderByConsumed" flag when it is not +valid to do so, on the other hand, might cause SQLite to return incorrect +results. +</p><hr><a name="sqlite3_vtab_in"></a> +<h2>Identify and handle IN constraints in xBestIndex</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle); +</pre></blockquote> +<p> +This interface may only be used from within an +<a href="vtab.html#xbestindex">xBestIndex() method</a> of a <a href="vtab.html">virtual table</a> implementation. +The result of invoking this interface from any other context is +undefined and probably harmful.</p> + +<p>A constraint on a virtual table of the form +"<a href="lang_expr.html#in_op">column IN (...)</a>" is +communicated to the xBestIndex method as a +<a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_EQ</a> constraint. If xBestIndex wants to use +this constraint, it must set the corresponding +aConstraintUsage[].argvIndex to a positive integer. Then, under +the usual mode of handling IN operators, SQLite generates <a href="opcode.html">bytecode</a> +that invokes the <a href="vtab.html#xfilter">xFilter() method</a> once for each value +on the right-hand side of the IN operator. Thus the virtual table +only sees a single value from the right-hand side of the IN operator +at a time.</p> + +<p>In some cases, however, it would be advantageous for the virtual +table to see all values on the right-hand of the IN operator all at +once. The sqlite3_vtab_in() interfaces facilitates this in two ways:</p> + +<p><ol> +<li><p> +A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero) +if and only if the <a href="#sqlite3_index_info">P->aConstraint</a>[N] constraint +is an <a href="lang_expr.html#in_op">IN operator</a> that can be processed all at once. In other words, +sqlite3_vtab_in() with -1 in the third argument is a mechanism +by which the virtual table can ask SQLite if all-at-once processing +of the IN operator is even possible.</p> + +<p><li><p> +A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates +to SQLite that the virtual table does or does not want to process +the IN operator all-at-once, respectively. Thus when the third +parameter (F) is non-negative, this interface is the mechanism by +which the virtual table tells SQLite how it wants to process the +IN operator. +</ol></p> + +<p>The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times +within the same xBestIndex method call. For any given P,N pair, +the return value from sqlite3_vtab_in(P,N,F) will always be the same +within the same xBestIndex call. If the interface returns true +(non-zero), that means that the constraint is an IN operator +that can be processed all-at-once. If the constraint is not an IN +operator or cannot be processed all-at-once, then the interface returns +false.</p> + +<p>All-at-once processing of the IN operator is selected if both of the +following conditions are met:</p> + +<p><ol> +<li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive +integer. This is how the virtual table tells SQLite that it wants to +use the N-th constraint.</p> + +<p><li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was +non-negative had F>=1. +</ol></p> + +<p>If either or both of the conditions above are false, then SQLite uses +the traditional one-at-a-time processing strategy for the IN constraint. +If both conditions are true, then the argvIndex-th parameter to the +xFilter method will be an <a href="#sqlite3_value">sqlite3_value</a> that appears to be NULL, +but which can be passed to <a href="#sqlite3_vtab_in_first">sqlite3_vtab_in_first()</a> and +<a href="#sqlite3_vtab_in_first">sqlite3_vtab_in_next()</a> to find all values on the right-hand side +of the IN constraint. +</p><hr><a name="sqlite3_vtab_nochange"></a> +<h2>Determine If Virtual Table Column Access Is For UPDATE</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_nochange(sqlite3_context*); +</pre></blockquote> +<p> +If the sqlite3_vtab_nochange(X) routine is called within the <a href="vtab.html#xcolumn">xColumn</a> +method of a <a href="vtab.html">virtual table</a>, then it might return true if the +column is being fetched as part of an UPDATE operation during which the +column value will not change. The virtual table implementation can use +this hint as permission to substitute a return value that is less +expensive to compute and that the corresponding +<a href="vtab.html#xupdate">xUpdate</a> method understands as a "no-change" value.</p> + +<p>If the <a href="vtab.html#xcolumn">xColumn</a> method calls sqlite3_vtab_nochange() and finds that +the column is not changed by the UPDATE statement, then the xColumn +method can optionally return without setting a result, without calling +any of the <a href="#sqlite3_result_blob">sqlite3_result_xxxxx() interfaces</a>. +In that case, <a href="#sqlite3_value_blob">sqlite3_value_nochange(X)</a> will return true for the +same column in the <a href="vtab.html#xupdate">xUpdate</a> method.</p> + +<p>The sqlite3_vtab_nochange() routine is an optimization. Virtual table +implementations should continue to give a correct answer even if the +sqlite3_vtab_nochange() interface were to always return false. In the +current implementation, the sqlite3_vtab_nochange() interface does always +returns false for the enhanced <a href="lang_update.html#upfrom">UPDATE FROM</a> statement. +</p><hr><a name="sqlite3_vtab_on_conflict"></a> +<h2>Determine The Virtual Table Conflict Policy</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_on_conflict(sqlite3 *); +</pre></blockquote> +<p> +This function may only be called from within a call to the <a href="vtab.html#xupdate">xUpdate</a> method +of a <a href="vtab.html">virtual table</a> implementation for an INSERT or UPDATE operation. The +value returned is one of <a href="#SQLITE_FAIL">SQLITE_ROLLBACK</a>, <a href="#SQLITE_DENY">SQLITE_IGNORE</a>, <a href="#SQLITE_FAIL">SQLITE_FAIL</a>, +<a href="#SQLITE_ABORT">SQLITE_ABORT</a>, or <a href="#SQLITE_FAIL">SQLITE_REPLACE</a>, according to the <a href="lang_conflict.html">ON CONFLICT</a> mode +of the SQL statement that triggered the call to the <a href="vtab.html#xupdate">xUpdate</a> method of the +<a href="vtab.html">virtual table</a>. +</p><hr><a name="sqlite3_vtab_rhs_value"></a> +<h2>Constraint values in xBestIndex()</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal); +</pre></blockquote> +<p> +This API may only be used from within the <a href="vtab.html#xbestindex">xBestIndex method</a> +of a <a href="vtab.html">virtual table</a> implementation. The result of calling this interface +from outside of an xBestIndex method are undefined and probably harmful.</p> + +<p>When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within +the <a href="vtab.html#xbestindex">xBestIndex</a> method of a <a href="vtab.html">virtual table</a> implementation, with P being +a copy of the <a href="#sqlite3_index_info">sqlite3_index_info</a> object pointer passed into xBestIndex and +J being a 0-based index into P->aConstraint[], then this routine +attempts to set *V to the value of the right-hand operand of +that constraint if the right-hand operand is known. If the +right-hand operand is not known, then *V is set to a NULL pointer. +The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if +and only if *V is set to a value. The sqlite3_vtab_rhs_value(P,J,V) +inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th +constraint is not available. The sqlite3_vtab_rhs_value() interface +can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if +something goes wrong.</p> + +<p>The sqlite3_vtab_rhs_value() interface is usually only successful if +the right-hand operand of a constraint is a literal value in the original +SQL statement. If the right-hand operand is an expression or a reference +to some other column or a <a href="#sqlite3_bind_blob">host parameter</a>, then sqlite3_vtab_rhs_value() +will probably return <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>.</p> + +<p>Some constraints, such as <a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ISNULL</a> and +<a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ISNOTNULL</a>, have no right-hand operand. For such +constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.</p> + +<p>The <a href="#sqlite3_value">sqlite3_value</a> object returned in *V is a protected sqlite3_value +and remains valid for the duration of the xBestIndex method call. +When xBestIndex returns, the sqlite3_value object returned by +sqlite3_vtab_rhs_value() is automatically deallocated.</p> + +<p>The "_rhs_" in the name of this routine is an abbreviation for +"Right-Hand Side". +</p><hr><a name="sqlite3_wal_autocheckpoint"></a> +<h2>Configure an auto-checkpoint</h2> +</div> +<blockquote><pre> +int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); +</pre></blockquote> +<p> +The <a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint(D,N)</a> is a wrapper around +<a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> that causes any database on <a href="#sqlite3">database connection</a> D +to automatically <a href="wal.html#ckpt">checkpoint</a> +after committing a transaction if there are N or +more frames in the <a href="wal.html">write-ahead log</a> file. Passing zero or +a negative value as the nFrame parameter disables automatic +checkpoints entirely.</p> + +<p>The callback registered by this function replaces any existing callback +registered using <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a>. Likewise, registering a callback +using <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> disables the automatic checkpoint mechanism +configured by this function.</p> + +<p>The <a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> can be used to invoke this interface +from SQL.</p> + +<p>Checkpoints initiated by this mechanism are +<a href="#sqlite3_wal_checkpoint_v2">PASSIVE</a>.</p> + +<p>Every new <a href="#sqlite3">database connection</a> defaults to having the auto-checkpoint +enabled with a threshold of 1000 or <a href="compile.html#default_wal_autocheckpoint">SQLITE_DEFAULT_WAL_AUTOCHECKPOINT</a> +pages. The use of this interface +is only necessary if the default setting is found to be suboptimal +for a particular application. +</p><hr><a name="sqlite3_wal_checkpoint"></a> +<h2>Checkpoint a database</h2> +</div> +<blockquote><pre> +int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); +</pre></blockquote> +<p> +The sqlite3_wal_checkpoint(D,X) is equivalent to +<a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2</a>(D,X,<a href="#SQLITE_CHECKPOINT_FULL">SQLITE_CHECKPOINT_PASSIVE</a>,0,0).</p> + +<p>In brief, sqlite3_wal_checkpoint(D,X) causes the content in the +<a href="wal.html">write-ahead log</a> for database X on <a href="#sqlite3">database connection</a> D to be +transferred into the database file and for the write-ahead log to +be reset. See the <a href="wal.html#ckpt">checkpointing</a> documentation for addition +information.</p> + +<p>This interface used to be the only way to cause a checkpoint to +occur. But then the newer and more powerful <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a> +interface was added. This interface is retained for backwards +compatibility and as a convenience for applications that need to manually +start a callback but which do not need the full power (and corresponding +complication) of <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a>. +</p><hr><a name="sqlite3_wal_checkpoint_v2"></a> +<h2>Checkpoint a database</h2> +</div> +<blockquote><pre> +int sqlite3_wal_checkpoint_v2( + sqlite3 *db, /* Database handle */ + const char *zDb, /* Name of attached database (or NULL) */ + int eMode, /* SQLITE_CHECKPOINT_* value */ + int *pnLog, /* OUT: Size of WAL log in frames */ + int *pnCkpt /* OUT: Total number of frames checkpointed */ +); +</pre></blockquote> +<p> +The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint +operation on database X of <a href="#sqlite3">database connection</a> D in mode M. Status +information is written back into integers pointed to by L and C. +The M parameter must be a valid <a href="#SQLITE_CHECKPOINT_FULL">checkpoint mode</a>:</p> + +<p><dl> +<dt>SQLITE_CHECKPOINT_PASSIVE<dd> +Checkpoint as many frames as possible without waiting for any database +readers or writers to finish, then sync the database file if all frames +in the log were checkpointed. The <a href="#sqlite3_busy_handler">busy-handler callback</a> +is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode. +On the other hand, passive mode might leave the checkpoint unfinished +if there are concurrent readers or writers.</p> + +<p><dt>SQLITE_CHECKPOINT_FULL<dd> +This mode blocks (it invokes the +<a href="#sqlite3_busy_handler">busy-handler callback</a>) until there is no +database writer and all readers are reading from the most recent database +snapshot. It then checkpoints all frames in the log file and syncs the +database file. This mode blocks new database writers while it is pending, +but new database readers are allowed to continue unimpeded.</p> + +<p><dt>SQLITE_CHECKPOINT_RESTART<dd> +This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition +that after checkpointing the log file it blocks (calls the +<a href="#sqlite3_busy_handler">busy-handler callback</a>) +until all readers are reading from the database file only. This ensures +that the next writer will restart the log file from the beginning. +Like SQLITE_CHECKPOINT_FULL, this mode blocks new +database writer attempts while it is pending, but does not impede readers.</p> + +<p><dt>SQLITE_CHECKPOINT_TRUNCATE<dd> +This mode works the same way as SQLITE_CHECKPOINT_RESTART with the +addition that it also truncates the log file to zero bytes just prior +to a successful return. +</dl></p> + +<p>If pnLog is not NULL, then *pnLog is set to the total number of frames in +the log file or to -1 if the checkpoint could not run because +of an error or because the database is not in <a href="wal.html">WAL mode</a>. If pnCkpt is not +NULL,then *pnCkpt is set to the total number of checkpointed frames in the +log file (including any that were already checkpointed before the function +was called) or to -1 if the checkpoint could not run due to an error or +because the database is not in WAL mode. Note that upon successful +completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been +truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.</p> + +<p>All calls obtain an exclusive "checkpoint" lock on the database file. If +any other process is running a checkpoint operation at the same time, the +lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a +busy-handler configured, it will not be invoked in this case.</p> + +<p>The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the +exclusive "writer" lock on the database file. If the writer lock cannot be +obtained immediately, and a busy-handler is configured, it is invoked and +the writer lock retried until either the busy-handler returns 0 or the lock +is successfully obtained. The busy-handler is also invoked while waiting for +database readers as described above. If the busy-handler returns 0 before +the writer lock is obtained or while waiting for database readers, the +checkpoint operation proceeds from that point in the same way as +SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible +without blocking any further. SQLITE_BUSY is returned in this case.</p> + +<p>If parameter zDb is NULL or points to a zero length string, then the +specified operation is attempted on all WAL databases <a href="lang_attach.html">attached</a> to +<a href="#sqlite3">database connection</a> db. In this case the +values written to output parameters *pnLog and *pnCkpt are undefined. If +an SQLITE_BUSY error is encountered when processing one or more of the +attached WAL databases, the operation is still attempted on any remaining +attached databases and SQLITE_BUSY is returned at the end. If any other +error occurs while processing an attached database, processing is abandoned +and the error code is returned to the caller immediately. If no error +(SQLITE_BUSY or otherwise) is encountered while processing the attached +databases, SQLITE_OK is returned.</p> + +<p>If database zDb is the name of an attached database that is not in WAL +mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If +zDb is not NULL (or a zero length string) and is not the name of any +attached database, SQLITE_ERROR is returned to the caller.</p> + +<p>Unless it returns SQLITE_MISUSE, +the sqlite3_wal_checkpoint_v2() interface +sets the error information that is queried by +<a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a>.</p> + +<p>The <a href="pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a> command can be used to invoke this interface +from SQL. +</p><hr><a name="sqlite3_wal_hook"></a> +<h2>Write-Ahead Log Commit Hook</h2> +</div> +<blockquote><pre> +void *sqlite3_wal_hook( + sqlite3*, + int(*)(void *,sqlite3*,const char*,int), + void* +); +</pre></blockquote> +<p> +The <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> function is used to register a callback that +is invoked each time data is committed to a database in wal mode.</p> + +<p>The callback is invoked by SQLite after the commit has taken place and +the associated write-lock on the database released, so the implementation +may read, write or <a href="wal.html#ckpt">checkpoint</a> the database as required.</p> + +<p>The first parameter passed to the callback function when it is invoked +is a copy of the third parameter passed to sqlite3_wal_hook() when +registering the callback. The second is a copy of the database handle. +The third parameter is the name of the database that was written to - +either "main" or the name of an <a href="lang_attach.html">ATTACH</a>-ed database. The fourth parameter +is the number of pages currently in the write-ahead log file, +including those that were just committed.</p> + +<p>The callback function should normally return <a href="#SQLITE_ABORT">SQLITE_OK</a>. If an error +code is returned, that error will propagate back up through the +SQLite code base to cause the statement that provoked the callback +to report an error, though the commit will have still occurred. If the +callback returns <a href="#SQLITE_ABORT">SQLITE_ROW</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>, or if it returns a value +that does not correspond to any valid SQLite error code, the results +are undefined.</p> + +<p>A single database handle may have at most a single write-ahead log callback +registered at one time. Calling <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> replaces any +previously registered write-ahead log callback. The return value is +a copy of the third parameter from the previous call, if any, or 0. +Note that the <a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint()</a> interface and the +<a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> both invoke <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> and will +overwrite any prior <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> settings. +</p><hr><a name="SQLITE_ABORT"></a> +<h2>Result Codes</h2> +</div> +<blockquote><pre> +#define SQLITE_OK 0 /* Successful result */ +/* beginning-of-error-codes */ +#define SQLITE_ERROR 1 /* Generic error */ +#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ +#define SQLITE_PERM 3 /* Access permission denied */ +#define SQLITE_ABORT 4 /* Callback routine requested an abort */ +#define SQLITE_BUSY 5 /* The database file is locked */ +#define SQLITE_LOCKED 6 /* A table in the database is locked */ +#define SQLITE_NOMEM 7 /* A malloc() failed */ +#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ +#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ +#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ +#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ +#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */ +#define SQLITE_FULL 13 /* Insertion failed because database is full */ +#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ +#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ +#define SQLITE_EMPTY 16 /* Internal use only */ +#define SQLITE_SCHEMA 17 /* The database schema changed */ +#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ +#define SQLITE_MISMATCH 20 /* Data type mismatch */ +#define SQLITE_MISUSE 21 /* Library used incorrectly */ +#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ +#define SQLITE_AUTH 23 /* Authorization denied */ +#define SQLITE_FORMAT 24 /* Not used */ +#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ +#define SQLITE_NOTADB 26 /* File opened that is not a database file */ +#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */ +#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */ +#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ +#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ +/* end-of-error-codes */ +</pre></blockquote> +<p> +Many SQLite functions return an integer result code from the set shown +here in order to indicate success or failure.</p> + +<p>New error codes may be added in future versions of SQLite.</p> + +<p>See also: <a href="#SQLITE_ABORT_ROLLBACK">extended result code definitions</a> +</p><hr><a name="SQLITE_ABORT_ROLLBACK"></a> +<h2>Extended Result Codes</h2> +</div> +<blockquote><pre> +#define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8)) +#define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8)) +#define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8)) +#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)) +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) +#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) +#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) +#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) +#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8)) +#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) +#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) +#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8)) +#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8)) +#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8)) +#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8)) +#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8)) +#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8)) +#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8)) +#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8)) +#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8)) +#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8)) +#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8)) +#define SQLITE_IOERR_DATA (SQLITE_IOERR | (32<<8)) +#define SQLITE_IOERR_CORRUPTFS (SQLITE_IOERR | (33<<8)) +#define SQLITE_IOERR_IN_PAGE (SQLITE_IOERR | (34<<8)) +#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) +#define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8)) +#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) +#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) +#define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY | (3<<8)) +#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) +#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) +#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) +#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) +#define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */ +#define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN | (6<<8)) +#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) +#define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8)) +#define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT | (3<<8)) +#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) +#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) +#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) +#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8)) +#define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8)) +#define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8)) +#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8)) +#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8)) +#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8)) +#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8)) +#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8)) +#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) +#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) +#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) +#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) +#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) +#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) +#define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8)) +#define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8)) +#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) +#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) +#define SQLITE_NOTICE_RBU (SQLITE_NOTICE | (3<<8)) +#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) +#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) +#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8)) +#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */ +</pre></blockquote> +<p> +In its default configuration, SQLite API routines return one of 30 integer +<a href="rescode.html">result codes</a>. However, experience has shown that many of +these result codes are too coarse-grained. They do not provide as +much information about problems as programmers might like. In an effort to +address this, newer versions of SQLite (version 3.3.8 2006-10-09 +and later) include +support for additional result codes that provide more detailed information +about errors. These <a href="rescode.html#extrc">extended result codes</a> are enabled or disabled +on a per database connection basis using the +<a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes()</a> API. Or, the extended code for +the most recent error can be obtained using +<a href="#sqlite3_errcode">sqlite3_extended_errcode()</a>. +</p><hr><a name="SQLITE_ACCESS_EXISTS"></a> +<h2>Flags for the xAccess VFS method</h2> +</div> +<blockquote><pre> +#define SQLITE_ACCESS_EXISTS 0 +#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */ +#define SQLITE_ACCESS_READ 2 /* Unused */ +</pre></blockquote> +<p> +These integer constants can be used as the third parameter to +the xAccess method of an <a href="#sqlite3_vfs">sqlite3_vfs</a> object. They determine +what kind of permissions the xAccess method is looking for. +With SQLITE_ACCESS_EXISTS, the xAccess method +simply checks whether the file exists. +With SQLITE_ACCESS_READWRITE, the xAccess method +checks whether the named directory is both readable and writable +(in other words, if files can be added, removed, and renamed within +the directory). +The SQLITE_ACCESS_READWRITE constant is currently used only by the +<a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a>, though this could change in a future +release of SQLite. +With SQLITE_ACCESS_READ, the xAccess method +checks whether the file is readable. The SQLITE_ACCESS_READ constant is +currently unused, though it might be used in a future release of +SQLite. +</p><hr><a name="SQLITE_ALTER_TABLE"></a> +<h2>Authorizer Action Codes</h2> +</div> +<blockquote><pre> +/******************************************* 3rd ************ 4th ***********/ +#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ +#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ +#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ +#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ +#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ +#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ +#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ +#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ +#define SQLITE_DELETE 9 /* Table Name NULL */ +#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ +#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ +#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ +#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ +#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ +#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ +#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ +#define SQLITE_DROP_VIEW 17 /* View Name NULL */ +#define SQLITE_INSERT 18 /* Table Name NULL */ +#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ +#define SQLITE_READ 20 /* Table Name Column Name */ +#define SQLITE_SELECT 21 /* NULL NULL */ +#define SQLITE_TRANSACTION 22 /* Operation NULL */ +#define SQLITE_UPDATE 23 /* Table Name Column Name */ +#define SQLITE_ATTACH 24 /* Filename NULL */ +#define SQLITE_DETACH 25 /* Database Name NULL */ +#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ +#define SQLITE_REINDEX 27 /* Index Name NULL */ +#define SQLITE_ANALYZE 28 /* Table Name NULL */ +#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ +#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ +#define SQLITE_FUNCTION 31 /* NULL Function Name */ +#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ +#define SQLITE_COPY 0 /* No longer used */ +#define SQLITE_RECURSIVE 33 /* NULL NULL */ +</pre></blockquote> +<p> +The <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> interface registers a callback function +that is invoked to authorize certain SQL statement actions. The +second parameter to the callback is an integer code that specifies +what action is being authorized. These are the integer action codes that +the authorizer callback may be passed.</p> + +<p>These action code values signify what kind of operation is to be +authorized. The 3rd and 4th parameters to the authorization +callback function will be parameters or NULL depending on which of these +codes is used as the second parameter. The 5th parameter to the +authorizer callback is the name of the database ("main", "temp", +etc.) if applicable. The 6th parameter to the authorizer callback +is the name of the inner-most trigger or view that is responsible for +the access attempt or NULL if this access attempt is directly from +top-level SQL code. +</p><hr><a name="SQLITE_ANY"></a> +<h2>Text Encodings</h2> +</div> +<blockquote><pre> +#define SQLITE_UTF8 1 /* IMP: R-37514-35566 */ +#define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */ +#define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */ +#define SQLITE_UTF16 4 /* Use native byte order */ +#define SQLITE_ANY 5 /* Deprecated */ +#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ +</pre></blockquote> +<p> +These constant define integer codes that represent the various +text encodings supported by SQLite. +</p><hr><a name="SQLITE_BLOB"></a> +<h2>Fundamental Datatypes</h2> +</div> +<blockquote><pre> +#define SQLITE_INTEGER 1 +#define SQLITE_FLOAT 2 +#define SQLITE_BLOB 4 +#define SQLITE_NULL 5 +#ifdef SQLITE_TEXT +# undef SQLITE_TEXT +#else +# define SQLITE_TEXT 3 +#endif +#define SQLITE3_TEXT 3 +</pre></blockquote> +<p> +Every value in SQLite has one of five fundamental datatypes:</p> + +<p><ul> +<li> 64-bit signed integer +<li> 64-bit IEEE floating point number +<li> string +<li> BLOB +<li> NULL +</ul></p> + +<p>These constants are codes for each of those types.</p> + +<p>Note that the SQLITE_TEXT constant was also used in SQLite version 2 +for a completely different meaning. Software that links against both +SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not +SQLITE_TEXT. +</p><hr><a name="SQLITE_CHECKPOINT_FULL"></a> +<h2>Checkpoint Mode Values</h2> +</div> +<blockquote><pre> +#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */ +#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */ +#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for readers */ +#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */ +</pre></blockquote> +<p> +These constants define all valid values for the "checkpoint mode" passed +as the third parameter to the <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a> interface. +See the <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a> documentation for details on the +meaning of each of these checkpoint modes. +</p><hr><a name="SQLITE_CONFIG_COVERING_INDEX_SCAN"></a> +<h2>Configuration Options</h2> +</div> +<blockquote><pre> +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */ +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ +/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ +#define SQLITE_CONFIG_PCACHE 14 /* no-op */ +#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ +#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ +#define SQLITE_CONFIG_URI 17 /* int */ +#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ +#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ +#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ +#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ +#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ +#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ +#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ +#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ +#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ +#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ +#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */ +#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */ +</pre></blockquote> +<p> +These constants are the available integer configuration options that +can be passed as the first argument to the <a href="#sqlite3_config">sqlite3_config()</a> interface.</p> + +<p>Most of the configuration options for sqlite3_config() +will only work if invoked prior to <a href="#sqlite3_initialize">sqlite3_initialize()</a> or after +<a href="#sqlite3_initialize">sqlite3_shutdown()</a>. The few exceptions to this rule are called +"anytime configuration options". +Calling <a href="#sqlite3_config">sqlite3_config()</a> with a first argument that is not an +anytime configuration option in between calls to <a href="#sqlite3_initialize">sqlite3_initialize()</a> and +<a href="#sqlite3_initialize">sqlite3_shutdown()</a> is a no-op that returns SQLITE_MISUSE.</p> + +<p>The set of anytime configuration options can change (by insertions +and/or deletions) from one release of SQLite to the next. +As of SQLite version 3.42.0, the complete set of anytime configuration +options is: +<ul> +<li> SQLITE_CONFIG_LOG +<li> SQLITE_CONFIG_PCACHE_HDRSZ +</ul></p> + +<p>New configuration options may be added in future releases of SQLite. +Existing configuration options might be discontinued. Applications +should check the return code from <a href="#sqlite3_config">sqlite3_config()</a> to make sure that +the call worked. The <a href="#sqlite3_config">sqlite3_config()</a> interface will return a +non-zero <a href="rescode.html">error code</a> if a discontinued or unsupported configuration option +is invoked.</p> + +<p><dl> +<a name="sqliteconfigsinglethread"></a> + <dt>SQLITE_CONFIG_SINGLETHREAD</dt> +<dd>There are no arguments to this option. This option sets the +<a href="threadsafe.html">threading mode</a> to Single-thread. In other words, it disables +all mutexing and puts SQLite into a mode where it can only be used +by a single thread. If SQLite is compiled with +the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then +it is not possible to change the <a href="threadsafe.html">threading mode</a> from its default +value of Single-thread and so <a href="#sqlite3_config">sqlite3_config()</a> will return +<a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the SQLITE_CONFIG_SINGLETHREAD +configuration option.</dd></p> + +<p><a name="sqliteconfigmultithread"></a> + <dt>SQLITE_CONFIG_MULTITHREAD</dt> +<dd>There are no arguments to this option. This option sets the +<a href="threadsafe.html">threading mode</a> to Multi-thread. In other words, it disables +mutexing on <a href="#sqlite3">database connection</a> and <a href="#sqlite3_stmt">prepared statement</a> objects. +The application is responsible for serializing access to +<a href="#sqlite3">database connections</a> and <a href="#sqlite3_stmt">prepared statements</a>. But other mutexes +are enabled so that SQLite will be safe to use in a multi-threaded +environment as long as no two threads attempt to use the same +<a href="#sqlite3">database connection</a> at the same time. If SQLite is compiled with +the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then +it is not possible to set the Multi-thread <a href="threadsafe.html">threading mode</a> and +<a href="#sqlite3_config">sqlite3_config()</a> will return <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the +SQLITE_CONFIG_MULTITHREAD configuration option.</dd></p> + +<p><a name="sqliteconfigserialized"></a> + <dt>SQLITE_CONFIG_SERIALIZED</dt> +<dd>There are no arguments to this option. This option sets the +<a href="threadsafe.html">threading mode</a> to Serialized. In other words, this option enables +all mutexes including the recursive +mutexes on <a href="#sqlite3">database connection</a> and <a href="#sqlite3_stmt">prepared statement</a> objects. +In this mode (which is the default when SQLite is compiled with +<a href="compile.html#threadsafe">SQLITE_THREADSAFE=1</a>) the SQLite library will itself serialize access +to <a href="#sqlite3">database connections</a> and <a href="#sqlite3_stmt">prepared statements</a> so that the +application is free to use the same <a href="#sqlite3">database connection</a> or the +same <a href="#sqlite3_stmt">prepared statement</a> in different threads at the same time. +If SQLite is compiled with +the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then +it is not possible to set the Serialized <a href="threadsafe.html">threading mode</a> and +<a href="#sqlite3_config">sqlite3_config()</a> will return <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the +SQLITE_CONFIG_SERIALIZED configuration option.</dd></p> + +<p><a name="sqliteconfigmalloc"></a> + <dt>SQLITE_CONFIG_MALLOC</dt> +<dd> The SQLITE_CONFIG_MALLOC option takes a single argument which is +a pointer to an instance of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure. +The argument specifies +alternative low-level memory allocation routines to be used in place of +the memory allocation routines built into SQLite. SQLite makes +its own private copy of the content of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure +before the <a href="#sqlite3_config">sqlite3_config()</a> call returns.</dd></p> + +<p><a name="sqliteconfiggetmalloc"></a> + <dt>SQLITE_CONFIG_GETMALLOC</dt> +<dd> The SQLITE_CONFIG_GETMALLOC option takes a single argument which +is a pointer to an instance of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure. +The <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> +structure is filled with the currently defined memory allocation routines. +This option can be used to overload the default memory allocation +routines with a wrapper that simulations memory allocation failure or +tracks memory usage, for example. </dd></p> + +<p><a name="sqliteconfigsmallmalloc"></a> + <dt>SQLITE_CONFIG_SMALL_MALLOC</dt> +<dd> The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of +type int, interpreted as a boolean, which if true provides a hint to +SQLite that it should avoid large memory allocations if possible. +SQLite will run faster if it is free to make large memory allocations, +but some application might prefer to run slower in exchange for +guarantees about memory fragmentation that are possible if large +allocations are avoided. This hint is normally off. +</dd></p> + +<p><a name="sqliteconfigmemstatus"></a> + <dt>SQLITE_CONFIG_MEMSTATUS</dt> +<dd> The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int, +interpreted as a boolean, which enables or disables the collection of +memory allocation statistics. When memory allocation statistics are +disabled, the following SQLite interfaces become non-operational: +<ul> +<li> <a href="#sqlite3_hard_heap_limit64">sqlite3_hard_heap_limit64()</a> +<li> <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> +<li> <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> +<li> <a href="#sqlite3_hard_heap_limit64">sqlite3_soft_heap_limit64()</a> +<li> <a href="#sqlite3_status">sqlite3_status64()</a> +</ul> +Memory allocation statistics are enabled by default unless SQLite is +compiled with <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a>=0 in which case memory +allocation statistics are disabled by default. +</dd></p> + +<p><a name="sqliteconfigscratch"></a> + <dt>SQLITE_CONFIG_SCRATCH</dt> +<dd> The SQLITE_CONFIG_SCRATCH option is no longer used. +</dd></p> + +<p><a name="sqliteconfigpagecache"></a> + <dt>SQLITE_CONFIG_PAGECACHE</dt> +<dd> The SQLITE_CONFIG_PAGECACHE option specifies a memory pool +that SQLite can use for the database page cache with the default page +cache implementation. +This configuration option is a no-op if an application-defined page +cache implementation is loaded using the <a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>. +There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to +8-byte aligned memory (pMem), the size of each page cache line (sz), +and the number of cache lines (N). +The sz argument should be the size of the largest database page +(a power of two between 512 and 65536) plus some extra bytes for each +page header. The number of extra bytes needed by the page header +can be determined using <a href="#sqliteconfigpcachehdrsz">SQLITE_CONFIG_PCACHE_HDRSZ</a>. +It is harmless, apart from the wasted memory, +for the sz parameter to be larger than necessary. The pMem +argument must be either a NULL pointer or a pointer to an 8-byte +aligned block of memory of at least sz*N bytes, otherwise +subsequent behavior is undefined. +When pMem is not NULL, SQLite will strive to use the memory provided +to satisfy page cache needs, falling back to <a href="#sqlite3_free">sqlite3_malloc()</a> if +a page cache line is larger than sz bytes or if all of the pMem buffer +is exhausted. +If pMem is NULL and N is non-zero, then each database connection +does an initial bulk allocation for page cache memory +from <a href="#sqlite3_free">sqlite3_malloc()</a> sufficient for N cache lines if N is positive or +of -1024*N bytes if N is negative, . If additional +page cache memory is needed beyond what is provided by the initial +allocation, then SQLite goes to <a href="#sqlite3_free">sqlite3_malloc()</a> separately for each +additional cache line. </dd></p> + +<p><a name="sqliteconfigheap"></a> + <dt>SQLITE_CONFIG_HEAP</dt> +<dd> The SQLITE_CONFIG_HEAP option specifies a static memory buffer +that SQLite will use for all of its dynamic memory allocation needs +beyond those provided for by <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>. +The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled +with either <a href="compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> or <a href="compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> and returns +<a href="#SQLITE_ABORT">SQLITE_ERROR</a> if invoked otherwise. +There are three arguments to SQLITE_CONFIG_HEAP: +An 8-byte aligned pointer to the memory, +the number of bytes in the memory buffer, and the minimum allocation size. +If the first pointer (the memory pointer) is NULL, then SQLite reverts +to using its default memory allocator (the system malloc() implementation), +undoing any prior invocation of <a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>. If the +memory pointer is not NULL then the alternative memory +allocator is engaged to handle all of SQLites memory allocation needs. +The first pointer (the memory pointer) must be aligned to an 8-byte +boundary or subsequent behavior of SQLite will be undefined. +The minimum allocation size is capped at 2**12. Reasonable values +for the minimum allocation size are 2**5 through 2**8.</dd></p> + +<p><a name="sqliteconfigmutex"></a> + <dt>SQLITE_CONFIG_MUTEX</dt> +<dd> The SQLITE_CONFIG_MUTEX option takes a single argument which is a +pointer to an instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure. +The argument specifies alternative low-level mutex routines to be used +in place the mutex routines built into SQLite. SQLite makes a copy of +the content of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure before the call to +<a href="#sqlite3_config">sqlite3_config()</a> returns. If SQLite is compiled with +the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then +the entire mutexing subsystem is omitted from the build and hence calls to +<a href="#sqlite3_config">sqlite3_config()</a> with the SQLITE_CONFIG_MUTEX configuration option will +return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</dd></p> + +<p><a name="sqliteconfiggetmutex"></a> + <dt>SQLITE_CONFIG_GETMUTEX</dt> +<dd> The SQLITE_CONFIG_GETMUTEX option takes a single argument which +is a pointer to an instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure. The +<a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> +structure is filled with the currently defined mutex routines. +This option can be used to overload the default mutex allocation +routines with a wrapper used to track mutex usage for performance +profiling or testing, for example. If SQLite is compiled with +the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then +the entire mutexing subsystem is omitted from the build and hence calls to +<a href="#sqlite3_config">sqlite3_config()</a> with the SQLITE_CONFIG_GETMUTEX configuration option will +return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</dd></p> + +<p><a name="sqliteconfiglookaside"></a> + <dt>SQLITE_CONFIG_LOOKASIDE</dt> +<dd> The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine +the default size of lookaside memory on each <a href="#sqlite3">database connection</a>. +The first argument is the +size of each lookaside buffer slot and the second is the number of +slots allocated to each database connection. SQLITE_CONFIG_LOOKASIDE +sets the <i>default</i> lookaside size. The <a href="#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a> +option to <a href="#sqlite3_db_config">sqlite3_db_config()</a> can be used to change the lookaside +configuration on individual connections. </dd></p> + +<p><a name="sqliteconfigpcache2"></a> + <dt>SQLITE_CONFIG_PCACHE2</dt> +<dd> The SQLITE_CONFIG_PCACHE2 option takes a single argument which is +a pointer to an <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object. This object specifies +the interface to a custom page cache implementation. +SQLite makes a copy of the <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object.</dd></p> + +<p><a name="sqliteconfiggetpcache2"></a> + <dt>SQLITE_CONFIG_GETPCACHE2</dt> +<dd> The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which +is a pointer to an <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object. SQLite copies of +the current page cache implementation into that object. </dd></p> + +<p><a name="sqliteconfiglog"></a> + <dt>SQLITE_CONFIG_LOG</dt> +<dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite +global <a href="errlog.html">error log</a>. +(The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a +function with a call signature of void(*)(void*,int,const char*), +and a pointer to void. If the function pointer is not NULL, it is +invoked by <a href="#sqlite3_log">sqlite3_log()</a> to process each logging event. If the +function pointer is NULL, the <a href="#sqlite3_log">sqlite3_log()</a> interface becomes a no-op. +The void pointer that is the second argument to SQLITE_CONFIG_LOG is +passed through as the first parameter to the application-defined logger +function whenever that function is invoked. The second parameter to +the logger function is a copy of the first parameter to the corresponding +<a href="#sqlite3_log">sqlite3_log()</a> call and is intended to be a <a href="rescode.html">result code</a> or an +<a href="rescode.html#extrc">extended result code</a>. The third parameter passed to the logger is +log message after formatting via <a href="#sqlite3_mprintf">sqlite3_snprintf()</a>. +The SQLite logging interface is not reentrant; the logger function +supplied by the application must not invoke any SQLite interface. +In a multi-threaded application, the application-defined logger +function must be threadsafe. </dd></p> + +<p><a name="sqliteconfiguri"></a> + <dt>SQLITE_CONFIG_URI +<dd>The SQLITE_CONFIG_URI option takes a single argument of type int. +If non-zero, then URI handling is globally enabled. If the parameter is zero, +then URI handling is globally disabled. If URI handling is globally +enabled, all filenames passed to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a>, +<a href="#sqlite3_open">sqlite3_open16()</a> or +specified as part of <a href="lang_attach.html">ATTACH</a> commands are interpreted as URIs, regardless +of whether or not the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flag is set when the database +connection is opened. If it is globally disabled, filenames are +only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the +database connection is opened. By default, URI handling is globally +disabled. The default value may be changed by compiling with the +<a href="compile.html#use_uri">SQLITE_USE_URI</a> symbol defined.</p> + +<p><a name="sqliteconfigcoveringindexscan"></a> + <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN +<dd>The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer +argument which is interpreted as a boolean in order to enable or disable +the use of covering indices for full table scans in the query optimizer. +The default setting is determined +by the <a href="compile.html#allow_covering_index_scan">SQLITE_ALLOW_COVERING_INDEX_SCAN</a> compile-time option, or is "on" +if that compile-time option is omitted. +The ability to disable the use of covering indices for full table scans +is because some incorrectly coded legacy applications might malfunction +when the optimization is enabled. Providing the ability to +disable the optimization allows the older, buggy application code to work +without change even with newer versions of SQLite.</p> + +<p><a name="sqliteconfigpcache"></a> + <a name="sqliteconfiggetpcache"></a> + +<dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE +<dd> These options are obsolete and should not be used by new code. +They are retained for backwards compatibility but are now no-ops. +</dd></p> + +<p><a name="sqliteconfigsqllog"></a> + +<dt>SQLITE_CONFIG_SQLLOG +<dd>This option is only available if sqlite is compiled with the +<a href="compile.html#enable_sqllog">SQLITE_ENABLE_SQLLOG</a> pre-processor macro defined. The first argument should +be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int). +The second should be of type (void*). The callback is invoked by the library +in three separate circumstances, identified by the value passed as the +fourth parameter. If the fourth parameter is 0, then the database connection +passed as the second argument has just been opened. The third argument +points to a buffer containing the name of the main database file. If the +fourth parameter is 1, then the SQL statement that the third parameter +points to has just been executed. Or, if the fourth parameter is 2, then +the connection being passed as the second parameter is being closed. The +third parameter is passed NULL In this case. An example of using this +configuration option can be seen in the "test_sqllog.c" source file in +the canonical SQLite source tree.</dd></p> + +<p><a name="sqliteconfigmmapsize"></a> + +<dt>SQLITE_CONFIG_MMAP_SIZE +<dd>SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values +that are the default mmap size limit (the default setting for +<a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>) and the maximum allowed mmap size limit. +The default setting can be overridden by each database connection using +either the <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a> command, or by using the +<a href="#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control. The maximum allowed mmap size +will be silently truncated if necessary so that it does not exceed the +compile-time maximum mmap size set by the +<a href="compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> compile-time option. +If either argument to this option is negative, then that argument is +changed to its compile-time default.</p> + +<p><a name="sqliteconfigwin32heapsize"></a> + +<dt>SQLITE_CONFIG_WIN32_HEAPSIZE +<dd>The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is +compiled for Windows with the <a href="compile.html#win32_malloc">SQLITE_WIN32_MALLOC</a> pre-processor macro +defined. SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value +that specifies the maximum size of the created heap.</p> + +<p><a name="sqliteconfigpcachehdrsz"></a> + +<dt>SQLITE_CONFIG_PCACHE_HDRSZ +<dd>The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which +is a pointer to an integer and writes into that integer the number of extra +bytes per page required for each page in <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>. +The amount of extra space required can change depending on the compiler, +target platform, and SQLite version.</p> + +<p><a name="sqliteconfigpmasz"></a> + +<dt>SQLITE_CONFIG_PMASZ +<dd>The SQLITE_CONFIG_PMASZ option takes a single parameter which +is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded +sorter to that integer. The default minimum PMA Size is set by the +<a href="compile.html#sorter_pmasz">SQLITE_SORTER_PMASZ</a> compile-time option. New threads are launched +to help with sort operations when multithreaded sorting +is enabled (using the <a href="pragma.html#pragma_threads">PRAGMA threads</a> command) and the amount of content +to be sorted exceeds the page size times the minimum of the +<a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a> setting and this value.</p> + +<p><a name="sqliteconfigstmtjrnlspill"></a> + +<dt>SQLITE_CONFIG_STMTJRNL_SPILL +<dd>The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which +becomes the <a href="tempfiles.html#stmtjrnl">statement journal</a> spill-to-disk threshold. +<a href="tempfiles.html#stmtjrnl">Statement journals</a> are held in memory until their size (in bytes) +exceeds this threshold, at which point they are written to disk. +Or if the threshold is -1, statement journals are always held +exclusively in memory. +Since many statement journals never become large, setting the spill +threshold to a value such as 64KiB can greatly reduce the amount of +I/O required to support statement rollback. +The default value for this setting is controlled by the +<a href="compile.html#stmtjrnl_spill">SQLITE_STMTJRNL_SPILL</a> compile-time option.</p> + +<p><a name="sqliteconfigsorterrefsize"></a> + +<dt>SQLITE_CONFIG_SORTERREF_SIZE +<dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter +of type (int) - the new value of the sorter-reference size threshold. +Usually, when SQLite uses an external sort to order records according +to an ORDER BY clause, all fields required by the caller are present in the +sorted records. However, if SQLite determines based on the declared type +of a table column that its values are likely to be very large - larger +than the configured sorter-reference size threshold - then a reference +is stored in each sorted record and the required column values loaded +from the database as records are returned in sorted order. The default +value for this option is to never use this optimization. Specifying a +negative value for this option restores the default behavior. +This option is only available if SQLite is compiled with the +<a href="compile.html#enable_sorter_references">SQLITE_ENABLE_SORTER_REFERENCES</a> compile-time option.</p> + +<p><a name="sqliteconfigmemdbmaxsize"></a> + +<dt>SQLITE_CONFIG_MEMDB_MAXSIZE +<dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter +<a href="#sqlite3_int64">sqlite3_int64</a> parameter which is the default maximum size for an in-memory +database created using <a href="#sqlite3_deserialize">sqlite3_deserialize()</a>. This default maximum +size can be adjusted up or down for individual databases using the +<a href="#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> <a href="#sqlite3_file_control">file-control</a>. If this +configuration setting is never used, then the default maximum is determined +by the <a href="compile.html#memdb_default_maxsize">SQLITE_MEMDB_DEFAULT_MAXSIZE</a> compile-time option. If that +compile-time option is not set, then the default maximum is 1073741824. +</dl> +</p><hr><a name="SQLITE_DBCONFIG_DEFENSIVE"></a> +<h2>Database Connection Configuration Options</h2> +</div> +<blockquote><pre> +#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ +#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ +#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ +#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ +#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */ +#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */ +#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */ +#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */ +#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */ +#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */ +#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */ +#define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */ +#define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */ +#define SQLITE_DBCONFIG_MAX 1019 /* Largest DBCONFIG */ +</pre></blockquote> +<p> +These constants are the available integer configuration options that +can be passed as the second argument to the <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface.</p> + +<p>New configuration options may be added in future releases of SQLite. +Existing configuration options might be discontinued. Applications +should check the return code from <a href="#sqlite3_db_config">sqlite3_db_config()</a> to make sure that +the call worked. The <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface will return a +non-zero <a href="rescode.html">error code</a> if a discontinued or unsupported configuration option +is invoked.</p> + +<p><dl> +<a name="sqlitedbconfiglookaside"></a> + +<dt>SQLITE_DBCONFIG_LOOKASIDE</dt> +<dd> This option takes three additional arguments that determine the +<a href="malloc.html#lookaside">lookaside memory allocator</a> configuration for the <a href="#sqlite3">database connection</a>. +The first argument (the third parameter to <a href="#sqlite3_db_config">sqlite3_db_config()</a> is a +pointer to a memory buffer to use for lookaside memory. +The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb +may be NULL in which case SQLite will allocate the +lookaside buffer itself using <a href="#sqlite3_free">sqlite3_malloc()</a>. The second argument is the +size of each lookaside buffer slot. 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. The buffer +must be aligned to an 8-byte boundary. If the second argument to +SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally +rounded down to the next smaller multiple of 8. The lookaside memory +configuration for a database connection can only be changed when that +connection is not currently using lookaside memory, or in other words +when the "current value" returned by +<a href="#sqlite3_db_status">sqlite3_db_status</a>(D,<a href="#sqlitedbstatuslookasideused">SQLITE_DBSTATUS_LOOKASIDE_USED</a>,...) is zero. +Any attempt to change the lookaside memory configuration when lookaside +memory is in use leaves the configuration unchanged and returns +<a href="#SQLITE_ABORT">SQLITE_BUSY</a>.</dd></p> + +<p><a name="sqlitedbconfigenablefkey"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt> +<dd> This option is used to enable or disable the enforcement of +<a href="foreignkeys.html">foreign key constraints</a>. There should be two additional arguments. +The first argument is an integer which is 0 to disable FK enforcement, +positive to enable FK enforcement or negative to leave FK enforcement +unchanged. The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether FK enforcement is off or on +following this call. The second parameter may be a NULL pointer, in +which case the FK enforcement setting is not reported back. </dd></p> + +<p><a name="sqlitedbconfigenabletrigger"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> +<dd> This option is used to enable or disable <a href="lang_createtrigger.html">triggers</a>. +There should be two additional arguments. +The first argument is an integer which is 0 to disable triggers, +positive to enable triggers or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether triggers are disabled or enabled +following this call. The second parameter may be a NULL pointer, in +which case the trigger setting is not reported back.</p> + +<p><p>Originally this option disabled all triggers. However, since +SQLite version 3.35.0, TEMP triggers are still allowed even if +this option is off. So, in other words, this option now only disables +triggers in the main database schema or in the schemas of ATTACH-ed +databases. </dd></p> + +<p><a name="sqlitedbconfigenableview"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt> +<dd> This option is used to enable or disable <a href="lang_createview.html">views</a>. +There should be two additional arguments. +The first argument is an integer which is 0 to disable views, +positive to enable views or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether views are disabled or enabled +following this call. The second parameter may be a NULL pointer, in +which case the view setting is not reported back.</p> + +<p><p>Originally this option disabled all views. However, since +SQLite version 3.35.0, TEMP views are still allowed even if +this option is off. So, in other words, this option now only disables +views in the main database schema or in the schemas of ATTACH-ed +databases. </dd></p> + +<p><a name="sqlitedbconfigenablefts3tokenizer"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> +<dd> This option is used to enable or disable the +<a href="fts3.html#f3tknzr">fts3_tokenizer()</a> function which is part of the +<a href="fts3.html">FTS3</a> full-text search engine extension. +There should be two additional arguments. +The first argument is an integer which is 0 to disable fts3_tokenizer() or +positive to enable fts3_tokenizer() or negative to leave the setting +unchanged. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled +following this call. The second parameter may be a NULL pointer, in +which case the new setting is not reported back. </dd></p> + +<p><a name="sqlitedbconfigenableloadextension"></a> + +<dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> +<dd> This option is used to enable or disable the <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> +interface independently of the <a href="lang_corefunc.html#load_extension">load_extension()</a> SQL function. +The <a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> API enables or disables both the +C-API <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> and the SQL function <a href="lang_corefunc.html#load_extension">load_extension()</a>. +There should be two additional arguments. +When the first argument to this interface is 1, then only the C-API is +enabled and the SQL function remains disabled. If the first argument to +this interface is 0, then both the C-API and the SQL function are disabled. +If the first argument is -1, then no changes are made to state of either the +C-API or the SQL function. +The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> interface +is disabled or enabled following this call. The second parameter may +be a NULL pointer, in which case the new setting is not reported back. +</dd></p> + +<p><a name="sqlitedbconfigmaindbname"></a> + <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> +<dd> This option is used to change the name of the "main" database +schema. The sole argument is a pointer to a constant UTF8 string +which will become the new schema name in place of "main". SQLite +does not make a copy of the new main schema name string, so the application +must ensure that the argument passed into this DBCONFIG option is unchanged +until after the database connection closes. +</dd></p> + +<p><a name="sqlitedbconfignockptonclose"></a> + +<dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> +<dd> Usually, when a database in wal mode is closed or detached from a +database handle, SQLite checks if this will mean that there are now no +connections at all to the database. If so, it performs a checkpoint +operation before closing the connection. This option may be used to +override this behavior. The first parameter passed to this operation +is an integer - positive to disable checkpoints-on-close, or zero (the +default) to enable them, and negative to leave the setting unchanged. +The second parameter is a pointer to an integer +into which is written 0 or 1 to indicate whether checkpoints-on-close +have been disabled - 0 if they are not disabled, 1 if they are. +</dd></p> + +<p><a name="sqlitedbconfigenableqpsg"></a> + <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt> +<dd>The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates +the <a href="queryplanner-ng.html#qpstab">query planner stability guarantee</a> (QPSG). When the QPSG is active, +a single SQL query statement will always use the same algorithm regardless +of values of <a href="lang_expr.html#varparam">bound parameters</a>. The QPSG disables some query optimizations +that look at the values of bound parameters, which can make some queries +slower. But the QPSG has the advantage of more predictable behavior. With +the QPSG active, SQLite will always use the same query plan in the field as +was used during testing in the lab. +The first argument to this setting is an integer which is 0 to disable +the QPSG, positive to enable QPSG, or negative to leave the setting +unchanged. The second parameter is a pointer to an integer into which +is written 0 or 1 to indicate whether the QPSG is disabled or enabled +following this call. +</dd></p> + +<p><a name="sqlitedbconfigtriggereqp"></a> + <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt> +<dd> By default, the output of EXPLAIN QUERY PLAN commands does not +include output for any operations performed by trigger programs. This +option is used to set or clear (the default) a flag that governs this +behavior. The first parameter passed to this operation is an integer - +positive to enable output for trigger programs, or zero to disable it, +or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether output-for-triggers has been disabled - 0 if +it is not disabled, 1 if it is. +</dd></p> + +<p><a name="sqlitedbconfigresetdatabase"></a> + <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt> +<dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run +<a href="lang_vacuum.html">VACUUM</a> in order to reset a database back to an empty database +with no schema and no content. The following process works even for +a badly corrupted database file: +<ol> +<li> If the database connection is newly opened, make sure it has read the +database schema by preparing then discarding some query against the +database, or calling sqlite3_table_column_metadata(), ignoring any +errors. This step is only necessary if the application desires to keep +the database in WAL mode after the reset if it was in WAL mode before +the reset. +<li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); +<li> <a href="#sqlite3_exec">sqlite3_exec</a>(db, "<a href="lang_vacuum.html">VACUUM</a>", 0, 0, 0); +<li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); +</ol> +Because resetting a database is destructive and irreversible, the +process requires the use of this obscure API and multiple steps to +help ensure that it does not happen by accident. Because this +feature must be capable of resetting corrupt databases, and +shutting down virtual tables may require access to that corrupt +storage, the library must abandon any installed virtual tables +without calling their xDestroy() methods.</p> + +<p><a name="sqlitedbconfigdefensive"></a> + <dt>SQLITE_DBCONFIG_DEFENSIVE</dt> +<dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the +"defensive" flag for a database connection. When the defensive +flag is enabled, language features that allow ordinary SQL to +deliberately corrupt the database file are disabled. The disabled +features include but are not limited to the following: +<ul> +<li> The <a href="pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> statement. +<li> The <a href="pragma.html#pragma_journal_mode">PRAGMA journal_mode=OFF</a> statement. +<li> The <a href="pragma.html#pragma_schema_version">PRAGMA schema_version=N</a> statement. +<li> Writes to the <a href="dbpage.html">sqlite_dbpage</a> virtual table. +<li> Direct writes to <a href="vtab.html#xshadowname">shadow tables</a>. +</ul> +</dd></p> + +<p><a name="sqlitedbconfigwritableschema"></a> + <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt> +<dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the +"writable_schema" flag. This has the same effect and is logically equivalent +to setting <a href="pragma.html#pragma_writable_schema">PRAGMA writable_schema=ON</a> or <a href="pragma.html#pragma_writable_schema">PRAGMA writable_schema=OFF</a>. +The first argument to this setting is an integer which is 0 to disable +the writable_schema, positive to enable writable_schema, or negative to +leave the setting unchanged. The second parameter is a pointer to an +integer into which is written 0 or 1 to indicate whether the writable_schema +is enabled or disabled following this call. +</dd></p> + +<p><a name="sqlitedbconfiglegacyaltertable"></a> + +<dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt> +<dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates +the legacy behavior of the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME</a> command such it +behaves as it did prior to <a href="releaselog/3_24_0.html">version 3.24.0</a> (2018-06-04). See the +"Compatibility Notice" on the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME documentation</a> for +additional information. This feature can also be turned on and off +using the <a href="pragma.html#pragma_legacy_alter_table">PRAGMA legacy_alter_table</a> statement. +</dd></p> + +<p><a name="sqlitedbconfigdqsdml"></a> + +<dt>SQLITE_DBCONFIG_DQS_DML</dt> +<dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates +the legacy <a href="quirks.html#dblquote">double-quoted string literal</a> misfeature for DML statements +only, that is DELETE, INSERT, SELECT, and UPDATE statements. The +default value of this setting is determined by the <a href="compile.html#dqs">-DSQLITE_DQS</a> +compile-time option. +</dd></p> + +<p><a name="sqlitedbconfigdqsddl"></a> + +<dt>SQLITE_DBCONFIG_DQS_DDL</dt> +<dd>The SQLITE_DBCONFIG_DQS option activates or deactivates +the legacy <a href="quirks.html#dblquote">double-quoted string literal</a> misfeature for DDL statements, +such as CREATE TABLE and CREATE INDEX. The +default value of this setting is determined by the <a href="compile.html#dqs">-DSQLITE_DQS</a> +compile-time option. +</dd></p> + +<p><a name="sqlitedbconfigtrustedschema"></a> + +<dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</dt> +<dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to +assume that database schemas are untainted by malicious content. +When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite +takes additional defensive steps to protect the application from harm +including: +<ul> +<li> Prohibit the use of SQL functions inside triggers, views, +CHECK constraints, DEFAULT clauses, expression indexes, +partial indexes, or generated columns +unless those functions are tagged with <a href="#sqliteinnocuous">SQLITE_INNOCUOUS</a>. +<li> Prohibit the use of virtual tables inside of triggers or views +unless those virtual tables are tagged with <a href="#sqlitevtabinnocuous">SQLITE_VTAB_INNOCUOUS</a>. +</ul> +This setting defaults to "on" for legacy compatibility, however +all applications are advised to turn it off if possible. This setting +can also be controlled using the <a href="pragma.html#pragma_trusted_schema">PRAGMA trusted_schema</a> statement. +</dd></p> + +<p><a name="sqlitedbconfiglegacyfileformat"></a> + +<dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</dt> +<dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates +the legacy file format flag. When activated, this flag causes all newly +created database file to have a schema format version number (the 4-byte +integer found at offset 44 into the database header) of 1. This in turn +means that the resulting database file will be readable and writable by +any SQLite version back to 3.0.0 (2004-06-18). Without this setting, +newly created databases are generally not understandable by SQLite versions +prior to 3.3.0 (2006-01-11). As these words are written, there +is now scarcely any need to generate database files that are compatible +all the way back to version 3.0.0, and so this setting is of little +practical use, but is provided so that SQLite can continue to claim the +ability to generate new database files that are compatible with version +3.0.0. +<p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on, +the <a href="lang_vacuum.html">VACUUM</a> command will fail with an obscure error when attempting to +process a table with generated columns and a descending index. This is +not considered a bug since SQLite versions 3.3.0 and earlier do not support +either generated columns or descending indexes. +</dd></p> + +<p><a name="sqlitedbconfigstmtscanstatus"></a> + +<dt>SQLITE_DBCONFIG_STMT_SCANSTATUS</dt> +<dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in +SQLITE_ENABLE_STMT_SCANSTATUS builds. In this case, it sets or clears +a flag that enables collection of the sqlite3_stmt_scanstatus_v2() +statistics. For statistics to be collected, the flag must be set on +the database handle both when the SQL statement is prepared and when it +is stepped. The flag is set (collection of statistics is enabled) +by default. This option takes two arguments: an integer and a pointer to +an integer.. The first argument is 1, 0, or -1 to enable, disable, or +leave unchanged the statement scanstatus option. If the second argument +is not NULL, then the value of the statement scanstatus setting after +processing the first argument is written into the integer that the second +argument points to. +</dd></p> + +<p><a name="sqlitedbconfigreversescanorder"></a> + +<dt>SQLITE_DBCONFIG_REVERSE_SCANORDER</dt> +<dd>The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order +in which tables and indexes are scanned so that the scans start at the end +and work toward the beginning rather than starting at the beginning and +working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the +same as setting <a href="pragma.html#pragma_reverse_unordered_selects">PRAGMA reverse_unordered_selects</a>. This option takes +two arguments which are an integer and a pointer to an integer. The first +argument is 1, 0, or -1 to enable, disable, or leave unchanged the +reverse scan order flag, respectively. If the second argument is not NULL, +then 0 or 1 is written into the integer that the second argument points to +depending on if the reverse scan order flag is set after processing the +first argument. +</dd></p> + +<p></dl> +</p><hr><a name="SQLITE_DENY"></a> +<h2>Authorizer Return Codes</h2> +</div> +<blockquote><pre> +#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ +#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ +</pre></blockquote> +<p> +The <a href="#sqlite3_set_authorizer">authorizer callback function</a> must +return either <a href="#SQLITE_ABORT">SQLITE_OK</a> or one of these two constants in order +to signal SQLite whether or not the action is permitted. See the +<a href="#sqlite3_set_authorizer">authorizer documentation</a> for additional +information.</p> + +<p>Note that SQLITE_IGNORE is also used as a <a href="#SQLITE_FAIL">conflict resolution mode</a> +returned from the <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> interface. +</p><hr><a name="SQLITE_DESERIALIZE_FREEONCLOSE"></a> +<h2>Flags for sqlite3_deserialize()</h2> +</div> +<blockquote><pre> +#define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */ +#define SQLITE_DESERIALIZE_RESIZEABLE 2 /* Resize using sqlite3_realloc64() */ +#define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */ +</pre></blockquote> +<p> +The following are allowed values for 6th argument (the F argument) to +the <a href="#sqlite3_deserialize">sqlite3_deserialize(D,S,P,N,M,F)</a> interface.</p> + +<p>The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization +in the P argument is held in memory obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a> +and that SQLite should take ownership of this memory and automatically +free it when it has finished using it. Without this flag, the caller +is responsible for freeing any dynamically allocated memory.</p> + +<p>The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to +grow the size of the database using calls to <a href="#sqlite3_free">sqlite3_realloc64()</a>. This +flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used. +Without this flag, the deserialized database cannot increase in size beyond +the number of bytes specified by the M parameter.</p> + +<p>The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database +should be treated as read-only. +</p><hr><a name="SQLITE_DETERMINISTIC"></a> +<h2>Function Flags</h2> +</div> +<blockquote><pre> +#define SQLITE_DETERMINISTIC 0x000000800 +#define SQLITE_DIRECTONLY 0x000080000 +#define SQLITE_SUBTYPE 0x000100000 +#define SQLITE_INNOCUOUS 0x000200000 +#define SQLITE_RESULT_SUBTYPE 0x001000000 +</pre></blockquote> +<p> +These constants may be ORed together with the +<a href="#SQLITE_ANY">preferred text encoding</a> as the fourth argument +to <a href="#sqlite3_create_function">sqlite3_create_function()</a>, <a href="#sqlite3_create_function">sqlite3_create_function16()</a>, or +<a href="#sqlite3_create_function">sqlite3_create_function_v2()</a>.</p> + +<p><dl> +<a name="sqlitedeterministic"></a> + <dt>SQLITE_DETERMINISTIC</dt><dd> +The SQLITE_DETERMINISTIC flag means that the new function always gives +the same output when the input parameters are the same. +The <a href="lang_corefunc.html#abs">abs() function</a> is deterministic, for example, but +<a href="lang_corefunc.html#randomblob">randomblob()</a> is not. Functions must +be deterministic in order to be used in certain contexts such as +with the WHERE clause of <a href="partialindex.html">partial indexes</a> or in <a href="gencol.html">generated columns</a>. +SQLite might also optimize deterministic functions by factoring them +out of inner loops. +</dd></p> + +<p><a name="sqlitedirectonly"></a> + <dt>SQLITE_DIRECTONLY</dt><dd> +The SQLITE_DIRECTONLY flag means that the function may only be invoked +from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in +schema structures such as <a href="lang_createtable.html#ckconst">CHECK constraints</a>, <a href="lang_createtable.html#dfltval">DEFAULT clauses</a>, +<a href="expridx.html">expression indexes</a>, <a href="partialindex.html">partial indexes</a>, or <a href="gencol.html">generated columns</a>. +<p> +The SQLITE_DIRECTONLY flag is recommended for any +<a href="appfunc.html">application-defined SQL function</a> +that has side-effects or that could potentially leak sensitive information. +This will prevent attacks in which an application is tricked +into using a database file that has had its schema surreptitiously +modified to invoke the application-defined function in ways that are +harmful. +<p> +Some people say it is good practice to set SQLITE_DIRECTONLY on all +<a href="appfunc.html">application-defined SQL functions</a>, regardless of whether or not they +are security sensitive, as doing so prevents those functions from being used +inside of the database schema, and thus ensures that the database +can be inspected and modified using generic tools (such as the <a href="cli.html">CLI</a>) +that do not have access to the application-defined functions. +</dd></p> + +<p><a name="sqliteinnocuous"></a> + <dt>SQLITE_INNOCUOUS</dt><dd> +The SQLITE_INNOCUOUS flag means that the function is unlikely +to cause problems even if misused. An innocuous function should have +no side effects and should not depend on any values other than its +input parameters. The <a href="lang_corefunc.html#abs">abs() function</a> is an example of an +innocuous function. +The <a href="lang_corefunc.html#load_extension">load_extension() SQL function</a> is not innocuous because of its +side effects. +<p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not +exactly the same. The <a href="lang_corefunc.html#random">random() function</a> is an example of a +function that is innocuous but not deterministic. +<p>Some heightened security settings +(<a href="#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a> and <a href="pragma.html#pragma_trusted_schema">PRAGMA trusted_schema=OFF</a>) +disable the use of SQL functions inside views and triggers and in +schema structures such as <a href="lang_createtable.html#ckconst">CHECK constraints</a>, <a href="lang_createtable.html#dfltval">DEFAULT clauses</a>, +<a href="expridx.html">expression indexes</a>, <a href="partialindex.html">partial indexes</a>, and <a href="gencol.html">generated columns</a> unless +the function is tagged with SQLITE_INNOCUOUS. Most built-in functions +are innocuous. Developers are advised to avoid using the +SQLITE_INNOCUOUS flag for application-defined functions unless the +function has been carefully audited and found to be free of potentially +security-adverse side-effects and information-leaks. +</dd></p> + +<p><a name="sqlitesubtype"></a> + <dt>SQLITE_SUBTYPE</dt><dd> +The SQLITE_SUBTYPE flag indicates to SQLite that a function might call +<a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> to inspect the sub-types of its arguments. +This flag instructs SQLite to omit some corner-case optimizations that +might disrupt the operation of the <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> function, +causing it to return zero rather than the correct subtype(). +SQL functions that invokes <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> should have this +property. If the SQLITE_SUBTYPE property is omitted, then the return +value from <a href="#sqlite3_value_subtype">sqlite3_value_subtype()</a> might sometimes be zero even though +a non-zero subtype was specified by the function argument expression.</p> + +<p><a name="sqliteresultsubtype"></a> + <dt>SQLITE_RESULT_SUBTYPE</dt><dd> +The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call +<a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> to cause a sub-type to be associated with its +result. +Every function that invokes <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> should have this +property. If it does not, then the call to <a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> +might become a no-op if the function is used as term in an +<a href="expridx.html">expression index</a>. On the other hand, SQL functions that never invoke +<a href="#sqlite3_result_subtype">sqlite3_result_subtype()</a> should avoid setting this property, as the +purpose of this property is to disable certain optimizations that are +incompatible with subtypes. +</dd> +</dl> +</p><hr><a name="SQLITE_FAIL"></a> +<h2>Conflict resolution modes</h2> +</div> +<blockquote><pre> +#define SQLITE_ROLLBACK 1 +/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */ +#define SQLITE_FAIL 3 +/* #define SQLITE_ABORT 4 // Also an error code */ +#define SQLITE_REPLACE 5 +</pre></blockquote> +<p> +These constants are returned by <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> to +inform a <a href="vtab.html">virtual table</a> implementation what the <a href="lang_conflict.html">ON CONFLICT</a> mode +is for the SQL statement being evaluated.</p> + +<p>Note that the <a href="#SQLITE_DENY">SQLITE_IGNORE</a> constant is also used as a potential +return value from the <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> callback and that +<a href="#SQLITE_ABORT">SQLITE_ABORT</a> is also a <a href="rescode.html">result code</a>. +</p><hr><a name="SQLITE_FCNTL_BEGIN_ATOMIC_WRITE"></a> +<h2>Standard File Control Opcodes</h2> +</div> +<blockquote><pre> +#define SQLITE_FCNTL_LOCKSTATE 1 +#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2 +#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3 +#define SQLITE_FCNTL_LAST_ERRNO 4 +#define SQLITE_FCNTL_SIZE_HINT 5 +#define SQLITE_FCNTL_CHUNK_SIZE 6 +#define SQLITE_FCNTL_FILE_POINTER 7 +#define SQLITE_FCNTL_SYNC_OMITTED 8 +#define SQLITE_FCNTL_WIN32_AV_RETRY 9 +#define SQLITE_FCNTL_PERSIST_WAL 10 +#define SQLITE_FCNTL_OVERWRITE 11 +#define SQLITE_FCNTL_VFSNAME 12 +#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13 +#define SQLITE_FCNTL_PRAGMA 14 +#define SQLITE_FCNTL_BUSYHANDLER 15 +#define SQLITE_FCNTL_TEMPFILENAME 16 +#define SQLITE_FCNTL_MMAP_SIZE 18 +#define SQLITE_FCNTL_TRACE 19 +#define SQLITE_FCNTL_HAS_MOVED 20 +#define SQLITE_FCNTL_SYNC 21 +#define SQLITE_FCNTL_COMMIT_PHASETWO 22 +#define SQLITE_FCNTL_WIN32_SET_HANDLE 23 +#define SQLITE_FCNTL_WAL_BLOCK 24 +#define SQLITE_FCNTL_ZIPVFS 25 +#define SQLITE_FCNTL_RBU 26 +#define SQLITE_FCNTL_VFS_POINTER 27 +#define SQLITE_FCNTL_JOURNAL_POINTER 28 +#define SQLITE_FCNTL_WIN32_GET_HANDLE 29 +#define SQLITE_FCNTL_PDB 30 +#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31 +#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32 +#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33 +#define SQLITE_FCNTL_LOCK_TIMEOUT 34 +#define SQLITE_FCNTL_DATA_VERSION 35 +#define SQLITE_FCNTL_SIZE_LIMIT 36 +#define SQLITE_FCNTL_CKPT_DONE 37 +#define SQLITE_FCNTL_RESERVE_BYTES 38 +#define SQLITE_FCNTL_CKPT_START 39 +#define SQLITE_FCNTL_EXTERNAL_READER 40 +#define SQLITE_FCNTL_CKSM_FILE 41 +#define SQLITE_FCNTL_RESET_CACHE 42 +</pre></blockquote> +<p> +These integer constants are opcodes for the xFileControl method +of the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object and for the <a href="#sqlite3_file_control">sqlite3_file_control()</a> +interface.</p> + +<p><ul> +<li><a name="sqlitefcntllockstate"></a> + +The <a href="#sqlitefcntllockstate">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging. This +opcode causes the xFileControl method to write the current state of +the lock (one of <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>, <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>, +<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>, <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>) +into an integer that the pArg argument points to. +This capability is only available if SQLite is compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>.</p> + +<p><li><a name="sqlitefcntlsizehint"></a> + +The <a href="#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a> opcode is used by SQLite to give the VFS +layer a hint of how large the database file will grow to be during the +current transaction. This hint is not guaranteed to be accurate but it +is often close. The underlying VFS might choose to preallocate database +file space based on this hint in order to help writes to the database +file run faster.</p> + +<p><li><a name="sqlitefcntlsizelimit"></a> + +The <a href="#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> opcode is used by in-memory VFS that +implements <a href="#sqlite3_deserialize">sqlite3_deserialize()</a> to set an upper bound on the size +of the in-memory database. The argument is a pointer to a <a href="#sqlite3_int64">sqlite3_int64</a>. +If the integer pointed to is negative, then it is filled in with the +current limit. Otherwise the limit is set to the larger of the value +of the integer pointed to and the current database size. The integer +pointed to is set to the new limit.</p> + +<p><li><a name="sqlitefcntlchunksize"></a> + +The <a href="#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a> opcode is used to request that the VFS +extends and truncates the database file in chunks of a size specified +by the user. The fourth argument to <a href="#sqlite3_file_control">sqlite3_file_control()</a> should +point to an integer (type int) containing the new chunk-size to use +for the nominated database. Allocating database file space in large +chunks (say 1MB at a time), may reduce file-system fragmentation and +improve performance on some systems.</p> + +<p><li><a name="sqlitefcntlfilepointer"></a> + +The <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> opcode is used to obtain a pointer +to the <a href="#sqlite3_file">sqlite3_file</a> object associated with a particular database +connection. See also <a href="#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a>.</p> + +<p><li><a name="sqlitefcntljournalpointer"></a> + +The <a href="#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a> opcode is used to obtain a pointer +to the <a href="#sqlite3_file">sqlite3_file</a> object associated with the journal file (either +the <a href="lockingv3.html#rollback">rollback journal</a> or the <a href="wal.html">write-ahead log</a>) for a particular database +connection. See also <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a>.</p> + +<p><li><a name="sqlitefcntlsyncomitted"></a> + +No longer in use.</p> + +<p><li><a name="sqlitefcntlsync"></a> + +The <a href="#sqlitefcntlsync">SQLITE_FCNTL_SYNC</a> opcode is generated internally by SQLite and +sent to the VFS immediately before the xSync method is invoked on a +database file descriptor. Or, if the xSync method is not invoked +because the user has configured SQLite with +<a href="pragma.html#pragma_synchronous">PRAGMA synchronous=OFF</a> it is invoked in place +of the xSync method. In most cases, the pointer argument passed with +this file-control is NULL. However, if the database file is being synced +as part of a multi-database commit, the argument points to a nul-terminated +string containing the transactions super-journal file name. VFSes that +do not need this signal should silently ignore this opcode. Applications +should not call <a href="#sqlite3_file_control">sqlite3_file_control()</a> with this opcode as doing so may +disrupt the operation of the specialized VFSes that do require it.</p> + +<p><li><a name="sqlitefcntlcommitphasetwo"></a> + +The <a href="#sqlitefcntlcommitphasetwo">SQLITE_FCNTL_COMMIT_PHASETWO</a> opcode is generated internally by SQLite +and sent to the VFS after a transaction has been committed immediately +but before the database is unlocked. VFSes that do not need this signal +should silently ignore this opcode. Applications should not call +<a href="#sqlite3_file_control">sqlite3_file_control()</a> with this opcode as doing so may disrupt the +operation of the specialized VFSes that do require it.</p> + +<p><li><a name="sqlitefcntlwin32avretry"></a> + +The <a href="#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a> opcode is used to configure automatic +retry counts and intervals for certain disk I/O operations for the +windows <a href="vfs.html">VFS</a> in order to provide robustness in the presence of +anti-virus programs. By default, the windows VFS will retry file read, +file write, and file delete operations up to 10 times, with a delay +of 25 milliseconds before the first retry and with the delay increasing +by an additional 25 milliseconds with each subsequent retry. This +opcode allows these two values (10 retries and 25 milliseconds of delay) +to be adjusted. The values are changed for all database connections +within the same process. The argument is a pointer to an array of two +integers where the first integer is the new retry count and the second +integer is the delay. If either integer is negative, then the setting +is not changed but instead the prior value of that setting is written +into the array entry, allowing the current retry settings to be +interrogated. The zDbName parameter is ignored.</p> + +<p><li><a name="sqlitefcntlpersistwal"></a> + +The <a href="#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> opcode is used to set or query the +persistent <a href="wal.html">Write Ahead Log</a> setting. By default, the auxiliary +write ahead log (<a href="wal.html#walfile">WAL file</a>) and shared memory +files used for transaction control +are automatically deleted when the latest connection to the database +closes. Setting persistent WAL mode causes those files to persist after +close. Persisting the files is useful when other processes that do not +have write permission on the directory containing the database file want +to read the database file, as the WAL and shared memory files must exist +in order for the database to be readable. The fourth parameter to +<a href="#sqlite3_file_control">sqlite3_file_control()</a> for this opcode should be a pointer to an integer. +That integer is 0 to disable persistent WAL mode or 1 to enable persistent +WAL mode. If the integer is -1, then it is overwritten with the current +WAL persistence setting.</p> + +<p><li><a name="sqlitefcntlpowersafeoverwrite"></a> + +The <a href="#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a> opcode is used to set or query the +persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting +determines the <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> bit of the +xDeviceCharacteristics methods. The fourth parameter to +<a href="#sqlite3_file_control">sqlite3_file_control()</a> for this opcode should be a pointer to an integer. +That integer is 0 to disable zero-damage mode or 1 to enable zero-damage +mode. If the integer is -1, then it is overwritten with the current +zero-damage mode setting.</p> + +<p><li><a name="sqlitefcntloverwrite"></a> + +The <a href="#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a> opcode is invoked by SQLite after opening +a write transaction to indicate that, unless it is rolled back for some +reason, the entire database file will be overwritten by the current +transaction. This is used by VACUUM operations.</p> + +<p><li><a name="sqlitefcntlvfsname"></a> + +The <a href="#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a> opcode can be used to obtain the names of +all <a href="vfs.html">VFSes</a> in the VFS stack. The names are of all VFS shims and the +final bottom-level VFS are written into memory obtained from +<a href="#sqlite3_free">sqlite3_malloc()</a> and the result is stored in the char* variable +that the fourth parameter of <a href="#sqlite3_file_control">sqlite3_file_control()</a> points to. +The caller is responsible for freeing the memory when done. As with +all file-control actions, there is no guarantee that this will actually +do anything. Callers should initialize the char* variable to a NULL +pointer in case this file-control is not implemented. This file-control +is intended for diagnostic use only.</p> + +<p><li><a name="sqlitefcntlvfspointer"></a> + +The <a href="#sqlitefcntlvfspointer">SQLITE_FCNTL_VFS_POINTER</a> opcode finds a pointer to the top-level +<a href="vfs.html">VFSes</a> currently in use. The argument X in +sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be +of type "<a href="#sqlite3_vfs">sqlite3_vfs</a> **". This opcodes will set *X +to a pointer to the top-level VFS. +When there are multiple VFS shims in the stack, this opcode finds the +upper-most shim only.</p> + +<p><li><a name="sqlitefcntlpragma"></a> + +Whenever a <a href="pragma.html#syntax">PRAGMA</a> statement is parsed, an <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> +file control is sent to the open <a href="#sqlite3_file">sqlite3_file</a> object corresponding +to the database file to which the pragma statement refers. The argument +to the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control is an array of +pointers to strings (char**) in which the second element of the array +is the name of the pragma and the third element is the argument to the +pragma or NULL if the pragma has no argument. The handler for an +<a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control can optionally make the first element +of the char** argument point to a string obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a> +or the equivalent and that string will become the result of the pragma or +the error message if the pragma fails. If the +<a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>, then normal +<a href="pragma.html#syntax">PRAGMA</a> processing continues. If the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> +file control returns <a href="#SQLITE_ABORT">SQLITE_OK</a>, then the parser assumes that the +VFS has handled the PRAGMA itself and the parser generates a no-op +prepared statement if result string is NULL, or that returns a copy +of the result string if the string is non-NULL. +If the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns +any result code other than <a href="#SQLITE_ABORT">SQLITE_OK</a> or <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>, that means +that the VFS encountered an error while handling the <a href="pragma.html#syntax">PRAGMA</a> and the +compilation of the PRAGMA fails with an error. The <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> +file control occurs at the beginning of pragma statement analysis and so +it is able to override built-in <a href="pragma.html#syntax">PRAGMA</a> statements.</p> + +<p><li><a name="sqlitefcntlbusyhandler"></a> + +The <a href="#sqlitefcntlbusyhandler">SQLITE_FCNTL_BUSYHANDLER</a> +file-control may be invoked by SQLite on the database file handle +shortly after it is opened in order to provide a custom VFS with access +to the connection's busy-handler callback. The argument is of type (void**) +- an array of two (void *) values. The first (void *) actually points +to a function of type (int (*)(void *)). In order to invoke the connection's +busy-handler, this function should be invoked with the second (void *) in +the array as the only argument. If it returns non-zero, then the operation +should be retried. If it returns zero, the custom VFS should abandon the +current operation.</p> + +<p><li><a name="sqlitefcntltempfilename"></a> + +Applications can invoke the <a href="#sqlitefcntltempfilename">SQLITE_FCNTL_TEMPFILENAME</a> file-control +to have SQLite generate a +temporary filename using the same algorithm that is followed to generate +temporary filenames for TEMP tables and other internal uses. The +argument should be a char** which will be filled with the filename +written into memory obtained from <a href="#sqlite3_free">sqlite3_malloc()</a>. The caller should +invoke <a href="#sqlite3_free">sqlite3_free()</a> on the result to avoid a memory leak.</p> + +<p><li><a name="sqlitefcntlmmapsize"></a> + +The <a href="#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control is used to query or set the +maximum number of bytes that will be used for memory-mapped I/O. +The argument is a pointer to a value of type sqlite3_int64 that +is an advisory maximum number of bytes in the file to memory map. The +pointer is overwritten with the old value. The limit is not changed if +the value originally pointed to is negative, and so the current limit +can be queried by passing in a pointer to a negative number. This +file-control is used internally to implement <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>.</p> + +<p><li><a name="sqlitefcntltrace"></a> + +The <a href="#sqlitefcntltrace">SQLITE_FCNTL_TRACE</a> file control provides advisory information +to the VFS about what the higher layers of the SQLite stack are doing. +This file control is used by some VFS activity tracing <a href="vfs.html#shim">shims</a>. +The argument is a zero-terminated string. Higher layers in the +SQLite stack may generate instances of this file control if +the <a href="compile.html#use_fcntl_trace">SQLITE_USE_FCNTL_TRACE</a> compile-time option is enabled.</p> + +<p><li><a name="sqlitefcntlhasmoved"></a> + +The <a href="#sqlitefcntlhasmoved">SQLITE_FCNTL_HAS_MOVED</a> file control interprets its argument as a +pointer to an integer and it writes a boolean into that integer depending +on whether or not the file has been renamed, moved, or deleted since it +was first opened.</p> + +<p><li><a name="sqlitefcntlwin32gethandle"></a> + +The <a href="#sqlitefcntlwin32gethandle">SQLITE_FCNTL_WIN32_GET_HANDLE</a> opcode can be used to obtain the +underlying native file handle associated with a file handle. This file +control interprets its argument as a pointer to a native file handle and +writes the resulting value there.</p> + +<p><li><a name="sqlitefcntlwin32sethandle"></a> + +The <a href="#sqlitefcntlwin32sethandle">SQLITE_FCNTL_WIN32_SET_HANDLE</a> opcode is used for debugging. This +opcode causes the xFileControl method to swap the file handle with the one +pointed to by the pArg argument. This capability is used during testing +and only needs to be supported when SQLITE_TEST is defined.</p> + +<p><li><a name="sqlitefcntlwalblock"></a> + +The <a href="#sqlitefcntlwalblock">SQLITE_FCNTL_WAL_BLOCK</a> is a signal to the VFS layer that it might +be advantageous to block on the next WAL lock if the lock is not immediately +available. The WAL subsystem issues this signal during rare +circumstances in order to fix a problem with priority inversion. +Applications should <em>not</em> use this file-control.</p> + +<p><li><a name="sqlitefcntlzipvfs"></a> + +The <a href="#sqlitefcntlzipvfs">SQLITE_FCNTL_ZIPVFS</a> opcode is implemented by zipvfs only. All other +VFS should return SQLITE_NOTFOUND for this opcode.</p> + +<p><li><a name="sqlitefcntlrbu"></a> + +The <a href="#sqlitefcntlrbu">SQLITE_FCNTL_RBU</a> opcode is implemented by the special VFS used by +the RBU extension only. All other VFS should return SQLITE_NOTFOUND for +this opcode.</p> + +<p><li><a name="sqlitefcntlbeginatomicwrite"></a> + +If the <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> opcode returns SQLITE_OK, then +the file descriptor is placed in "batch write mode", which +means all subsequent write operations will be deferred and done +atomically at the next <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a>. Systems +that do not support batch atomic writes will return SQLITE_NOTFOUND. +Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to +the closing <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> or +<a href="#sqlitefcntlrollbackatomicwrite">SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a>, SQLite will make +no VFS interface calls on the same <a href="#sqlite3_file">sqlite3_file</a> file descriptor +except for calls to the xWrite method and the xFileControl method +with <a href="#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a>.</p> + +<p><li><a name="sqlitefcntlcommitatomicwrite"></a> + +The <a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> opcode causes all write +operations since the previous successful call to +<a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> to be performed atomically. +This file control returns <a href="#SQLITE_ABORT">SQLITE_OK</a> if and only if the writes were +all performed successfully and have been committed to persistent storage. +Regardless of whether or not it is successful, this file control takes +the file descriptor out of batch write mode so that all subsequent +write operations are independent. +SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without +a prior successful call to <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a>.</p> + +<p><li><a name="sqlitefcntlrollbackatomicwrite"></a> + +The <a href="#sqlitefcntlrollbackatomicwrite">SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a> opcode causes all write +operations since the previous successful call to +<a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> to be rolled back. +This file control takes the file descriptor out of batch write mode +so that all subsequent write operations are independent. +SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without +a prior successful call to <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a>.</p> + +<p><li><a name="sqlitefcntllocktimeout"></a> + +The <a href="#sqlitefcntllocktimeout">SQLITE_FCNTL_LOCK_TIMEOUT</a> opcode is used to configure a VFS +to block for up to M milliseconds before failing when attempting to +obtain a file lock using the xLock or xShmLock methods of the VFS. +The parameter is a pointer to a 32-bit signed integer that contains +the value that M is to be set to. Before returning, the 32-bit signed +integer is overwritten with the previous value of M.</p> + +<p><li><a name="sqlitefcntldataversion"></a> + +The <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> opcode is used to detect changes to +a database file. The argument is a pointer to a 32-bit unsigned integer. +The "data version" for the pager is written into the pointer. The +"data version" changes whenever any change occurs to the corresponding +database file, either through SQL statements on the same database +connection or through transactions committed by separate database +connections possibly in other processes. The <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> +interface can be used to find if any database on the connection has changed, +but that interface responds to changes on TEMP as well as MAIN and does +not provide a mechanism to detect changes to MAIN only. Also, the +<a href="#sqlite3_total_changes">sqlite3_total_changes()</a> interface responds to internal changes only and +omits changes made by other database connections. The +<a href="pragma.html#pragma_data_version">PRAGMA data_version</a> command provides a mechanism to detect changes to +a single attached database that occur due to other database connections, +but omits changes implemented by the database connection on which it is +called. This file control is the only mechanism to detect changes that +happen either internally or externally and that are associated with +a particular attached database.</p> + +<p><li><a name="sqlitefcntlckptstart"></a> + +The <a href="#sqlitefcntlckptstart">SQLITE_FCNTL_CKPT_START</a> opcode is invoked from within a checkpoint +in wal mode before the client starts to copy pages from the wal +file to the database file.</p> + +<p><li><a name="sqlitefcntlckptdone"></a> + +The <a href="#sqlitefcntlckptdone">SQLITE_FCNTL_CKPT_DONE</a> opcode is invoked from within a checkpoint +in wal mode after the client has finished copying pages from the wal +file to the database file, but before the *-shm file is updated to +record the fact that the pages have been checkpointed.</p> + +<p><li><a name="sqlitefcntlexternalreader"></a> + +The EXPERIMENTAL <a href="#sqlitefcntlexternalreader">SQLITE_FCNTL_EXTERNAL_READER</a> opcode is used to detect +whether or not there is a database client in another process with a wal-mode +transaction open on the database or not. It is only available on unix.The +(void*) argument passed with this file-control should be a pointer to a +value of type (int). The integer value is set to 1 if the database is a wal +mode database and there exists at least one client in another process that +currently has an SQL transaction open on the database. It is set to 0 if +the database is not a wal-mode db, or if there is no such connection in any +other process. This opcode cannot be used to detect transactions opened +by clients within the current process, only within other processes.</p> + +<p><li><a name="sqlitefcntlcksmfile"></a> + +The <a href="#sqlitefcntlcksmfile">SQLITE_FCNTL_CKSM_FILE</a> opcode is for use internally by the +<a href="cksumvfs.html">checksum VFS shim</a> only.</p> + +<p><li><a name="sqlitefcntlresetcache"></a> + +If there is currently no transaction open on the database, and the +database is not a temp db, then the <a href="#sqlitefcntlresetcache">SQLITE_FCNTL_RESET_CACHE</a> file-control +purges the contents of the in-memory page cache. If there is an open +transaction, or if the db is a temp-db, this opcode is a no-op, not an error. +</ul> +</p><hr><a name="SQLITE_INDEX_CONSTRAINT_EQ"></a> +<h2>Virtual Table Constraint Operator Codes</h2> +</div> +<blockquote><pre> +#define SQLITE_INDEX_CONSTRAINT_EQ 2 +#define SQLITE_INDEX_CONSTRAINT_GT 4 +#define SQLITE_INDEX_CONSTRAINT_LE 8 +#define SQLITE_INDEX_CONSTRAINT_LT 16 +#define SQLITE_INDEX_CONSTRAINT_GE 32 +#define SQLITE_INDEX_CONSTRAINT_MATCH 64 +#define SQLITE_INDEX_CONSTRAINT_LIKE 65 +#define SQLITE_INDEX_CONSTRAINT_GLOB 66 +#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 +#define SQLITE_INDEX_CONSTRAINT_NE 68 +#define SQLITE_INDEX_CONSTRAINT_ISNOT 69 +#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 +#define SQLITE_INDEX_CONSTRAINT_ISNULL 71 +#define SQLITE_INDEX_CONSTRAINT_IS 72 +#define SQLITE_INDEX_CONSTRAINT_LIMIT 73 +#define SQLITE_INDEX_CONSTRAINT_OFFSET 74 +#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 +</pre></blockquote> +<p> +These macros define the allowed values for the +<a href="#sqlite3_index_info">sqlite3_index_info</a>.aConstraint[].op field. Each value represents +an operator that is part of a constraint term in the WHERE clause of +a query that uses a <a href="vtab.html">virtual table</a>.</p> + +<p>The left-hand operand of the operator is given by the corresponding +aConstraint[].iColumn field. An iColumn of -1 indicates the left-hand +operand is the rowid. +The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET +operators have no left-hand operand, and so for those operators the +corresponding aConstraint[].iColumn is meaningless and should not be +used.</p> + +<p>All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through +value 255 are reserved to represent functions that are overloaded +by the <a href="vtab.html#xfindfunction">xFindFunction method</a> of the virtual table +implementation.</p> + +<p>The right-hand operands for each constraint might be accessible using +the <a href="#sqlite3_vtab_rhs_value">sqlite3_vtab_rhs_value()</a> interface. Usually the right-hand +operand is only available if it appears as a single constant literal +in the input SQL. If the right-hand operand is another column or an +expression (even a constant expression) or a parameter, then the +sqlite3_vtab_rhs_value() probably will not be able to extract it. +The SQLITE_INDEX_CONSTRAINT_ISNULL and +SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand +and hence calls to sqlite3_vtab_rhs_value() for those operators will +always return SQLITE_NOTFOUND.</p> + +<p>The collating sequence to be used for comparison can be found using +the <a href="#sqlite3_vtab_collation">sqlite3_vtab_collation()</a> interface. For most real-world virtual +tables, the collating sequence of constraints does not matter (for example +because the constraints are numeric) and so the sqlite3_vtab_collation() +interface is not commonly needed. +</p><hr><a name="SQLITE_IOCAP_ATOMIC"></a> +<h2>Device Characteristics</h2> +</div> +<blockquote><pre> +#define SQLITE_IOCAP_ATOMIC 0x00000001 +#define SQLITE_IOCAP_ATOMIC512 0x00000002 +#define SQLITE_IOCAP_ATOMIC1K 0x00000004 +#define SQLITE_IOCAP_ATOMIC2K 0x00000008 +#define SQLITE_IOCAP_ATOMIC4K 0x00000010 +#define SQLITE_IOCAP_ATOMIC8K 0x00000020 +#define SQLITE_IOCAP_ATOMIC16K 0x00000040 +#define SQLITE_IOCAP_ATOMIC32K 0x00000080 +#define SQLITE_IOCAP_ATOMIC64K 0x00000100 +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 +#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 +#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 +#define SQLITE_IOCAP_IMMUTABLE 0x00002000 +#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000 +</pre></blockquote> +<p> +The xDeviceCharacteristics method of the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> +object returns an integer which is a vector of these +bit values expressing I/O characteristics of the mass storage +device that holds the file that the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> +refers to.</p> + +<p>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 +that when data is appended to a file, the data is appended +first then the size of the file is extended, never the other +way around. The SQLITE_IOCAP_SEQUENTIAL property means that +information is written to disk in the same order as calls +to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that +after reboot following a crash or power loss, the only bytes in a +file that were written at the application level might have changed +and that adjacent bytes, even bytes within the same sector are +guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN +flag indicates that a file cannot be deleted when open. The +SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on +read-only media and cannot be changed even by processes with +elevated privileges.</p> + +<p>The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying +filesystem supports doing multiple write operations atomically when those +write operations are bracketed by <a href="#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> and +<a href="#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a>. +</p><hr><a name="SQLITE_LOCK_EXCLUSIVE"></a> +<h2>File Locking Levels</h2> +</div> +<blockquote><pre> +#define SQLITE_LOCK_NONE 0 /* xUnlock() only */ +#define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */ +#define SQLITE_LOCK_RESERVED 2 /* xLock() only */ +#define SQLITE_LOCK_PENDING 3 /* xLock() only */ +#define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */ +</pre></blockquote> +<p> +SQLite uses one of these integer values as the second +argument to calls it makes to the xLock() and xUnlock() methods +of an <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object. These values are ordered from +lest restrictive to most restrictive.</p> + +<p>The argument to xLock() is always SHARED or higher. The argument to +xUnlock is either SHARED or NONE. +</p><hr><a name="SQLITE_MUTEX_FAST"></a> +<h2>Mutex Types</h2> +</div> +<blockquote><pre> +#define SQLITE_MUTEX_FAST 0 +#define SQLITE_MUTEX_RECURSIVE 1 +#define SQLITE_MUTEX_STATIC_MAIN 2 +#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ +#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ +#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ +#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */ +#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ +#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ +#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ +#define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ +#define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ +#define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ +#define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ +#define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ +#define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ +</pre></blockquote> +<p> +The <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> interface takes a single argument +which is one of these integer constants.</p> + +<p>The set of static mutexes may change from one SQLite release to the +next. Applications that override the built-in mutex logic must be +prepared to accommodate additional static mutexes. +</p><hr><a name="SQLITE_OPEN_AUTOPROXY"></a> +<h2>Flags For File Open Operations</h2> +</div> +<blockquote><pre> +#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */ +#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */ +#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */ +#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */ +#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */ +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */ +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */ +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */ +#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */ +#define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */ +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */ +#define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */ +</pre></blockquote> +<p> +These bit values are intended for use in the +3rd parameter to the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface and +in the 4th parameter to the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method.</p> + +<p>Only those flags marked as "Ok for sqlite3_open_v2()" may be +used as the third argument to the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface. +The other flags have historically been ignored by sqlite3_open_v2(), +though future versions of SQLite might change so that an error is +raised if any of the disallowed bits are passed into sqlite3_open_v2(). +Applications should not depend on the historical behavior.</p> + +<p>Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into +<a href="#sqlite3_open">sqlite3_open_v2()</a> does *not* cause the underlying database file +to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into +<a href="#sqlite3_open">sqlite3_open_v2()</a> has historically be a no-op and might become an +error in future versions of SQLite. +</p><hr><a name="SQLITE_PREPARE_NORMALIZE"></a> +<h2>Prepare Flags</h2> +</div> +<blockquote><pre> +#define SQLITE_PREPARE_PERSISTENT 0x01 +#define SQLITE_PREPARE_NORMALIZE 0x02 +#define SQLITE_PREPARE_NO_VTAB 0x04 +</pre></blockquote> +<p> +These constants define various flags that can be passed into +"prepFlags" parameter of the <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> and +<a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> interfaces.</p> + +<p>New flags may be added in future releases of SQLite.</p> + +<p><dl> +<a name="sqlitepreparepersistent"></a> + <dt>SQLITE_PREPARE_PERSISTENT</dt> +<dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner +that the prepared statement will be retained for a long time and +probably reused many times. Without this flag, <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> +and <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a> assume that the prepared statement will +be used just once or at most a few times and then destroyed using +<a href="#sqlite3_finalize">sqlite3_finalize()</a> relatively soon. The current implementation acts +on this hint by avoiding the use of <a href="malloc.html#lookaside">lookaside memory</a> so as not to +deplete the limited store of lookaside memory. Future versions of +SQLite may act on this hint differently.</p> + +<p><a name="sqlitepreparenormalize"></a> + <dt>SQLITE_PREPARE_NORMALIZE</dt> +<dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used +to be required for any prepared statement that wanted to use the +<a href="#sqlite3_expanded_sql">sqlite3_normalized_sql()</a> interface. However, the +<a href="#sqlite3_expanded_sql">sqlite3_normalized_sql()</a> interface is now available to all +prepared statements, regardless of whether or not they use this +flag.</p> + +<p><a name="sqlitepreparenovtab"></a> + <dt>SQLITE_PREPARE_NO_VTAB</dt> +<dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler +to return an error (error code SQLITE_ERROR) if the statement uses +any virtual tables. +</dl> +</p><hr><a name="SQLITE_SCANSTAT_COMPLEX"></a> +<h2>Prepared Statement Scan Status</h2> +</div> +<blockquote><pre> +#define SQLITE_SCANSTAT_COMPLEX 0x0001 +</pre></blockquote> +<p></p><hr><a name="SQLITE_SCANSTAT_EST"></a> +<h2>Prepared Statement Scan Status Opcodes</h2> +</div> +<blockquote><pre> +#define SQLITE_SCANSTAT_NLOOP 0 +#define SQLITE_SCANSTAT_NVISIT 1 +#define SQLITE_SCANSTAT_EST 2 +#define SQLITE_SCANSTAT_NAME 3 +#define SQLITE_SCANSTAT_EXPLAIN 4 +#define SQLITE_SCANSTAT_SELECTID 5 +#define SQLITE_SCANSTAT_PARENTID 6 +#define SQLITE_SCANSTAT_NCYCLE 7 +</pre></blockquote> +<p> +The following constants can be used for the T parameter to the +<a href="#sqlite3_stmt_scanstatus">sqlite3_stmt_scanstatus(S,X,T,V)</a> interface. Each constant designates a +different metric for sqlite3_stmt_scanstatus() to return.</p> + +<p>When the value returned to V is a string, space to hold that string is +managed by the prepared statement S and will be automatically freed when +S is finalized.</p> + +<p>Not all values are available for all query elements. When a value is +not available, the output variable is set to -1 if the value is numeric, +or to NULL if it is a string (SQLITE_SCANSTAT_NAME).</p> + +<p><dl> +<a name="sqlitescanstatnloop"></a> + <dt>SQLITE_SCANSTAT_NLOOP</dt> +<dd>The <a href="#sqlite3_int64">sqlite3_int64</a> variable pointed to by the V parameter will be +set to the total number of times that the X-th loop has run.</dd></p> + +<p><a name="sqlitescanstatnvisit"></a> + <dt>SQLITE_SCANSTAT_NVISIT</dt> +<dd>The <a href="#sqlite3_int64">sqlite3_int64</a> variable pointed to by the V parameter will be set +to the total number of rows examined by all iterations of the X-th loop.</dd></p> + +<p><a name="sqlitescanstatest"></a> + <dt>SQLITE_SCANSTAT_EST</dt> +<dd>The "double" variable pointed to by the V parameter will be set to the +query planner's estimate for the average number of rows output from each +iteration of the X-th loop. If the query planner's estimates was accurate, +then this value will approximate the quotient NVISIT/NLOOP and the +product of this value for all prior loops with the same SELECTID will +be the NLOOP value for the current loop.</p> + +<p><a name="sqlitescanstatname"></a> + <dt>SQLITE_SCANSTAT_NAME</dt> +<dd>The "const char *" variable pointed to by the V parameter will be set +to a zero-terminated UTF-8 string containing the name of the index or table +used for the X-th loop.</p> + +<p><a name="sqlitescanstatexplain"></a> + <dt>SQLITE_SCANSTAT_EXPLAIN</dt> +<dd>The "const char *" variable pointed to by the V parameter will be set +to a zero-terminated UTF-8 string containing the <a href="eqp.html">EXPLAIN QUERY PLAN</a> +description for the X-th loop.</p> + +<p><a name="sqlitescanstatselectid"></a> + <dt>SQLITE_SCANSTAT_SELECTID</dt> +<dd>The "int" variable pointed to by the V parameter will be set to the +id for the X-th query plan element. The id value is unique within the +statement. The select-id is the same value as is output in the first +column of an <a href="eqp.html">EXPLAIN QUERY PLAN</a> query.</p> + +<p><a name="sqlitescanstatparentid"></a> + <dt>SQLITE_SCANSTAT_PARENTID</dt> +<dd>The "int" variable pointed to by the V parameter will be set to the +the id of the parent of the current query element, if applicable, or +to zero if the query element has no parent. This is the same value as +returned in the second column of an <a href="eqp.html">EXPLAIN QUERY PLAN</a> query.</p> + +<p><a name="sqlitescanstatncycle"></a> + <dt>SQLITE_SCANSTAT_NCYCLE</dt> +<dd>The sqlite3_int64 output value is set to the number of cycles, +according to the processor time-stamp counter, that elapsed while the +query element was being processed. This value is not available for +all query elements - if it is unavailable the output variable is +set to -1. +</dl> +</p><hr><a name="SQLITE_SHM_EXCLUSIVE"></a> +<h2>Flags for the xShmLock VFS method</h2> +</div> +<blockquote><pre> +#define SQLITE_SHM_UNLOCK 1 +#define SQLITE_SHM_LOCK 2 +#define SQLITE_SHM_SHARED 4 +#define SQLITE_SHM_EXCLUSIVE 8 +</pre></blockquote> +<p> +These integer constants define the various locking operations +allowed by the xShmLock method of <a href="#sqlite3_io_methods">sqlite3_io_methods</a>. The +following are the only legal combinations of flags to the +xShmLock method:</p> + +<p><ul> +<li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED +<li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE +<li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED +<li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE +</ul></p> + +<p>When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as +was given on the corresponding lock.</p> + +<p>The xShmLock method can transition between unlocked and SHARED or +between unlocked and EXCLUSIVE. It cannot transition between SHARED +and EXCLUSIVE. +</p><hr><a name="SQLITE_SOURCE_ID"></a> +<h2>Compile-Time Library Version Numbers</h2> +</div> +<blockquote><pre> +#define SQLITE_VERSION "3.45.1" +#define SQLITE_VERSION_NUMBER 3045001 +#define SQLITE_SOURCE_ID "2024-01-30 16:01:20 e876e51a0ed5c5b3126f52e532044363a014bc594cfefa87ffb5b82257cc467a" +</pre></blockquote> +<p> +The <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a> C preprocessor macro in the sqlite3.h header +evaluates to a string literal that is the SQLite version in the +format "X.Y.Z" where X is the major version number (always 3 for +SQLite3) and Y is the minor version number and Z is the release number. +The <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a> C preprocessor macro resolves to an integer +with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same +numbers used in <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a>. +The SQLITE_VERSION_NUMBER for any given release of SQLite will also +be larger than the release from which it is derived. Either Y will +be held constant and Z will be incremented or else Y will be incremented +and Z will be reset to zero.</p> + +<p>Since <a href="releaselog/3_6_18.html">version 3.6.18</a> (2009-09-11), +SQLite source code has been stored in the +<a href="http://www.fossil-scm.org/">Fossil configuration management +system</a>. The SQLITE_SOURCE_ID macro evaluates to +a string which identifies a particular check-in of SQLite +within its configuration management system. The SQLITE_SOURCE_ID +string contains the date and time of the check-in (UTC) and a SHA1 +or SHA3-256 hash of the entire source tree. If the source code has +been edited in any way since it was last checked in, then the last +four hexadecimal digits of the hash may be modified.</p> + +<p>See also: <a href="#sqlite3_libversion">sqlite3_libversion()</a>, +<a href="#sqlite3_libversion">sqlite3_libversion_number()</a>, <a href="#sqlite3_libversion">sqlite3_sourceid()</a>, +<a href="lang_corefunc.html#sqlite_version">sqlite_version()</a> and <a href="lang_corefunc.html#sqlite_source_id">sqlite_source_id()</a>. +</p><hr><a name="SQLITE_STATIC"></a> +<h2>Constants Defining Special Destructor Behavior</h2> +</div> +<blockquote><pre> +typedef void (*sqlite3_destructor_type)(void*); +#define SQLITE_STATIC ((sqlite3_destructor_type)0) +#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) +</pre></blockquote> +<p> +These are special values for the destructor that is passed in as the +final argument to routines like <a href="#sqlite3_result_blob">sqlite3_result_blob()</a>. If the destructor +argument is SQLITE_STATIC, it means that the content pointer is constant +and will never change. It does not need to be destroyed. The +SQLITE_TRANSIENT value means that the content will likely change in +the near future and that SQLite should make its own private copy of +the content before returning.</p> + +<p>The typedef is necessary to work around problems in certain +C++ compilers. +</p><hr><a name="SQLITE_STATUS_MALLOC_COUNT"></a> +<h2>Status Parameters</h2> +</div> +<blockquote><pre> +#define SQLITE_STATUS_MEMORY_USED 0 +#define SQLITE_STATUS_PAGECACHE_USED 1 +#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 +#define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */ +#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */ +#define SQLITE_STATUS_MALLOC_SIZE 5 +#define SQLITE_STATUS_PARSER_STACK 6 +#define SQLITE_STATUS_PAGECACHE_SIZE 7 +#define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */ +#define SQLITE_STATUS_MALLOC_COUNT 9 +</pre></blockquote> +<p> +These integer constants designate various run-time status parameters +that can be returned by <a href="#sqlite3_status">sqlite3_status()</a>.</p> + +<p><dl> +<a name="sqlitestatusmemoryused"></a> + <dt>SQLITE_STATUS_MEMORY_USED</dt> +<dd>This parameter is the current amount of memory checked out +using <a href="#sqlite3_free">sqlite3_malloc()</a>, either directly or indirectly. The +figure includes calls made to <a href="#sqlite3_free">sqlite3_malloc()</a> by the application +and internal memory usage by the SQLite library. Auxiliary page-cache +memory controlled by <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a> is not included in +this parameter. The amount returned is the sum of the allocation +sizes as reported by the xSize method in <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a>.</dd></p> + +<p><a name="sqlitestatusmallocsize"></a> + <dt>SQLITE_STATUS_MALLOC_SIZE</dt> +<dd>This parameter records the largest memory allocation request +handed to <a href="#sqlite3_free">sqlite3_malloc()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a> (or their +internal equivalents). Only the value returned in the +*pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest. +The value written into the *pCurrent parameter is undefined.</dd></p> + +<p><a name="sqlitestatusmalloccount"></a> + <dt>SQLITE_STATUS_MALLOC_COUNT</dt> +<dd>This parameter records the number of separate memory allocations +currently checked out.</dd></p> + +<p><a name="sqlitestatuspagecacheused"></a> + <dt>SQLITE_STATUS_PAGECACHE_USED</dt> +<dd>This parameter returns the number of pages used out of the +<a href="malloc.html#pagecache">pagecache memory allocator</a> that was configured using +<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>. The +value returned is in pages, not in bytes.</dd></p> + +<p><a name="sqlitestatuspagecacheoverflow"></a> + +<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> +<dd>This parameter returns the number of bytes of page cache +allocation which could not be satisfied by the <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a> +buffer and where forced to overflow to <a href="#sqlite3_free">sqlite3_malloc()</a>. The +returned value includes allocations that overflowed because they +where too large (they were larger than the "sz" parameter to +<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>) and allocations that overflowed because +no space was left in the page cache.</dd></p> + +<p><a name="sqlitestatuspagecachesize"></a> + <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> +<dd>This parameter records the largest memory allocation request +handed to the <a href="malloc.html#pagecache">pagecache memory allocator</a>. Only the value returned in the +*pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest. +The value written into the *pCurrent parameter is undefined.</dd></p> + +<p><a name="sqlitestatusscratchused"></a> + <dt>SQLITE_STATUS_SCRATCH_USED</dt> +<dd>No longer used.</dd></p> + +<p><a name="sqlitestatusscratchoverflow"></a> + <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> +<dd>No longer used.</dd></p> + +<p><a name="sqlitestatusscratchsize"></a> + <dt>SQLITE_STATUS_SCRATCH_SIZE</dt> +<dd>No longer used.</dd></p> + +<p><a name="sqlitestatusparserstack"></a> + <dt>SQLITE_STATUS_PARSER_STACK</dt> +<dd>The *pHighwater parameter records the deepest parser stack. +The *pCurrent value is undefined. The *pHighwater value is only +meaningful if SQLite is compiled with <a href="compile.html#yytrackmaxstackdepth">YYTRACKMAXSTACKDEPTH</a>.</dd> +</dl></p> + +<p>New status parameters may be added from time to time. +</p><hr><a name="SQLITE_SYNC_DATAONLY"></a> +<h2>Synchronization Type Flags</h2> +</div> +<blockquote><pre> +#define SQLITE_SYNC_NORMAL 0x00002 +#define SQLITE_SYNC_FULL 0x00003 +#define SQLITE_SYNC_DATAONLY 0x00010 +</pre></blockquote> +<p> +When SQLite invokes the xSync() method of an +<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object it uses a combination of +these integer values as the second argument.</p> + +<p>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. If the lower four bits of the flag +equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. +If the lower four bits equal SQLITE_SYNC_FULL, that means +to use Mac OS X style fullsync instead of fsync().</p> + +<p>Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags +with the <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a>=NORMAL and <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a>=FULL +settings. The <a href="pragma.html#pragma_synchronous">synchronous pragma</a> determines when calls to the +xSync VFS method occur and applies uniformly across all platforms. +The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how +energetic or rigorous or forceful the sync operations are and +only make a difference on Mac OSX for the default SQLite code. +(Third-party VFS implementations might also make the distinction +between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the +operating systems natively supported by SQLite, only Mac OSX +cares about the difference.) +</p><hr><a name="SQLITE_TESTCTRL_ALWAYS"></a> +<h2>Testing Interface Operation Codes</h2> +</div> +<blockquote><pre> +#define SQLITE_TESTCTRL_FIRST 5 +#define SQLITE_TESTCTRL_PRNG_SAVE 5 +#define SQLITE_TESTCTRL_PRNG_RESTORE 6 +#define SQLITE_TESTCTRL_PRNG_RESET 7 /* NOT USED */ +#define SQLITE_TESTCTRL_FK_NO_ACTION 7 +#define SQLITE_TESTCTRL_BITVEC_TEST 8 +#define SQLITE_TESTCTRL_FAULT_INSTALL 9 +#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 +#define SQLITE_TESTCTRL_PENDING_BYTE 11 +#define SQLITE_TESTCTRL_ASSERT 12 +#define SQLITE_TESTCTRL_ALWAYS 13 +#define SQLITE_TESTCTRL_RESERVE 14 /* NOT USED */ +#define SQLITE_TESTCTRL_JSON_SELFCHECK 14 +#define SQLITE_TESTCTRL_OPTIMIZATIONS 15 +#define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */ +#define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ +#define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17 +#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 +#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ +#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 +#define SQLITE_TESTCTRL_NEVER_CORRUPT 20 +#define SQLITE_TESTCTRL_VDBE_COVERAGE 21 +#define SQLITE_TESTCTRL_BYTEORDER 22 +#define SQLITE_TESTCTRL_ISINIT 23 +#define SQLITE_TESTCTRL_SORTER_MMAP 24 +#define SQLITE_TESTCTRL_IMPOSTER 25 +#define SQLITE_TESTCTRL_PARSER_COVERAGE 26 +#define SQLITE_TESTCTRL_RESULT_INTREAL 27 +#define SQLITE_TESTCTRL_PRNG_SEED 28 +#define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29 +#define SQLITE_TESTCTRL_SEEK_COUNT 30 +#define SQLITE_TESTCTRL_TRACEFLAGS 31 +#define SQLITE_TESTCTRL_TUNE 32 +#define SQLITE_TESTCTRL_LOGEST 33 +#define SQLITE_TESTCTRL_USELONGDOUBLE 34 +#define SQLITE_TESTCTRL_LAST 34 /* Largest TESTCTRL */ +</pre></blockquote> +<p> +These constants are the valid operation code parameters used +as the first argument to <a href="#sqlite3_test_control">sqlite3_test_control()</a>.</p> + +<p>These parameters and their meanings are subject to change +without notice. These values are for testing purposes only. +Applications should not use any of these parameters or the +<a href="#sqlite3_test_control">sqlite3_test_control()</a> interface. +</p><hr><a name="SQLITE_TRACE"></a> +<h2>SQL Trace Event Codes</h2> +</div> +<blockquote><pre> +#define SQLITE_TRACE_STMT 0x01 +#define SQLITE_TRACE_PROFILE 0x02 +#define SQLITE_TRACE_ROW 0x04 +#define SQLITE_TRACE_CLOSE 0x08 +</pre></blockquote> +<p> +These constants identify classes of events that can be monitored +using the <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a> tracing logic. The M argument +to <a href="#sqlite3_trace_v2">sqlite3_trace_v2(D,M,X,P)</a> is an OR-ed combination of one or more of +the following constants. The first argument to the trace callback +is one of the following constants.</p> + +<p>New tracing constants may be added in future releases.</p> + +<p>A trace callback has four arguments: xCallback(T,C,P,X). +The T argument is one of the integer type codes above. +The C argument is a copy of the context pointer passed in as the +fourth argument to <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a>. +The P and X arguments are pointers whose meanings depend on T.</p> + +<p><dl> +<a name="sqlitetracestmt"></a> + <dt>SQLITE_TRACE_STMT</dt> +<dd>An SQLITE_TRACE_STMT callback is invoked when a prepared statement +first begins running and possibly at other times during the +execution of the prepared statement, such as at the start of each +trigger subprogram. The P argument is a pointer to the +<a href="#sqlite3_stmt">prepared statement</a>. The X argument is a pointer to a string which +is the unexpanded SQL text of the prepared statement or an SQL comment +that indicates the invocation of a trigger. The callback can compute +the same text that would have been returned by the legacy <a href="#sqlite3_profile">sqlite3_trace()</a> +interface by using the X argument when X begins with "--" and invoking +<a href="#sqlite3_expanded_sql">sqlite3_expanded_sql(P)</a> otherwise.</p> + +<p><a name="sqlitetraceprofile"></a> + <dt>SQLITE_TRACE_PROFILE</dt> +<dd>An SQLITE_TRACE_PROFILE callback provides approximately the same +information as is provided by the <a href="#sqlite3_profile">sqlite3_profile()</a> callback. +The P argument is a pointer to the <a href="#sqlite3_stmt">prepared statement</a> and the +X argument points to a 64-bit integer which is approximately +the number of nanoseconds that the prepared statement took to run. +The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.</p> + +<p><a name="sqlitetracerow"></a> + <dt>SQLITE_TRACE_ROW</dt> +<dd>An SQLITE_TRACE_ROW callback is invoked whenever a prepared +statement generates a single row of result. +The P argument is a pointer to the <a href="#sqlite3_stmt">prepared statement</a> and the +X argument is unused.</p> + +<p><a name="sqlitetraceclose"></a> + <dt>SQLITE_TRACE_CLOSE</dt> +<dd>An SQLITE_TRACE_CLOSE callback is invoked when a database +connection closes. +The P argument is a pointer to the <a href="#sqlite3">database connection</a> object +and the X argument is unused. +</dl> +</p><hr><a name="SQLITE_TXN_NONE"></a> +<h2>Allowed return values from sqlite3_txn_state()</h2> +</div> +<blockquote><pre> +#define SQLITE_TXN_NONE 0 +#define SQLITE_TXN_READ 1 +#define SQLITE_TXN_WRITE 2 +</pre></blockquote> +<p> +These constants define the current transaction state of a database file. +The <a href="#sqlite3_txn_state">sqlite3_txn_state(D,S)</a> interface returns one of these +constants in order to describe the transaction state of schema S +in <a href="#sqlite3">database connection</a> D.</p> + +<p><dl> +<a name="sqlitetxnnone"></a> + <dt>SQLITE_TXN_NONE</dt> +<dd>The SQLITE_TXN_NONE state means that no transaction is currently +pending.</dd></p> + +<p><a name="sqlitetxnread"></a> + <dt>SQLITE_TXN_READ</dt> +<dd>The SQLITE_TXN_READ state means that the database is currently +in a read transaction. Content has been read from the database file +but nothing in the database file has changed. The transaction state +will advanced to SQLITE_TXN_WRITE if any changes occur and there are +no other conflicting concurrent write transactions. The transaction +state will revert to SQLITE_TXN_NONE following a <a href="lang_transaction.html">ROLLBACK</a> or +<a href="lang_transaction.html">COMMIT</a>.</dd></p> + +<p><a name="sqlitetxnwrite"></a> + <dt>SQLITE_TXN_WRITE</dt> +<dd>The SQLITE_TXN_WRITE state means that the database is currently +in a write transaction. Content has been written to the database file +but has not yet committed. The transaction state will change to +to SQLITE_TXN_NONE at the next <a href="lang_transaction.html">ROLLBACK</a> or <a href="lang_transaction.html">COMMIT</a>.</dd> +</p><hr><a name="SQLITE_VTAB_CONSTRAINT_SUPPORT"></a> +<h2>Virtual Table Configuration Options</h2> +</div> +<blockquote><pre> +#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1 +#define SQLITE_VTAB_INNOCUOUS 2 +#define SQLITE_VTAB_DIRECTONLY 3 +#define SQLITE_VTAB_USES_ALL_SCHEMAS 4 +</pre></blockquote> +<p> +These macros define the various options to the +<a href="#sqlite3_vtab_config">sqlite3_vtab_config()</a> interface that <a href="vtab.html">virtual table</a> implementations +can use to customize and optimize their behavior.</p> + +<p><dl> +<a name="sqlitevtabconstraintsupport"></a> + +<dt>SQLITE_VTAB_CONSTRAINT_SUPPORT</dt> +<dd>Calls of the form +<a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported, +where X is an integer. If X is zero, then the <a href="vtab.html">virtual table</a> whose +<a href="vtab.html#xcreate">xCreate</a> or <a href="vtab.html#xconnect">xConnect</a> method invoked <a href="#sqlite3_vtab_config">sqlite3_vtab_config()</a> does not +support constraints. In this configuration (which is the default) if +a call to the <a href="vtab.html#xupdate">xUpdate</a> method returns <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, then the entire +statement is rolled back as if <a href="lang_conflict.html">OR ABORT</a> had been +specified as part of the users SQL statement, regardless of the actual +ON CONFLICT mode specified.</p> + +<p>If X is non-zero, then the virtual table implementation guarantees +that if <a href="vtab.html#xupdate">xUpdate</a> returns <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, it will do so before +any modifications to internal or persistent data structures have been made. +If the <a href="lang_conflict.html">ON CONFLICT</a> mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite +is able to roll back a statement or database transaction, and abandon +or continue processing the current SQL statement as appropriate. +If the ON CONFLICT mode is REPLACE and the <a href="vtab.html#xupdate">xUpdate</a> method returns +<a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, SQLite handles this as if the ON CONFLICT mode +had been ABORT.</p> + +<p>Virtual table implementations that are required to handle OR REPLACE +must do so within the <a href="vtab.html#xupdate">xUpdate</a> method. If a call to the +<a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> function indicates that the current ON +CONFLICT policy is REPLACE, the virtual table implementation should +silently replace the appropriate rows within the xUpdate callback and +return SQLITE_OK. Or, if this is not possible, it may return +SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT +constraint handling. +</dd></p> + +<p><a name="sqlitevtabdirectonly"></a> +<dt>SQLITE_VTAB_DIRECTONLY</dt> +<dd>Calls of the form +<a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_DIRECTONLY) from within the +the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> methods of a <a href="vtab.html">virtual table</a> implementation +prohibits that virtual table from being used from within triggers and +views. +</dd></p> + +<p><a name="sqlitevtabinnocuous"></a> +<dt>SQLITE_VTAB_INNOCUOUS</dt> +<dd>Calls of the form +<a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_INNOCUOUS) from within the +the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> methods of a <a href="vtab.html">virtual table</a> implementation +identify that virtual table as being safe to use from within triggers +and views. Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the +virtual table can do no serious harm even if it is controlled by a +malicious hacker. Developers should avoid setting the SQLITE_VTAB_INNOCUOUS +flag unless absolutely necessary. +</dd></p> + +<p><a name="sqlitevtabusesallschemas"></a> +<dt>SQLITE_VTAB_USES_ALL_SCHEMAS</dt> +<dd>Calls of the form +<a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_USES_ALL_SCHEMA) from within the +the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> methods of a <a href="vtab.html">virtual table</a> implementation +instruct the query planner to begin at least a read transaction on +all schemas ("main", "temp", and any ATTACH-ed databases) whenever the +virtual table is used. +</dd> +</dl> +</p><hr><a name="SQLITE_WIN32_DATA_DIRECTORY_TYPE"></a> +<h2>Win32 Directory Types</h2> +</div> +<blockquote><pre> +#define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1 +#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2 +</pre></blockquote> +<p> +These macros are only available on Windows. They define the allowed values +for the type argument to the <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory</a> interface. +</p><hr><a name="SQLITE_LIMIT_ATTACHED"></a> +<h2>Run-Time Limit Categories</h2> +</div> +<blockquote><pre> +#define SQLITE_LIMIT_LENGTH 0 +#define SQLITE_LIMIT_SQL_LENGTH 1 +#define SQLITE_LIMIT_COLUMN 2 +#define SQLITE_LIMIT_EXPR_DEPTH 3 +#define SQLITE_LIMIT_COMPOUND_SELECT 4 +#define SQLITE_LIMIT_VDBE_OP 5 +#define SQLITE_LIMIT_FUNCTION_ARG 6 +#define SQLITE_LIMIT_ATTACHED 7 +#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 +#define SQLITE_LIMIT_VARIABLE_NUMBER 9 +#define SQLITE_LIMIT_TRIGGER_DEPTH 10 +#define SQLITE_LIMIT_WORKER_THREADS 11 +</pre></blockquote> +<p> +These constants define various performance limits +that can be lowered at run-time using <a href="#sqlite3_limit">sqlite3_limit()</a>. +The synopsis of the meanings of the various limits is shown below. +Additional information is available at <a href="limits.html">Limits in SQLite</a>.</p> + +<p><dl> +<a name="sqlitelimitlength"></a> + <dt>SQLITE_LIMIT_LENGTH</dt> +<dd>The maximum size of any string or BLOB or table row, in bytes.<dd></p> + +<p><a name="sqlitelimitsqllength"></a> + <dt>SQLITE_LIMIT_SQL_LENGTH</dt> +<dd>The maximum length of an SQL statement, in bytes.</dd></p> + +<p><a name="sqlitelimitcolumn"></a> + <dt>SQLITE_LIMIT_COLUMN</dt> +<dd>The maximum number of columns in a table definition or in the +result set of a <a href="lang_select.html">SELECT</a> or the maximum number of columns in an index +or in an ORDER BY or GROUP BY clause.</dd></p> + +<p><a name="sqlitelimitexprdepth"></a> + <dt>SQLITE_LIMIT_EXPR_DEPTH</dt> +<dd>The maximum depth of the parse tree on any expression.</dd></p> + +<p><a name="sqlitelimitcompoundselect"></a> + <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt> +<dd>The maximum number of terms in a compound SELECT statement.</dd></p> + +<p><a name="sqlitelimitvdbeop"></a> + <dt>SQLITE_LIMIT_VDBE_OP</dt> +<dd>The maximum number of instructions in a virtual machine program +used to implement an SQL statement. If <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or +the equivalent tries to allocate space for more than this many opcodes +in a single prepared statement, an SQLITE_NOMEM error is returned.</dd></p> + +<p><a name="sqlitelimitfunctionarg"></a> + <dt>SQLITE_LIMIT_FUNCTION_ARG</dt> +<dd>The maximum number of arguments on a function.</dd></p> + +<p><a name="sqlitelimitattached"></a> + <dt>SQLITE_LIMIT_ATTACHED</dt> +<dd>The maximum number of <a href="lang_attach.html">attached databases</a>.</dd></p> + +<p><a name="sqlitelimitlikepatternlength"></a> + +<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> +<dd>The maximum length of the pattern argument to the <a href="lang_expr.html#like">LIKE</a> or +<a href="lang_expr.html#glob">GLOB</a> operators.</dd></p> + +<p><a name="sqlitelimitvariablenumber"></a> + +<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> +<dd>The maximum index number of any <a href="lang_expr.html#varparam">parameter</a> in an SQL statement.</p> + +<p><a name="sqlitelimittriggerdepth"></a> + <dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt> +<dd>The maximum depth of recursion for triggers.</dd></p> + +<p><a name="sqlitelimitworkerthreads"></a> + <dt>SQLITE_LIMIT_WORKER_THREADS</dt> +<dd>The maximum number of auxiliary worker threads that a single +<a href="#sqlite3_stmt">prepared statement</a> may start.</dd> +</dl> +</p><hr><a name="SQLITE_DBSTATUS options"></a> +<h2>Status Parameters for database connections</h2> +</div> +<blockquote><pre> +#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 +#define SQLITE_DBSTATUS_CACHE_USED 1 +#define SQLITE_DBSTATUS_SCHEMA_USED 2 +#define SQLITE_DBSTATUS_STMT_USED 3 +#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 +#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 +#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 +#define SQLITE_DBSTATUS_CACHE_HIT 7 +#define SQLITE_DBSTATUS_CACHE_MISS 8 +#define SQLITE_DBSTATUS_CACHE_WRITE 9 +#define SQLITE_DBSTATUS_DEFERRED_FKS 10 +#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 +#define SQLITE_DBSTATUS_CACHE_SPILL 12 +#define SQLITE_DBSTATUS_MAX 12 /* Largest defined DBSTATUS */ +</pre></blockquote> +<p> +These constants are the available integer "verbs" that can be passed as +the second argument to the <a href="#sqlite3_db_status">sqlite3_db_status()</a> interface.</p> + +<p>New verbs may be added in future releases of SQLite. Existing verbs +might be discontinued. Applications should check the return code from +<a href="#sqlite3_db_status">sqlite3_db_status()</a> to make sure that the call worked. +The <a href="#sqlite3_db_status">sqlite3_db_status()</a> interface will return a non-zero error code +if a discontinued or unsupported verb is invoked.</p> + +<p><dl> +<a name="sqlitedbstatuslookasideused"></a> + <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> +<dd>This parameter returns the number of lookaside memory slots currently +checked out.</dd></p> + +<p><a name="sqlitedbstatuslookasidehit"></a> + <dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt> +<dd>This parameter returns the number of malloc attempts that were +satisfied using lookaside memory. Only the high-water value is meaningful; +the current value is always zero.</p> + +<p><a name="sqlitedbstatuslookasidemisssize"></a> + +<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt> +<dd>This parameter returns the number malloc attempts that might have +been satisfied using lookaside memory but failed due to the amount of +memory requested being larger than the lookaside slot size. +Only the high-water value is meaningful; +the current value is always zero.</p> + +<p><a name="sqlitedbstatuslookasidemissfull"></a> + +<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt> +<dd>This parameter returns the number malloc attempts that might have +been satisfied using lookaside memory but failed due to all lookaside +memory already being in use. +Only the high-water value is meaningful; +the current value is always zero.</p> + +<p><a name="sqlitedbstatuscacheused"></a> + <dt>SQLITE_DBSTATUS_CACHE_USED</dt> +<dd>This parameter returns the approximate number of bytes of heap +memory used by all pager caches associated with the database connection. +The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.</p> + +<p><a name="sqlitedbstatuscacheusedshared"></a> + +<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt> +<dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a +pager cache is shared between two or more connections the bytes of heap +memory used by that pager cache is divided evenly between the attached +connections. In other words, if none of the pager caches associated +with the database connection are shared, this request returns the same +value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are +shared, the value returned by this call will be smaller than that returned +by DBSTATUS_CACHE_USED. The highwater mark associated with +SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.</p> + +<p><a name="sqlitedbstatusschemaused"></a> + <dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> +<dd>This parameter returns the approximate number of bytes of heap +memory used to store the schema for all databases associated +with the connection - main, temp, and any <a href="lang_attach.html">ATTACH</a>-ed databases. +The full amount of memory used by the schemas is reported, even if the +schema memory is shared with other database connections due to +<a href="sharedcache.html">shared cache mode</a> being enabled. +The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.</p> + +<p><a name="sqlitedbstatusstmtused"></a> + <dt>SQLITE_DBSTATUS_STMT_USED</dt> +<dd>This parameter returns the approximate number of bytes of heap +and lookaside memory used by all prepared statements associated with +the database connection. +The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0. +</dd></p> + +<p><a name="sqlitedbstatuscachehit"></a> + <dt>SQLITE_DBSTATUS_CACHE_HIT</dt> +<dd>This parameter returns the number of pager cache hits that have +occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT +is always 0. +</dd></p> + +<p><a name="sqlitedbstatuscachemiss"></a> + <dt>SQLITE_DBSTATUS_CACHE_MISS</dt> +<dd>This parameter returns the number of pager cache misses that have +occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS +is always 0. +</dd></p> + +<p><a name="sqlitedbstatuscachewrite"></a> + <dt>SQLITE_DBSTATUS_CACHE_WRITE</dt> +<dd>This parameter returns the number of dirty cache entries that have +been written to disk. Specifically, the number of pages written to the +wal file in wal mode databases, or the number of pages written to the +database file in rollback mode databases. Any pages written as part of +transaction rollback or database recovery operations are not included. +If an IO or other error occurs while writing a page to disk, the effect +on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined. The +highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0. +</dd></p> + +<p><a name="sqlitedbstatuscachespill"></a> + <dt>SQLITE_DBSTATUS_CACHE_SPILL</dt> +<dd>This parameter returns the number of dirty cache entries that have +been written to disk in the middle of a transaction due to the page +cache overflowing. Transactions are more efficient if they are written +to disk all at once. When pages spill mid-transaction, that introduces +additional overhead. This parameter can be used help identify +inefficiencies that can be resolved by increasing the cache size. +</dd></p> + +<p><a name="sqlitedbstatusdeferredfks"></a> + <dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt> +<dd>This parameter returns zero for the current value if and only if +all foreign key constraints (deferred or immediate) have been +resolved. The highwater mark is always 0. +</dd> +</dl> +</p><hr><a name="SQLITE_STMTSTATUS counter"></a> +<h2>Status Parameters for prepared statements</h2> +</div> +<blockquote><pre> +#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 +#define SQLITE_STMTSTATUS_SORT 2 +#define SQLITE_STMTSTATUS_AUTOINDEX 3 +#define SQLITE_STMTSTATUS_VM_STEP 4 +#define SQLITE_STMTSTATUS_REPREPARE 5 +#define SQLITE_STMTSTATUS_RUN 6 +#define SQLITE_STMTSTATUS_FILTER_MISS 7 +#define SQLITE_STMTSTATUS_FILTER_HIT 8 +#define SQLITE_STMTSTATUS_MEMUSED 99 +</pre></blockquote> +<p> +These preprocessor macros define integer codes that name counter +values associated with the <a href="#sqlite3_stmt_status">sqlite3_stmt_status()</a> interface. +The meanings of the various counters are as follows:</p> + +<p><dl> +<a name="sqlitestmtstatusfullscanstep"></a> + <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt> +<dd>This is the number of times that SQLite has stepped forward in +a table as part of a full table scan. Large numbers for this counter +may indicate opportunities for performance improvement through +careful use of indices.</dd></p> + +<p><a name="sqlitestmtstatussort"></a> + <dt>SQLITE_STMTSTATUS_SORT</dt> +<dd>This is the number of sort operations that have occurred. +A non-zero value in this counter may indicate an opportunity to +improvement performance through careful use of indices.</dd></p> + +<p><a name="sqlitestmtstatusautoindex"></a> + <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt> +<dd>This is the number of rows inserted into transient indices that +were created automatically in order to help joins run faster. +A non-zero value in this counter may indicate an opportunity to +improvement performance by adding permanent indices that do not +need to be reinitialized each time the statement is run.</dd></p> + +<p><a name="sqlitestmtstatusvmstep"></a> + <dt>SQLITE_STMTSTATUS_VM_STEP</dt> +<dd>This is the number of virtual machine operations executed +by the prepared statement if that number is less than or equal +to 2147483647. The number of virtual machine operations can be +used as a proxy for the total work done by the prepared statement. +If the number of virtual machine operations exceeds 2147483647 +then the value returned by this statement status code is undefined.</p> + +<p><a name="sqlitestmtstatusreprepare"></a> + <dt>SQLITE_STMTSTATUS_REPREPARE</dt> +<dd>This is the number of times that the prepare statement has been +automatically regenerated due to schema changes or changes to +<a href="lang_expr.html#varparam">bound parameters</a> that might affect the query plan.</p> + +<p><a name="sqlitestmtstatusrun"></a> + <dt>SQLITE_STMTSTATUS_RUN</dt> +<dd>This is the number of times that the prepared statement has +been run. A single "run" for the purposes of this counter is one +or more calls to <a href="#sqlite3_step">sqlite3_step()</a> followed by a call to <a href="#sqlite3_reset">sqlite3_reset()</a>. +The counter is incremented on the first <a href="#sqlite3_step">sqlite3_step()</a> call of each +cycle.</p> + +<p><a name="sqlitestmtstatusfiltermiss"></a> + +<a name="sqlitestmtstatusfilterhit"></a> + +<dt>SQLITE_STMTSTATUS_FILTER_HIT<br> +SQLITE_STMTSTATUS_FILTER_MISS</dt> +<dd>SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join +step was bypassed because a Bloom filter returned not-found. The +corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of +times that the Bloom filter returned a find, and thus the join step +had to be processed as normal.</p> + +<p><a name="sqlitestmtstatusmemused"></a> + <dt>SQLITE_STMTSTATUS_MEMUSED</dt> +<dd>This is the approximate number of bytes of heap memory +used to store the prepared statement. This value is not actually +a counter, and so the resetFlg parameter to sqlite3_stmt_status() +is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED. +</dd> +</dl> +</p><hr><a name="sqlite3_snapshot"></a> +<h2>Database Snapshot</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_snapshot { + unsigned char hidden[48]; +} sqlite3_snapshot; +</pre></blockquote> +<p> +An instance of the snapshot object records the state of a <a href="wal.html">WAL mode</a> +database for some specific point in history.</p> + +<p>In <a href="wal.html">WAL mode</a>, multiple <a href="#sqlite3">database connections</a> that are open on the +same database file can each be reading a different historical version +of the database file. When a <a href="#sqlite3">database connection</a> begins a read +transaction, that connection sees an unchanging copy of the database +as it existed for the point in time when the transaction first started. +Subsequent changes to the database from other connections are not seen +by the reader until a new read transaction is started.</p> + +<p>The sqlite3_snapshot object records state information about an historical +version of the database file so that it is possible to later open a new read +transaction that sees that historical version of the database rather than +the most recent version. +</p><p>1 Constructor using this object: <a href="#sqlite3_snapshot_get">sqlite3_snapshot_get()</a></p> +<p>1 Destructor using this object: <a href="#sqlite3_snapshot_free">sqlite3_snapshot_free()</a></p> +<p>3 Methods using this object: + <a href="#sqlite3_snapshot_cmp">sqlite3_snapshot_cmp()</a>, +<a href="#sqlite3_snapshot_open">sqlite3_snapshot_open()</a>, +<a href="#sqlite3_snapshot_recover">sqlite3_snapshot_recover()</a></p> +<hr><a name="sqlite3_int64"></a> +<h2>64-Bit Integer Types</h2> +</div> +<blockquote><pre> +#ifdef SQLITE_INT64_TYPE + typedef SQLITE_INT64_TYPE sqlite_int64; +# ifdef SQLITE_UINT64_TYPE + typedef SQLITE_UINT64_TYPE sqlite_uint64; +# else + typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; +# endif +#elif defined(_MSC_VER) || defined(__BORLANDC__) + typedef __int64 sqlite_int64; + typedef unsigned __int64 sqlite_uint64; +#else + typedef long long int sqlite_int64; + typedef unsigned long long int sqlite_uint64; +#endif +typedef sqlite_int64 sqlite3_int64; +typedef sqlite_uint64 sqlite3_uint64; +</pre></blockquote> +<p> +Because there is no cross-platform way to specify 64-bit integer types +SQLite includes typedefs for 64-bit signed and unsigned integers.</p> + +<p>The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. +The sqlite_int64 and sqlite_uint64 types are supported for backwards +compatibility only.</p> + +<p>The sqlite3_int64 and sqlite_int64 types can store integer values +between -9223372036854775808 and +9223372036854775807 inclusive. The +sqlite3_uint64 and sqlite_uint64 types can store integer values +between 0 and +18446744073709551615 inclusive. +</p><hr><a name="sqlite3_module"></a> +<h2>Virtual Table Object</h2> +</div> +<blockquote><pre> +struct sqlite3_module { + int iVersion; + int (*xCreate)(sqlite3*, void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); + int (*xConnect)(sqlite3*, void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); + int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); + int (*xDisconnect)(sqlite3_vtab *pVTab); + int (*xDestroy)(sqlite3_vtab *pVTab); + int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); + int (*xClose)(sqlite3_vtab_cursor*); + int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, + int argc, sqlite3_value **argv); + int (*xNext)(sqlite3_vtab_cursor*); + int (*xEof)(sqlite3_vtab_cursor*); + int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); + int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); + int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); + int (*xBegin)(sqlite3_vtab *pVTab); + int (*xSync)(sqlite3_vtab *pVTab); + int (*xCommit)(sqlite3_vtab *pVTab); + int (*xRollback)(sqlite3_vtab *pVTab); + int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, + void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), + void **ppArg); + int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); + /* The methods above are in version 1 of the sqlite_module object. Those + ** below are for version 2 and greater. */ + int (*xSavepoint)(sqlite3_vtab *pVTab, int); + int (*xRelease)(sqlite3_vtab *pVTab, int); + int (*xRollbackTo)(sqlite3_vtab *pVTab, int); + /* The methods above are in versions 1 and 2 of the sqlite_module object. + ** Those below are for version 3 and greater. */ + int (*xShadowName)(const char*); + /* The methods above are in versions 1 through 3 of the sqlite_module object. + ** Those below are for version 4 and greater. */ + int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema, + const char *zTabName, int mFlags, char **pzErr); +}; +</pre></blockquote> +<p> +This structure, sometimes called a "virtual table module", +defines the implementation of a <a href="vtab.html">virtual table</a>. +This structure consists mostly of methods for the module.</p> + +<p>A virtual table module is created by filling in a persistent +instance of this structure and passing a pointer to that instance +to <a href="#sqlite3_create_module">sqlite3_create_module()</a> or <a href="#sqlite3_create_module">sqlite3_create_module_v2()</a>. +The registration remains valid until it is replaced by a different +module or until the <a href="#sqlite3">database connection</a> closes. The content +of this structure must not change while it is registered with +any database connection. +</p><hr><a name="sqlite3_vtab_cursor"></a> +<h2>Virtual Table Cursor Object</h2> +</div> +<blockquote><pre> +struct sqlite3_vtab_cursor { + sqlite3_vtab *pVtab; /* Virtual table of this cursor */ + /* Virtual table implementations will typically add additional fields */ +}; +</pre></blockquote> +<p> +Every <a href="#sqlite3_module">virtual table module</a> implementation uses a subclass of the +following structure to describe cursors that point into the +<a href="vtab.html">virtual table</a> and are used +to loop through the virtual table. Cursors are created using the +<a href="vtab.html#xopen">xOpen</a> method of the module and are destroyed +by the <a href="vtab.html#xclose">xClose</a> method. Cursors are used +by the <a href="vtab.html#xfilter">xFilter</a>, <a href="vtab.html#xnext">xNext</a>, <a href="vtab.html#xeof">xEof</a>, <a href="vtab.html#xcolumn">xColumn</a>, and <a href="vtab.html#xrowid">xRowid</a> methods +of the module. Each module implementation will define +the content of a cursor structure to suit its own needs.</p> + +<p>This superclass exists in order to define fields of the cursor that +are common to all implementations. +</p><hr><a name="sqlite3_blob"></a> +<h2>A Handle To An Open BLOB</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_blob sqlite3_blob; +</pre></blockquote> +<p> +An instance of this object represents an open BLOB on which +<a href="#sqlite3_blob_open">incremental BLOB I/O</a> can be performed. +Objects of this type are created by <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> +and destroyed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. +The <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> interfaces +can be used to read or write small subsections of the BLOB. +The <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface returns the size of the BLOB in bytes. +</p><p>1 Constructor using this object: <a href="#sqlite3_blob_open">sqlite3_blob_open()</a></p> +<p>1 Destructor using this object: <a href="#sqlite3_blob_close">sqlite3_blob_close()</a></p> +<p>4 Methods using this object: + <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a>, +<a href="#sqlite3_blob_read">sqlite3_blob_read()</a>, +<a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a>, +<a href="#sqlite3_blob_write">sqlite3_blob_write()</a></p> +<hr><a name="sqlite3"></a> +<h2>Database Connection Handle</h2> +</div> +<blockquote><pre> +typedef struct sqlite3 sqlite3; +</pre></blockquote> +<p> +Each open SQLite database is represented by a pointer to an instance of +the opaque structure named "sqlite3". It is useful to think of an sqlite3 +pointer as an object. The <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, and +<a href="#sqlite3_open">sqlite3_open_v2()</a> interfaces are its constructors, and <a href="#sqlite3_close">sqlite3_close()</a> +and <a href="#sqlite3_close">sqlite3_close_v2()</a> are its destructors. There are many other +interfaces (such as +<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_create_function">sqlite3_create_function()</a>, and +<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> to name but three) that are methods on an +sqlite3 object. +</p><p>3 Constructors using this object: + <a href="#sqlite3_open">sqlite3_open()</a>, +<a href="#sqlite3_open">sqlite3_open16()</a>, +<a href="#sqlite3_open">sqlite3_open_v2()</a></p> +<p>2 Destructors using this object: + <a href="#sqlite3_close">sqlite3_close()</a>, +<a href="#sqlite3_close">sqlite3_close_v2()</a></p> +<p>79 Methods using this object: +<div class='columns' style='columns: 17em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_autovacuum_pages'>sqlite3_autovacuum_pages</a></li> +<li><a href='#sqlite3_blob_open'>sqlite3_blob_open</a></li> +<li><a href='#sqlite3_busy_handler'>sqlite3_busy_handler</a></li> +<li><a href='#sqlite3_busy_timeout'>sqlite3_busy_timeout</a></li> +<li><a href='#sqlite3_changes'>sqlite3_changes</a></li> +<li><a href='#sqlite3_changes'>sqlite3_changes64</a></li> +<li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed</a></li> +<li><a href='#sqlite3_collation_needed'>sqlite3_collation_needed16</a></li> +<li><a href='#sqlite3_commit_hook'>sqlite3_commit_hook</a></li> +<li><a href='#sqlite3_create_collation'>sqlite3_create_collation</a></li> +<li><a href='#sqlite3_create_collation'>sqlite3_create_collation16</a></li> +<li><a href='#sqlite3_create_collation'>sqlite3_create_collation_v2</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_function</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_function16</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_function_v2</a></li> +<li><a href='#sqlite3_create_module'>sqlite3_create_module</a></li> +<li><a href='#sqlite3_create_module'>sqlite3_create_module_v2</a></li> +<li><a href='#sqlite3_create_function'>sqlite3_create_window_function</a></li> +<li><a href='#sqlite3_db_cacheflush'>sqlite3_db_cacheflush</a></li> +<li><a href='#sqlite3_db_config'>sqlite3_db_config</a></li> +<li><a href='#sqlite3_db_filename'>sqlite3_db_filename</a></li> +<li><a href='#sqlite3_db_mutex'>sqlite3_db_mutex</a></li> +<li><a href='#sqlite3_db_name'>sqlite3_db_name</a></li> +<li><a href='#sqlite3_db_readonly'>sqlite3_db_readonly</a></li> +<li><a href='#sqlite3_db_release_memory'>sqlite3_db_release_memory</a></li> +<li><a href='#sqlite3_db_status'>sqlite3_db_status</a></li> +<li><a href='#sqlite3_drop_modules'>sqlite3_drop_modules</a></li> +<li><a href='#sqlite3_enable_load_extension'>sqlite3_enable_load_extension</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errcode</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errmsg</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errmsg16</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_error_offset</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_errstr</a></li> +<li><a href='#sqlite3_exec'>sqlite3_exec</a></li> +<li><a href='#sqlite3_errcode'>sqlite3_extended_errcode</a></li> +<li><a href='#sqlite3_extended_result_codes'>sqlite3_extended_result_codes</a></li> +<li><a href='#sqlite3_file_control'>sqlite3_file_control</a></li> +<li><a href='#sqlite3_free_table'>sqlite3_free_table</a></li> +<li><a href='#sqlite3_get_autocommit'>sqlite3_get_autocommit</a></li> +<li><a href='#sqlite3_get_clientdata'>sqlite3_get_clientdata</a></li> +<li><a href='#sqlite3_free_table'>sqlite3_get_table</a></li> +<li><a href='#sqlite3_interrupt'>sqlite3_interrupt</a></li> +<li><a href='#sqlite3_interrupt'>sqlite3_is_interrupted</a></li> +<li><a href='#sqlite3_last_insert_rowid'>sqlite3_last_insert_rowid</a></li> +<li><a href='#sqlite3_limit'>sqlite3_limit</a></li> +<li><a href='#sqlite3_load_extension'>sqlite3_load_extension</a></li> +<li><a href='#sqlite3_next_stmt'>sqlite3_next_stmt</a></li> +<li><a href='#sqlite3_overload_function'>sqlite3_overload_function</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16_v2</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16_v3</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare_v2</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare_v3</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_blobwrite</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_count</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_depth</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_hook</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_new</a></li> +<li><a href='#sqlite3_preupdate_blobwrite'>sqlite3_preupdate_old</a></li> +<li><a href='#sqlite3_profile'>sqlite3_profile</a></li> +<li><a href='#sqlite3_progress_handler'>sqlite3_progress_handler</a></li> +<li><a href='#sqlite3_commit_hook'>sqlite3_rollback_hook</a></li> +<li><a href='#sqlite3_set_authorizer'>sqlite3_set_authorizer</a></li> +<li><a href='#sqlite3_get_clientdata'>sqlite3_set_clientdata</a></li> +<li><a href='#sqlite3_set_last_insert_rowid'>sqlite3_set_last_insert_rowid</a></li> +<li><a href='#sqlite3_system_errno'>sqlite3_system_errno</a></li> +<li><a href='#sqlite3_table_column_metadata'>sqlite3_table_column_metadata</a></li> +<li><a href='#sqlite3_total_changes'>sqlite3_total_changes</a></li> +<li><a href='#sqlite3_total_changes'>sqlite3_total_changes64</a></li> +<li><a href='#sqlite3_profile'>sqlite3_trace</a></li> +<li><a href='#sqlite3_trace_v2'>sqlite3_trace_v2</a></li> +<li><a href='#sqlite3_txn_state'>sqlite3_txn_state</a></li> +<li><a href='#sqlite3_unlock_notify'>sqlite3_unlock_notify</a></li> +<li><a href='#sqlite3_update_hook'>sqlite3_update_hook</a></li> +<li><a href='#sqlite3_wal_autocheckpoint'>sqlite3_wal_autocheckpoint</a></li> +<li><a href='#sqlite3_wal_checkpoint'>sqlite3_wal_checkpoint</a></li> +<li><a href='#sqlite3_wal_checkpoint_v2'>sqlite3_wal_checkpoint_v2</a></li> +<li><a href='#sqlite3_wal_hook'>sqlite3_wal_hook</a></li> +</ul> +</div> +</p> +<hr><a name="sqlite3_str"></a> +<h2>Dynamic String Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_str sqlite3_str; +</pre></blockquote> +<p> +An instance of the sqlite3_str object contains a dynamically-sized +string under construction.</p> + +<p>The lifecycle of an sqlite3_str object is as follows: +<ol> +<li> The sqlite3_str object is created using <a href="#sqlite3_str_new">sqlite3_str_new()</a>. +<li> Text is appended to the sqlite3_str object using various +methods, such as <a href="#sqlite3_str_append">sqlite3_str_appendf()</a>. +<li> The sqlite3_str object is destroyed and the string it created +is returned using the <a href="#sqlite3_str_finish">sqlite3_str_finish()</a> interface. +</ol> +</p><p>1 Constructor using this object: <a href="#sqlite3_str_new">sqlite3_str_new()</a></p> +<p>1 Destructor using this object: <a href="#sqlite3_str_finish">sqlite3_str_finish()</a></p> +<p>9 Methods using this object: +<div class='columns' style='columns: 17em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_str_append'>sqlite3_str_append</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_appendall</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_appendchar</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_appendf</a></li> +<li><a href='#sqlite3_str_errcode'>sqlite3_str_errcode</a></li> +<li><a href='#sqlite3_str_errcode'>sqlite3_str_length</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_reset</a></li> +<li><a href='#sqlite3_str_errcode'>sqlite3_str_value</a></li> +<li><a href='#sqlite3_str_append'>sqlite3_str_vappendf</a></li> +</ul> +</div> +</p> +<hr><a name="sqlite3_pcache_methods2"></a> +<h2>Application Defined Page Cache.</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; +struct sqlite3_pcache_methods2 { + int iVersion; + void *pArg; + int (*xInit)(void*); + void (*xShutdown)(void*); + sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable); + void (*xCachesize)(sqlite3_pcache*, int nCachesize); + int (*xPagecount)(sqlite3_pcache*); + sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); + void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard); + void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, + unsigned oldKey, unsigned newKey); + void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); + void (*xDestroy)(sqlite3_pcache*); + void (*xShrink)(sqlite3_pcache*); +}; +</pre></blockquote> +<p> +The <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>, ...) interface can +register an alternative page cache implementation by passing in an +instance of the sqlite3_pcache_methods2 structure. +In many applications, most of the heap memory allocated by +SQLite is used for the page cache. +By implementing a +custom page cache using this API, an application can better control +the amount of memory consumed by SQLite, the way in which +that memory is allocated and released, and the policies used to +determine exactly which parts of a database file are cached and for +how long.</p> + +<p>The alternative page cache mechanism is an +extreme measure that is only needed by the most demanding applications. +The built-in page cache is recommended for most uses.</p> + +<p>The contents of the sqlite3_pcache_methods2 structure are copied to an +internal buffer by SQLite within the call to <a href="#sqlite3_config">sqlite3_config</a>. Hence +the application may discard the parameter after the call to +<a href="#sqlite3_config">sqlite3_config()</a> returns.</p> + +<p><a name="thexinitpagecachemethod"></a> + +The xInit() method is called once for each effective +call to <a href="#sqlite3_initialize">sqlite3_initialize()</a> +(usually only once during the lifetime of the process). The xInit() +method is passed a copy of the sqlite3_pcache_methods2.pArg value. +The intent of the xInit() method is to set up global data structures +required by the custom page cache implementation. +If the xInit() method is NULL, then the +built-in default page cache is used instead of the application defined +page cache.</p> + +<p><a name="thexshutdownpagecachemethod"></a> + +The xShutdown() method is called by <a href="#sqlite3_initialize">sqlite3_shutdown()</a>. +It can be used to clean up +any outstanding resources before process shutdown, if required. +The xShutdown() method may be NULL.</p> + +<p>SQLite automatically serializes calls to the xInit method, +so the xInit method need not be threadsafe. The +xShutdown method is only called from <a href="#sqlite3_initialize">sqlite3_shutdown()</a> so it does +not need to be threadsafe either. All other methods must be threadsafe +in multithreaded applications.</p> + +<p>SQLite will never invoke xInit() more than once without an intervening +call to xShutdown().</p> + +<p><a name="thexcreatepagecachemethods"></a> + +SQLite invokes the xCreate() method to construct a new cache instance. +SQLite will typically create one cache instance for each open database file, +though this is not guaranteed. The +first parameter, szPage, is the size in bytes of the pages that must +be allocated by the cache. szPage will always a power of two. The +second parameter szExtra is a number of bytes of extra storage +associated with each page cache entry. The szExtra parameter will +a number less than 250. SQLite will use the +extra szExtra bytes on each page to store metadata about the underlying +database page on disk. The value passed into szExtra depends +on the SQLite version, the target platform, and how SQLite was compiled. +The third argument to xCreate(), bPurgeable, is true if the cache being +created will be used to cache database pages of a file stored on disk, or +false if it is used for an in-memory database. The cache implementation +does not have to do anything special based with the value of bPurgeable; +it is purely advisory. On a cache where bPurgeable is false, SQLite will +never invoke xUnpin() except to deliberately delete a page. +In other words, calls to xUnpin() on a cache with bPurgeable set to +false will always have the "discard" flag set to true. +Hence, a cache created with bPurgeable false will +never contain any unpinned pages.</p> + +<p><a name="thexcachesizepagecachemethod"></a> + +The xCachesize() method may be called at any time by SQLite to set the +suggested maximum cache-size (number of pages stored by) the cache +instance passed as the first argument. This is the value configured using +the SQLite "<a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a>" command. As with the bPurgeable +parameter, the implementation is not required to do anything with this +value; it is advisory only.</p> + +<p><a name="thexpagecountpagecachemethods"></a> + +The xPagecount() method must return the number of pages currently +stored in the cache, both pinned and unpinned.</p> + +<p><a name="thexfetchpagecachemethods"></a> + +The xFetch() method locates a page in the cache and returns a pointer to +an sqlite3_pcache_page object associated with that page, or a NULL pointer. +The pBuf element of the returned sqlite3_pcache_page object will be a +pointer to a buffer of szPage bytes used to store the content of a +single database page. The pExtra element of sqlite3_pcache_page will be +a pointer to the szExtra bytes of extra storage that SQLite has requested +for each entry in the page cache.</p> + +<p>The page to be fetched is determined by the key. The minimum key value +is 1. After it has been retrieved using xFetch, the page is considered +to be "pinned".</p> + +<p>If the requested page is already in the page cache, then the page cache +implementation must return a pointer to the page buffer with its content +intact. If the requested page is not already in the cache, then the +cache implementation should use the value of the createFlag +parameter to help it determined what action to take:</p> + +<p><table border=1 width=85% align=center> +<tr><th> createFlag <th> Behavior when page is not already in cache +<tr><td> 0 <td> Do not allocate a new page. Return NULL. +<tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. +Otherwise return NULL. +<tr><td> 2 <td> Make every effort to allocate a new page. Only return +NULL if allocating a new page is effectively impossible. +</table></p> + +<p>SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite +will only use a createFlag of 2 after a prior call with a createFlag of 1 +failed. In between the xFetch() calls, SQLite may +attempt to unpin one or more cache pages by spilling the content of +pinned pages to disk and synching the operating system disk cache.</p> + +<p><a name="thexunpinpagecachemethod"></a> + +xUnpin() is called by SQLite with a pointer to a currently pinned page +as its second argument. If the third parameter, discard, is non-zero, +then the page must be evicted from the cache. +If the discard parameter is +zero, then the page may be discarded or retained at the discretion of +page cache implementation. The page cache implementation +may choose to evict unpinned pages at any time.</p> + +<p>The cache must not perform any reference counting. A single +call to xUnpin() unpins the page regardless of the number of prior calls +to xFetch().</p> + +<p><a name="thexrekeypagecachemethods"></a> + +The xRekey() method is used to change the key value associated with the +page passed as the second argument. If the cache +previously contains an entry associated with newKey, it must be +discarded. Any prior cache entry associated with newKey is guaranteed not +to be pinned.</p> + +<p>When SQLite calls the xTruncate() method, the cache must discard all +existing cache entries with page numbers (keys) greater than or equal +to the value of the iLimit parameter passed to xTruncate(). If any +of these pages are pinned, they are implicitly unpinned, meaning that +they can be safely discarded.</p> + +<p><a name="thexdestroypagecachemethod"></a> + +The xDestroy() method is used to delete a cache allocated by xCreate(). +All resources associated with the specified cache should be freed. After +calling the xDestroy() method, SQLite considers the <a href="#sqlite3_pcache">sqlite3_pcache*</a> +handle invalid, and will not use it with any other sqlite3_pcache_methods2 +functions.</p> + +<p><a name="thexshrinkpagecachemethod"></a> + +SQLite invokes the xShrink() method when it wants the page cache to +free up as much of heap memory as possible. The page cache implementation +is not obligated to free any memory, but well-behaved implementations should +do their best. +</p><hr><a name="sqlite3_stmt"></a> +<h2>Prepared Statement Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_stmt sqlite3_stmt; +</pre></blockquote> +<p> +An instance of this object represents a single SQL statement that +has been compiled into binary form and is ready to be evaluated.</p> + +<p>Think of each SQL statement as a separate computer program. The +original SQL text is source code. A prepared statement object +is the compiled object code. All SQL must be converted into a +prepared statement before it can be run.</p> + +<p>The life-cycle of a prepared statement object usually goes like this:</p> + +<p><ol> +<li> Create the prepared statement object using <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>. +<li> Bind values to <a href="lang_expr.html#varparam">parameters</a> using the sqlite3_bind_*() +interfaces. +<li> Run the SQL by calling <a href="#sqlite3_step">sqlite3_step()</a> one or more times. +<li> Reset the prepared statement using <a href="#sqlite3_reset">sqlite3_reset()</a> then go back +to step 2. Do this zero or more times. +<li> Destroy the object using <a href="#sqlite3_finalize">sqlite3_finalize()</a>. +</ol> +</p><p>6 Constructors using this object: +<div class='columns' style='columns: 17em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_prepare'>sqlite3_prepare</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16_v2</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare16_v3</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare_v2</a></li> +<li><a href='#sqlite3_prepare'>sqlite3_prepare_v3</a></li> +</ul> +</div> +</p> +<p>1 Destructor using this object: <a href="#sqlite3_finalize">sqlite3_finalize()</a></p> +<p>53 Methods using this object: +<div class='columns' style='columns: 17em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_blob64</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_double</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_int</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_int64</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_null</a></li> +<li><a href='#sqlite3_bind_parameter_count'>sqlite3_bind_parameter_count</a></li> +<li><a href='#sqlite3_bind_parameter_index'>sqlite3_bind_parameter_index</a></li> +<li><a href='#sqlite3_bind_parameter_name'>sqlite3_bind_parameter_name</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_pointer</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_text</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_text16</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_text64</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_value</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob</a></li> +<li><a href='#sqlite3_bind_blob'>sqlite3_bind_zeroblob64</a></li> +<li><a href='#sqlite3_clear_bindings'>sqlite3_clear_bindings</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_blob</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_bytes</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_bytes16</a></li> +<li><a href='#sqlite3_column_count'>sqlite3_column_count</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_database_name16</a></li> +<li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype</a></li> +<li><a href='#sqlite3_column_decltype'>sqlite3_column_decltype16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_double</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_int</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_int64</a></li> +<li><a href='#sqlite3_column_name'>sqlite3_column_name</a></li> +<li><a href='#sqlite3_column_name'>sqlite3_column_name16</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_origin_name16</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name</a></li> +<li><a href='#sqlite3_column_database_name'>sqlite3_column_table_name16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_text</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_text16</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_type</a></li> +<li><a href='#sqlite3_column_blob'>sqlite3_column_value</a></li> +<li><a href='#sqlite3_data_count'>sqlite3_data_count</a></li> +<li><a href='#sqlite3_db_handle'>sqlite3_db_handle</a></li> +<li><a href='#sqlite3_expanded_sql'>sqlite3_expanded_sql</a></li> +<li><a href='#sqlite3_expanded_sql'>sqlite3_normalized_sql</a></li> +<li><a href='#sqlite3_reset'>sqlite3_reset</a></li> +<li><a href='#sqlite3_expanded_sql'>sqlite3_sql</a></li> +<li><a href='#sqlite3_step'>sqlite3_step</a></li> +<li><a href='#sqlite3_stmt_busy'>sqlite3_stmt_busy</a></li> +<li><a href='#sqlite3_stmt_explain'>sqlite3_stmt_explain</a></li> +<li><a href='#sqlite3_stmt_isexplain'>sqlite3_stmt_isexplain</a></li> +<li><a href='#sqlite3_stmt_readonly'>sqlite3_stmt_readonly</a></li> +<li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus</a></li> +<li><a href='#sqlite3_stmt_scanstatus_reset'>sqlite3_stmt_scanstatus_reset</a></li> +<li><a href='#sqlite3_stmt_scanstatus'>sqlite3_stmt_scanstatus_v2</a></li> +<li><a href='#sqlite3_stmt_status'>sqlite3_stmt_status</a></li> +</ul> +</div> +</p> +<hr><a name="sqlite3_value"></a> +<h2>Dynamically Typed Value Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_value sqlite3_value; +</pre></blockquote> +<p> +SQLite uses the sqlite3_value object to represent all values +that can be stored in a database table. SQLite uses dynamic typing +for the values it stores. Values stored in sqlite3_value objects +can be integers, floating point values, strings, BLOBs, or NULL.</p> + +<p>An sqlite3_value object may be either "protected" or "unprotected". +Some interfaces require a protected sqlite3_value. Other interfaces +will accept either a protected or an unprotected sqlite3_value. +Every interface that accepts sqlite3_value arguments specifies +whether or not it requires a protected sqlite3_value. The +<a href="#sqlite3_value_dup">sqlite3_value_dup()</a> interface can be used to construct a new +protected sqlite3_value from an unprotected sqlite3_value.</p> + +<p>The terms "protected" and "unprotected" refer to whether or not +a mutex is held. An internal mutex is held for a protected +sqlite3_value object but no mutex is held for an unprotected +sqlite3_value object. If SQLite is compiled to be single-threaded +(with <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> and with <a href="#sqlite3_threadsafe">sqlite3_threadsafe()</a> returning 0) +or if SQLite is run in one of reduced mutex modes +<a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a> or <a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a> +then there is no distinction between protected and unprotected +sqlite3_value objects and they can be used interchangeably. However, +for maximum code portability it is recommended that applications +still make the distinction between protected and unprotected +sqlite3_value objects even when not strictly required.</p> + +<p>The sqlite3_value objects that are passed as parameters into the +implementation of <a href="appfunc.html">application-defined SQL functions</a> are protected. +The sqlite3_value objects returned by <a href="#sqlite3_vtab_rhs_value">sqlite3_vtab_rhs_value()</a> +are protected. +The sqlite3_value object returned by +<a href="#sqlite3_column_blob">sqlite3_column_value()</a> is unprotected. +Unprotected sqlite3_value objects may only be used as arguments +to <a href="#sqlite3_result_blob">sqlite3_result_value()</a>, <a href="#sqlite3_bind_blob">sqlite3_bind_value()</a>, and +<a href="#sqlite3_value_dup">sqlite3_value_dup()</a>. +The <a href="#sqlite3_value_blob">sqlite3_value_type()</a> family of +interfaces require protected sqlite3_value objects. +</p><p>19 Methods using this object: +<div class='columns' style='columns: 17em auto;'> +<ul style='padding-top:0;'> +<li><a href='#sqlite3_value_blob'>sqlite3_value_blob</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_bytes</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_bytes16</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_double</a></li> +<li><a href='#sqlite3_value_dup'>sqlite3_value_dup</a></li> +<li><a href='#sqlite3_value_encoding'>sqlite3_value_encoding</a></li> +<li><a href='#sqlite3_value_dup'>sqlite3_value_free</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_frombind</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_int</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_int64</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_nochange</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_numeric_type</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_pointer</a></li> +<li><a href='#sqlite3_value_subtype'>sqlite3_value_subtype</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text16</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text16be</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_text16le</a></li> +<li><a href='#sqlite3_value_blob'>sqlite3_value_type</a></li> +</ul> +</div> +</p> +<hr><a name="sqlite3_aggregate_count"></a> +<h2>Deprecated Functions</h2> +</div> +<blockquote><pre> +#ifndef SQLITE_OMIT_DEPRECATED +int sqlite3_aggregate_count(sqlite3_context*); +int sqlite3_expired(sqlite3_stmt*); +int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); +int sqlite3_global_recover(void); +void sqlite3_thread_cleanup(void); +int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int), + void*,sqlite3_int64); +#endif +</pre></blockquote> +<p> +These functions are <a href="capi3ref.html">deprecated</a>. In order to maintain +backwards compatibility with older code, these functions continue +to be supported. However, new applications should avoid +the use of these functions. To encourage programmers to avoid +these functions, we will not explain what they do. +</p><hr><a name="sqlite3_backup_finish"></a> +<h2>Online Backup API.</h2> +</div> +<blockquote><pre> +sqlite3_backup *sqlite3_backup_init( + sqlite3 *pDest, /* Destination database handle */ + const char *zDestName, /* Destination database name */ + sqlite3 *pSource, /* Source database handle */ + const char *zSourceName /* Source database name */ +); +int sqlite3_backup_step(sqlite3_backup *p, int nPage); +int sqlite3_backup_finish(sqlite3_backup *p); +int sqlite3_backup_remaining(sqlite3_backup *p); +int sqlite3_backup_pagecount(sqlite3_backup *p); +</pre></blockquote> +<p> +The backup API copies the content of one database into another. +It is useful either for creating backups of databases or +for copying in-memory databases to or from persistent files.</p> + +<p>See Also: <a href="backup.html">Using the SQLite Online Backup API</a></p> + +<p>SQLite holds a write transaction open on the destination database file +for the duration of the backup operation. +The source database is read-locked only while it is being read; +it is not locked continuously for the entire backup operation. +Thus, the backup may be performed on a live source database without +preventing other database connections from +reading or writing to the source database while the backup is underway.</p> + +<p>To perform a backup operation: +<ol> +<li><b>sqlite3_backup_init()</b> is called once to initialize the +backup, +<li><b>sqlite3_backup_step()</b> is called one or more times to transfer +the data between the two databases, and finally +<li><b>sqlite3_backup_finish()</b> is called to release all resources +associated with the backup operation. +</ol> +There should be exactly one call to sqlite3_backup_finish() for each +successful call to sqlite3_backup_init().</p> + +<p><a name="sqlite3backupinit"></a> + <b>sqlite3_backup_init()</b></p> + +<p>The D and N arguments to sqlite3_backup_init(D,N,S,M) are the +<a href="#sqlite3">database connection</a> associated with the destination database +and the database name, respectively. +The database name is "main" for the main database, "temp" for the +temporary database, or the name specified after the AS keyword in +an <a href="lang_attach.html">ATTACH</a> statement for an attached database. +The S and M arguments passed to +sqlite3_backup_init(D,N,S,M) identify the <a href="#sqlite3">database connection</a> +and database name of the source database, respectively. +The source and destination <a href="#sqlite3">database connections</a> (parameters S and D) +must be different or else sqlite3_backup_init(D,N,S,M) will fail with +an error.</p> + +<p>A call to sqlite3_backup_init() will fail, returning NULL, if +there is already a read or read-write transaction open on the +destination database.</p> + +<p>If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is +returned and an error code and error message are stored in the +destination <a href="#sqlite3">database connection</a> D. +The error code and message for the failed call to sqlite3_backup_init() +can be retrieved using the <a href="#sqlite3_errcode">sqlite3_errcode()</a>, <a href="#sqlite3_errcode">sqlite3_errmsg()</a>, and/or +<a href="#sqlite3_errcode">sqlite3_errmsg16()</a> functions. +A successful call to sqlite3_backup_init() returns a pointer to an +<a href="#sqlite3_backup">sqlite3_backup</a> object. +The <a href="#sqlite3_backup">sqlite3_backup</a> object may be used with the sqlite3_backup_step() and +sqlite3_backup_finish() functions to perform the specified backup +operation.</p> + +<p><a name="sqlite3backupstep"></a> + <b>sqlite3_backup_step()</b></p> + +<p>Function sqlite3_backup_step(B,N) will copy up to N pages between +the source and destination databases specified by <a href="#sqlite3_backup">sqlite3_backup</a> object B. +If N is negative, all remaining source pages are copied. +If sqlite3_backup_step(B,N) successfully copies N pages and there +are still more pages to be copied, then the function returns <a href="#SQLITE_ABORT">SQLITE_OK</a>. +If sqlite3_backup_step(B,N) successfully finishes copying all pages +from source to destination, then it returns <a href="#SQLITE_ABORT">SQLITE_DONE</a>. +If an error occurs while running sqlite3_backup_step(B,N), +then an <a href="rescode.html">error code</a> is returned. As well as <a href="#SQLITE_ABORT">SQLITE_OK</a> and +<a href="#SQLITE_ABORT">SQLITE_DONE</a>, a call to sqlite3_backup_step() may return <a href="#SQLITE_ABORT">SQLITE_READONLY</a>, +<a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, <a href="#SQLITE_ABORT">SQLITE_LOCKED</a>, or an +<a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_XXX</a> extended error code.</p> + +<p>The sqlite3_backup_step() might return <a href="#SQLITE_ABORT">SQLITE_READONLY</a> if +<ol> +<li> the destination database was opened read-only, or +<li> the destination database is using write-ahead-log journaling +and the destination and source page sizes differ, or +<li> the destination database is an in-memory database and the +destination and source page sizes differ. +</ol></p> + +<p>If sqlite3_backup_step() cannot obtain a required file-system lock, then +the <a href="#sqlite3_busy_handler">busy-handler function</a> +is invoked (if one is specified). If the +busy-handler returns non-zero before the lock is available, then +<a href="#SQLITE_ABORT">SQLITE_BUSY</a> is returned to the caller. In this case the call to +sqlite3_backup_step() can be retried later. If the source +<a href="#sqlite3">database connection</a> +is being used to write to the source database when sqlite3_backup_step() +is called, then <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> is returned immediately. Again, in this +case the call to sqlite3_backup_step() can be retried later on. If +<a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_XXX</a>, <a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, or +<a href="#SQLITE_ABORT">SQLITE_READONLY</a> is returned, then +there is no point in retrying the call to sqlite3_backup_step(). These +errors are considered fatal. The application must accept +that the backup operation has failed and pass the backup operation handle +to the sqlite3_backup_finish() to release associated resources.</p> + +<p>The first call to sqlite3_backup_step() obtains an exclusive lock +on the destination file. The exclusive lock is not released until either +sqlite3_backup_finish() is called or the backup operation is complete +and sqlite3_backup_step() returns <a href="#SQLITE_ABORT">SQLITE_DONE</a>. Every call to +sqlite3_backup_step() obtains a <a href="lockingv3.html#shared_lock">shared lock</a> on the source database that +lasts for the duration of the sqlite3_backup_step() call. +Because the source database is not locked between calls to +sqlite3_backup_step(), the source database may be modified mid-way +through the backup process. If the source database is modified by an +external process or via a database connection other than the one being +used by the backup operation, then the backup will be automatically +restarted by the next call to sqlite3_backup_step(). If the source +database is modified by the using the same database connection as is used +by the backup operation, then the backup database is automatically +updated at the same time.</p> + +<p><a name="sqlite3backupfinish"></a> + <b>sqlite3_backup_finish()</b></p> + +<p>When sqlite3_backup_step() has returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>, or when the +application wishes to abandon the backup operation, the application +should destroy the <a href="#sqlite3_backup">sqlite3_backup</a> by passing it to sqlite3_backup_finish(). +The sqlite3_backup_finish() interfaces releases all +resources associated with the <a href="#sqlite3_backup">sqlite3_backup</a> object. +If sqlite3_backup_step() has not yet returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>, then any +active write-transaction on the destination database is rolled back. +The <a href="#sqlite3_backup">sqlite3_backup</a> object is invalid +and may not be used following a call to sqlite3_backup_finish().</p> + +<p>The value returned by sqlite3_backup_finish is <a href="#SQLITE_ABORT">SQLITE_OK</a> if no +sqlite3_backup_step() errors occurred, regardless or whether or not +sqlite3_backup_step() completed. +If an out-of-memory condition or IO error occurred during any prior +sqlite3_backup_step() call on the same <a href="#sqlite3_backup">sqlite3_backup</a> object, then +sqlite3_backup_finish() returns the corresponding <a href="rescode.html">error code</a>.</p> + +<p>A return of <a href="#SQLITE_ABORT">SQLITE_BUSY</a> or <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> from sqlite3_backup_step() +is not a permanent error and does not affect the return value of +sqlite3_backup_finish().</p> + +<p><a name="sqlite3backupremaining"></a> + <a name="sqlite3backuppagecount"></a> + +<b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b></p> + +<p>The sqlite3_backup_remaining() routine returns the number of pages still +to be backed up at the conclusion of the most recent sqlite3_backup_step(). +The sqlite3_backup_pagecount() routine returns the total number of pages +in the source database at the conclusion of the most recent +sqlite3_backup_step(). +The values returned by these functions are only updated by +sqlite3_backup_step(). If the source database is modified in a way that +changes the size of the source database or the number of pages remaining, +those changes are not reflected in the output of sqlite3_backup_pagecount() +and sqlite3_backup_remaining() until after the next +sqlite3_backup_step().</p> + +<p><b>Concurrent Usage of Database Handles</b></p> + +<p>The source <a href="#sqlite3">database connection</a> may be used by the application for other +purposes while a backup operation is underway or being initialized. +If SQLite is compiled and configured to support threadsafe database +connections, then the source database connection may be used concurrently +from within other threads.</p> + +<p>However, the application must guarantee that the destination +<a href="#sqlite3">database connection</a> is not passed to any other API (by any thread) after +sqlite3_backup_init() is called and before the corresponding call to +sqlite3_backup_finish(). SQLite does not currently check to see +if the application incorrectly accesses the destination <a href="#sqlite3">database connection</a> +and so no error code is reported, but the operations may malfunction +nevertheless. Use of the destination database connection while a +backup is in progress might also cause a mutex deadlock.</p> + +<p>If running in <a href="sharedcache.html">shared cache mode</a>, the application must +guarantee that the shared cache used by the destination database +is not accessed while the backup is running. In practice this means +that the application must guarantee that the disk file being +backed up to is not accessed by any connection within the process, +not just the specific connection that was passed to sqlite3_backup_init().</p> + +<p>The <a href="#sqlite3_backup">sqlite3_backup</a> object itself is partially threadsafe. Multiple +threads may safely make multiple concurrent calls to sqlite3_backup_step(). +However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() +APIs are not strictly speaking threadsafe. If they are invoked at the +same time as another thread is invoking sqlite3_backup_step() it is +possible that they return invalid values. +</p><hr><a name="sqlite3_changes"></a> +<h2>Count The Number Of Rows Modified</h2> +</div> +<blockquote><pre> +int sqlite3_changes(sqlite3*); +sqlite3_int64 sqlite3_changes64(sqlite3*); +</pre></blockquote> +<p> +These functions return the number of rows modified, inserted or +deleted by the most recently completed INSERT, UPDATE or DELETE +statement on the database connection specified by the only parameter. +The two functions are identical except for the type of the return value +and that if the number of rows modified by the most recent INSERT, UPDATE +or DELETE is greater than the maximum value supported by type "int", then +the return value of sqlite3_changes() is undefined. Executing any other +type of SQL statement does not modify the value returned by these functions.</p> + +<p>Only changes made directly by the INSERT, UPDATE or DELETE statement are +considered - auxiliary changes caused by <a href="lang_createtrigger.html">triggers</a>, +<a href="foreignkeys.html#fk_actions">foreign key actions</a> or <a href="lang_replace.html">REPLACE</a> constraint resolution are not counted.</p> + +<p>Changes to a view that are intercepted by +<a href="lang_createtrigger.html#instead_of_trigger">INSTEAD OF triggers</a> are not counted. The value +returned by sqlite3_changes() immediately after an INSERT, UPDATE or +DELETE statement run on a view is always zero. Only changes made to real +tables are counted.</p> + +<p>Things are more complicated if the sqlite3_changes() function is +executed while a trigger program is running. This may happen if the +program uses the <a href="lang_corefunc.html#changes">changes() SQL function</a>, or if some other callback +function invokes sqlite3_changes() directly. Essentially:</p> + +<p><ul> +<li> Before entering a trigger program the value returned by +sqlite3_changes() function is saved. After the trigger program +has finished, the original value is restored.</p> + +<p><li> Within a trigger program each INSERT, UPDATE and DELETE +statement sets the value returned by sqlite3_changes() +upon completion as normal. Of course, this value will not include +any changes performed by sub-triggers, as the sqlite3_changes() +value will be saved and restored after each sub-trigger has run. +</ul></p> + +<p>This means that if the changes() SQL function (or similar) is used +by the first INSERT, UPDATE or DELETE statement within a trigger, it +returns the value as set when the calling statement began executing. +If it is used by the second or subsequent such statement within a trigger +program, the value returned reflects the number of rows modified by the +previous INSERT, UPDATE or DELETE statement within the same trigger.</p> + +<p>If a separate thread makes changes on the same database connection +while <a href="#sqlite3_changes">sqlite3_changes()</a> is running then the value returned +is unpredictable and not meaningful.</p> + +<p>See also: +<ul> +<li> the <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> interface +<li> the <a href="pragma.html#pragma_count_changes">count_changes pragma</a> +<li> the <a href="lang_corefunc.html#changes">changes() SQL function</a> +<li> the <a href="pragma.html#pragma_data_version">data_version pragma</a> +</ul> +</p><hr><a name="sqlite3_close"></a> +<h2>Closing A Database Connection</h2> +</div> +<blockquote><pre> +int sqlite3_close(sqlite3*); +int sqlite3_close_v2(sqlite3*); +</pre></blockquote> +<p> +The sqlite3_close() and sqlite3_close_v2() routines are destructors +for the <a href="#sqlite3">sqlite3</a> object. +Calls to sqlite3_close() and sqlite3_close_v2() return <a href="#SQLITE_ABORT">SQLITE_OK</a> if +the <a href="#sqlite3">sqlite3</a> object is successfully destroyed and all associated +resources are deallocated.</p> + +<p>Ideally, applications should <a href="#sqlite3_finalize">finalize</a> all +<a href="#sqlite3_stmt">prepared statements</a>, <a href="#sqlite3_blob_close">close</a> all <a href="#sqlite3_blob">BLOB handles</a>, and +<a href="#sqlite3backupfinish">finish</a> all <a href="#sqlite3_backup">sqlite3_backup</a> objects associated +with the <a href="#sqlite3">sqlite3</a> object prior to attempting to close the object. +If the database connection is associated with unfinalized prepared +statements, BLOB handlers, and/or unfinished sqlite3_backup objects then +sqlite3_close() will leave the database connection open and return +<a href="#SQLITE_ABORT">SQLITE_BUSY</a>. If sqlite3_close_v2() is called with unfinalized prepared +statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups, +it returns <a href="#SQLITE_ABORT">SQLITE_OK</a> regardless, but instead of deallocating the database +connection immediately, it marks the database connection as an unusable +"zombie" and makes arrangements to automatically deallocate the database +connection after all prepared statements are finalized, all BLOB handles +are closed, and all backups have finished. The sqlite3_close_v2() interface +is intended for use with host languages that are garbage collected, and +where the order in which destructors are called is arbitrary.</p> + +<p>If an <a href="#sqlite3">sqlite3</a> object is destroyed while a transaction is open, +the transaction is automatically rolled back.</p> + +<p>The C parameter to <a href="#sqlite3_close">sqlite3_close(C)</a> and <a href="#sqlite3_close">sqlite3_close_v2(C)</a> +must be either a NULL +pointer or an <a href="#sqlite3">sqlite3</a> object pointer obtained +from <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, or +<a href="#sqlite3_open">sqlite3_open_v2()</a>, and not previously closed. +Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer +argument is a harmless no-op. +</p><hr><a name="sqlite3_collation_needed"></a> +<h2>Collation Needed Callbacks</h2> +</div> +<blockquote><pre> +int sqlite3_collation_needed( + sqlite3*, + void*, + void(*)(void*,sqlite3*,int eTextRep,const char*) +); +int sqlite3_collation_needed16( + sqlite3*, + void*, + void(*)(void*,sqlite3*,int eTextRep,const void*) +); +</pre></blockquote> +<p> +To avoid having to register all collation sequences before a database +can be used, a single callback function may be registered with the +<a href="#sqlite3">database connection</a> to be invoked whenever an undefined collation +sequence is required.</p> + +<p>If the function is registered using the sqlite3_collation_needed() API, +then it is passed the names of undefined collation sequences as strings +encoded in UTF-8. If sqlite3_collation_needed16() is used, +the names are passed as UTF-16 in machine native byte order. +A call to either function replaces the existing collation-needed callback.</p> + +<p>When the callback is invoked, the first argument passed is a copy +of the second argument to sqlite3_collation_needed() or +sqlite3_collation_needed16(). The second argument is the database +connection. The third argument is one of <a href="#SQLITE_ANY">SQLITE_UTF8</a>, <a href="#SQLITE_ANY">SQLITE_UTF16BE</a>, +or <a href="#SQLITE_ANY">SQLITE_UTF16LE</a>, indicating the most desirable form of the collation +sequence function required. The fourth parameter is the name of the +required collation sequence.</p> + +<p>The callback function should register the desired collation using +<a href="#sqlite3_create_collation">sqlite3_create_collation()</a>, <a href="#sqlite3_create_collation">sqlite3_create_collation16()</a>, or +<a href="#sqlite3_create_collation">sqlite3_create_collation_v2()</a>. +</p><hr><a name="sqlite3_column_database_name"></a> +<h2>Source Of Data In A Query Result</h2> +</div> +<blockquote><pre> +const char *sqlite3_column_database_name(sqlite3_stmt*,int); +const void *sqlite3_column_database_name16(sqlite3_stmt*,int); +const char *sqlite3_column_table_name(sqlite3_stmt*,int); +const void *sqlite3_column_table_name16(sqlite3_stmt*,int); +const char *sqlite3_column_origin_name(sqlite3_stmt*,int); +const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); +</pre></blockquote> +<p> +These routines provide a means to determine the database, table, and +table column that is the origin of a particular result column in +<a href="lang_select.html">SELECT</a> statement. +The name of the database or table or column can be returned as +either a UTF-8 or UTF-16 string. The _database_ routines return +the database name, the _table_ routines return the table name, and +the origin_ routines return the column name. +The returned string is valid until the <a href="#sqlite3_stmt">prepared statement</a> is destroyed +using <a href="#sqlite3_finalize">sqlite3_finalize()</a> or until the statement is automatically +reprepared by the first call to <a href="#sqlite3_step">sqlite3_step()</a> for a particular run +or until the same information is requested +again in a different encoding.</p> + +<p>The names returned are the original un-aliased names of the +database, table, and column.</p> + +<p>The first argument to these interfaces is a <a href="#sqlite3_stmt">prepared statement</a>. +These functions return information about the Nth result column returned by +the statement, where N is the second function argument. +The left-most column is column 0 for these routines.</p> + +<p>If the Nth column returned by the statement is an expression or +subquery and is not a column value, then all of these functions return +NULL. These routines might also return NULL if a memory allocation error +occurs. Otherwise, they return the name of the attached database, table, +or column that query result column was extracted from.</p> + +<p>As with all other SQLite APIs, those whose names end with "16" return +UTF-16 encoded strings and the other functions return UTF-8.</p> + +<p>These APIs are only available if the library was compiled with the +<a href="compile.html#enable_column_metadata">SQLITE_ENABLE_COLUMN_METADATA</a> C-preprocessor symbol.</p> + +<p>If two or more threads call one or more +<a href="#sqlite3_column_database_name">column metadata interfaces</a> +for the same <a href="#sqlite3_stmt">prepared statement</a> and result column +at the same time then the results are undefined. +</p><hr><a name="sqlite3_column_decltype"></a> +<h2>Declared Datatype Of A Query Result</h2> +</div> +<blockquote><pre> +const char *sqlite3_column_decltype(sqlite3_stmt*,int); +const void *sqlite3_column_decltype16(sqlite3_stmt*,int); +</pre></blockquote> +<p> +The first parameter is a <a href="#sqlite3_stmt">prepared statement</a>. +If this statement is a <a href="lang_select.html">SELECT</a> statement and the Nth column of the +returned result set of that <a href="lang_select.html">SELECT</a> is a table column (not an +expression or subquery) then the declared type of the table +column is returned. If the Nth column of the result set is an +expression or subquery, then a NULL pointer is returned. +The returned string is always UTF-8 encoded.</p> + +<p>For example, given the database schema:</p> + +<p>CREATE TABLE t1(c1 VARIANT);</p> + +<p>and the following statement to be compiled:</p> + +<p>SELECT c1 + 1, c1 FROM t1;</p> + +<p>this routine would return the string "VARIANT" for the second result +column (i==1), and a NULL pointer for the first result column (i==0).</p> + +<p>SQLite uses dynamic run-time typing. So just because a column +is declared to contain a particular type does not mean that the +data stored in that column is of the declared type. SQLite is +strongly typed, but the typing is dynamic not static. Type +is associated with individual values, not with the containers +used to hold those values. +</p><hr><a name="sqlite3_column_name"></a> +<h2>Column Names In A Result Set</h2> +</div> +<blockquote><pre> +const char *sqlite3_column_name(sqlite3_stmt*, int N); +const void *sqlite3_column_name16(sqlite3_stmt*, int N); +</pre></blockquote> +<p> +These routines return the name assigned to a particular column +in the result set of a <a href="lang_select.html">SELECT</a> statement. The sqlite3_column_name() +interface returns a pointer to a zero-terminated UTF-8 string +and sqlite3_column_name16() returns a pointer to a zero-terminated +UTF-16 string. The first parameter is the <a href="#sqlite3_stmt">prepared statement</a> +that implements the <a href="lang_select.html">SELECT</a> statement. The second parameter is the +column number. The leftmost column is number 0.</p> + +<p>The returned string pointer is valid until either the <a href="#sqlite3_stmt">prepared statement</a> +is destroyed by <a href="#sqlite3_finalize">sqlite3_finalize()</a> or until the statement is automatically +reprepared by the first call to <a href="#sqlite3_step">sqlite3_step()</a> for a particular run +or until the next call to +sqlite3_column_name() or sqlite3_column_name16() on the same column.</p> + +<p>If sqlite3_malloc() fails during the processing of either routine +(for example during a conversion from UTF-8 to UTF-16) then a +NULL pointer is returned.</p> + +<p>The name of a result column is the value of the "AS" clause for +that column, if there is an AS clause. If there is no AS clause +then the name of the column is unspecified and may change from +one release of SQLite to the next. +</p><hr><a name="sqlite3_commit_hook"></a> +<h2>Commit And Rollback Notification Callbacks</h2> +</div> +<blockquote><pre> +void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); +void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); +</pre></blockquote> +<p> +The sqlite3_commit_hook() interface registers a callback +function to be invoked whenever a transaction is <a href="lang_transaction.html">committed</a>. +Any callback set by a previous call to sqlite3_commit_hook() +for the same database connection is overridden. +The sqlite3_rollback_hook() interface registers a callback +function to be invoked whenever a transaction is <a href="lang_transaction.html">rolled back</a>. +Any callback set by a previous call to sqlite3_rollback_hook() +for the same database connection is overridden. +The pArg argument is passed through to the callback. +If the callback on a commit hook function returns non-zero, +then the commit is converted into a rollback.</p> + +<p>The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions +return the P argument from the previous call of the same function +on the same <a href="#sqlite3">database connection</a> D, or NULL for +the first call for each function on D.</p> + +<p>The commit and rollback hook callbacks are not reentrant. +The callback implementation must not do anything that will modify +the database connection that invoked the callback. Any actions +to modify the database connection must be deferred until after the +completion of the <a href="#sqlite3_step">sqlite3_step()</a> call that triggered the commit +or rollback hook in the first place. +Note that running any other SQL statements, including SELECT statements, +or merely calling <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> will modify +the database connections for the meaning of "modify" in this paragraph.</p> + +<p>Registering a NULL function disables the callback.</p> + +<p>When the commit hook callback routine returns zero, the <a href="lang_transaction.html">COMMIT</a> +operation is allowed to continue normally. If the commit hook +returns non-zero, then the <a href="lang_transaction.html">COMMIT</a> is converted into a <a href="lang_transaction.html">ROLLBACK</a>. +The rollback hook is invoked on a rollback that results from a commit +hook returning non-zero, just as it would be with any other rollback.</p> + +<p>For the purposes of this API, a transaction is said to have been +rolled back if an explicit "ROLLBACK" statement is executed, or +an error or constraint causes an implicit rollback to occur. +The rollback callback is not invoked if a transaction is +automatically rolled back because the database connection is closed.</p> + +<p>See also the <a href="#sqlite3_update_hook">sqlite3_update_hook()</a> interface. +</p><hr><a name="sqlite3_compileoption_get"></a> +<h2>Run-Time Library Compilation Options Diagnostics</h2> +</div> +<blockquote><pre> +#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS +int sqlite3_compileoption_used(const char *zOptName); +const char *sqlite3_compileoption_get(int N); +#else +# define sqlite3_compileoption_used(X) 0 +# define sqlite3_compileoption_get(X) ((void*)0) +#endif +</pre></blockquote> +<p> +The sqlite3_compileoption_used() function returns 0 or 1 +indicating whether the specified option was defined at +compile time. The SQLITE_ prefix may be omitted from the +option name passed to sqlite3_compileoption_used().</p> + +<p>The sqlite3_compileoption_get() function allows iterating +over the list of options that were defined at compile time by +returning the N-th compile time option string. If N is out of range, +sqlite3_compileoption_get() returns a NULL pointer. The SQLITE_ +prefix is omitted from any strings returned by +sqlite3_compileoption_get().</p> + +<p>Support for the diagnostic functions sqlite3_compileoption_used() +and sqlite3_compileoption_get() may be omitted by specifying the +<a href="compile.html#omit_compileoption_diags">SQLITE_OMIT_COMPILEOPTION_DIAGS</a> option at compile time.</p> + +<p>See also: SQL functions <a href="lang_corefunc.html#sqlite_compileoption_used">sqlite_compileoption_used()</a> and +<a href="lang_corefunc.html#sqlite_compileoption_get">sqlite_compileoption_get()</a> and the <a href="pragma.html#pragma_compile_options">compile_options pragma</a>. +</p><hr><a name="sqlite3_complete"></a> +<h2>Determine If An SQL Statement Is Complete</h2> +</div> +<blockquote><pre> +int sqlite3_complete(const char *sql); +int sqlite3_complete16(const void *sql); +</pre></blockquote> +<p> +These routines are useful during command-line input to determine if the +currently entered text seems to form a complete SQL statement or +if additional input is needed before sending the text into +SQLite for parsing. These routines return 1 if the input string +appears to be a complete SQL statement. A statement is judged to be +complete if it ends with a semicolon token and is not a prefix of a +well-formed CREATE TRIGGER statement. Semicolons that are embedded within +string literals or quoted identifier names or comments are not +independent tokens (they are part of the token in which they are +embedded) and thus do not count as a statement terminator. Whitespace +and comments that follow the final semicolon are ignored.</p> + +<p>These routines return 0 if the statement is incomplete. If a +memory allocation fails, then SQLITE_NOMEM is returned.</p> + +<p>These routines do not parse the SQL statements thus +will not detect syntactically incorrect SQL.</p> + +<p>If SQLite has not been initialized using <a href="#sqlite3_initialize">sqlite3_initialize()</a> prior +to invoking sqlite3_complete16() then sqlite3_initialize() is invoked +automatically by sqlite3_complete16(). If that initialization fails, +then the return value from sqlite3_complete16() will be non-zero +regardless of whether or not the input SQL is complete.</p> + +<p>The input to <a href="#sqlite3_complete">sqlite3_complete()</a> must be a zero-terminated +UTF-8 string.</p> + +<p>The input to <a href="#sqlite3_complete">sqlite3_complete16()</a> must be a zero-terminated +UTF-16 string in native byte order. +</p><hr><a name="sqlite3_create_collation"></a> +<h2>Define New Collating Sequences</h2> +</div> +<blockquote><pre> +int sqlite3_create_collation( + sqlite3*, + const char *zName, + int eTextRep, + void *pArg, + int(*xCompare)(void*,int,const void*,int,const void*) +); +int sqlite3_create_collation_v2( + sqlite3*, + const char *zName, + int eTextRep, + void *pArg, + int(*xCompare)(void*,int,const void*,int,const void*), + void(*xDestroy)(void*) +); +int sqlite3_create_collation16( + sqlite3*, + const void *zName, + int eTextRep, + void *pArg, + int(*xCompare)(void*,int,const void*,int,const void*) +); +</pre></blockquote> +<p> +These functions add, remove, or modify a <a href="datatype3.html#collation">collation</a> associated +with the <a href="#sqlite3">database connection</a> specified as the first argument.</p> + +<p>The name of the collation is a UTF-8 string +for sqlite3_create_collation() and sqlite3_create_collation_v2() +and a UTF-16 string in native byte order for sqlite3_create_collation16(). +Collation names that compare equal according to <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a> are +considered to be the same name.</p> + +<p>The third argument (eTextRep) must be one of the constants: +<ul> +<li> <a href="#SQLITE_ANY">SQLITE_UTF8</a>, +<li> <a href="#SQLITE_ANY">SQLITE_UTF16LE</a>, +<li> <a href="#SQLITE_ANY">SQLITE_UTF16BE</a>, +<li> <a href="#SQLITE_ANY">SQLITE_UTF16</a>, or +<li> <a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a>. +</ul> +The eTextRep argument determines the encoding of strings passed +to the collating function callback, xCompare. +The <a href="#SQLITE_ANY">SQLITE_UTF16</a> and <a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a> values for eTextRep +force strings to be UTF16 with native byte order. +The <a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a> value for eTextRep forces strings to begin +on an even byte address.</p> + +<p>The fourth argument, pArg, is an application data pointer that is passed +through as the first argument to the collating function callback.</p> + +<p>The fifth argument, xCompare, is a pointer to the collating function. +Multiple collating functions can be registered using the same name but +with different eTextRep parameters and SQLite will use whichever +function requires the least amount of data transformation. +If the xCompare argument is NULL then the collating function is +deleted. When all collating functions having the same name are deleted, +that collation is no longer usable.</p> + +<p>The collating function callback is invoked with a copy of the pArg +application data pointer and with two strings in the encoding specified +by the eTextRep argument. The two integer parameters to the collating +function callback are the length of the two strings, in bytes. The collating +function must return an integer that is negative, zero, or positive +if the first string is less than, equal to, or greater than the second, +respectively. A collating function must always return the same answer +given the same inputs. If two or more collating functions are registered +to the same collation name (using different eTextRep values) then all +must give an equivalent answer when invoked with equivalent strings. +The collating function must obey the following properties for all +strings A, B, and C:</p> + +<p><ol> +<li> If A==B then B==A. +<li> If A==B and B==C then A==C. +<li> If A<B THEN B>A. +<li> If A<B and B<C then A<C. +</ol></p> + +<p>If a collating function fails any of the above constraints and that +collating function is registered and used, then the behavior of SQLite +is undefined.</p> + +<p>The sqlite3_create_collation_v2() works like sqlite3_create_collation() +with the addition that the xDestroy callback is invoked on pArg when +the collating function is deleted. +Collating functions are deleted when they are overridden by later +calls to the collation creation functions or when the +<a href="#sqlite3">database connection</a> is closed using <a href="#sqlite3_close">sqlite3_close()</a>.</p> + +<p>The xDestroy callback is <u>not</u> called if the +sqlite3_create_collation_v2() function fails. Applications that invoke +sqlite3_create_collation_v2() with a non-NULL xDestroy argument should +check the return code and dispose of the application data pointer +themselves rather than expecting SQLite to deal with it for them. +This is different from every other SQLite interface. The inconsistency +is unfortunate but cannot be changed without breaking backwards +compatibility.</p> + +<p>See also: <a href="#sqlite3_collation_needed">sqlite3_collation_needed()</a> and <a href="#sqlite3_collation_needed">sqlite3_collation_needed16()</a>. +</p><hr><a name="sqlite3_create_filename"></a> +<h2>Create and Destroy VFS Filenames</h2> +</div> +<blockquote><pre> +sqlite3_filename sqlite3_create_filename( + const char *zDatabase, + const char *zJournal, + const char *zWal, + int nParam, + const char **azParam +); +void sqlite3_free_filename(sqlite3_filename); +</pre></blockquote> +<p> +These interfaces are provided for use by <a href="vfs.html#shim">VFS shim</a> implementations and +are not useful outside of that context.</p> + +<p>The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of +database filename D with corresponding journal file J and WAL file W and +with N URI parameters key/values pairs in the array P. The result from +sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that +is safe to pass to routines like: +<ul> +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_parameter()</a>, +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_boolean()</a>, +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_int64()</a>, +<li> <a href="#sqlite3_uri_boolean">sqlite3_uri_key()</a>, +<li> <a href="#sqlite3_filename_database">sqlite3_filename_database()</a>, +<li> <a href="#sqlite3_filename_database">sqlite3_filename_journal()</a>, or +<li> <a href="#sqlite3_filename_database">sqlite3_filename_wal()</a>. +</ul> +If a memory allocation error occurs, sqlite3_create_filename() might +return a NULL pointer. The memory obtained from sqlite3_create_filename(X) +must be released by a corresponding call to sqlite3_free_filename(Y).</p> + +<p>The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array +of 2*N pointers to strings. Each pair of pointers in this array corresponds +to a key and value for a query parameter. The P parameter may be a NULL +pointer if N is zero. None of the 2*N pointers in the P array may be +NULL pointers and key pointers should not be empty strings. +None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may +be NULL pointers, though they can be empty strings.</p> + +<p>The sqlite3_free_filename(Y) routine releases a memory allocation +previously obtained from sqlite3_create_filename(). Invoking +sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.</p> + +<p>If the Y parameter to sqlite3_free_filename(Y) is anything other +than a NULL pointer or a pointer previously acquired from +sqlite3_create_filename(), then bad things such as heap +corruption or segfaults may occur. The value Y should not be +used again after sqlite3_free_filename(Y) has been called. This means +that if the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen()</a> method of a VFS has been called using Y, +then the corresponding [sqlite3_module.xClose() method should also be +invoked prior to calling sqlite3_free_filename(Y). +</p><hr><a name="sqlite3_create_module"></a> +<h2>Register A Virtual Table Implementation</h2> +</div> +<blockquote><pre> +int sqlite3_create_module( + sqlite3 *db, /* SQLite connection to register module with */ + const char *zName, /* Name of the module */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData /* Client data for xCreate/xConnect */ +); +int sqlite3_create_module_v2( + sqlite3 *db, /* SQLite connection to register module with */ + const char *zName, /* Name of the module */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData, /* Client data for xCreate/xConnect */ + void(*xDestroy)(void*) /* Module destructor function */ +); +</pre></blockquote> +<p> +These routines are used to register a new <a href="#sqlite3_module">virtual table module</a> name. +Module names must be registered before +creating a new <a href="vtab.html">virtual table</a> using the module and before using a +preexisting <a href="vtab.html">virtual table</a> for the module.</p> + +<p>The module name is registered on the <a href="#sqlite3">database connection</a> specified +by the first parameter. The name of the module is given by the +second parameter. The third parameter is a pointer to +the implementation of the <a href="#sqlite3_module">virtual table module</a>. The fourth +parameter is an arbitrary client data pointer that is passed through +into the <a href="vtab.html#xcreate">xCreate</a> and <a href="vtab.html#xconnect">xConnect</a> methods of the virtual table module +when a new virtual table is be being created or reinitialized.</p> + +<p>The sqlite3_create_module_v2() interface has a fifth parameter which +is a pointer to a destructor for the pClientData. SQLite will +invoke the destructor function (if it is not NULL) when SQLite +no longer needs the pClientData pointer. The destructor will also +be invoked if the call to sqlite3_create_module_v2() fails. +The sqlite3_create_module() +interface is equivalent to sqlite3_create_module_v2() with a NULL +destructor.</p> + +<p>If the third parameter (the pointer to the sqlite3_module object) is +NULL then no new module is created and any existing modules with the +same name are dropped.</p> + +<p>See also: <a href="#sqlite3_drop_modules">sqlite3_drop_modules()</a> +</p><hr><a name="sqlite3_errcode"></a> +<h2>Error Codes And Messages</h2> +</div> +<blockquote><pre> +int sqlite3_errcode(sqlite3 *db); +int sqlite3_extended_errcode(sqlite3 *db); +const char *sqlite3_errmsg(sqlite3*); +const void *sqlite3_errmsg16(sqlite3*); +const char *sqlite3_errstr(int); +int sqlite3_error_offset(sqlite3 *db); +</pre></blockquote> +<p> +If the most recent sqlite3_* API call associated with +<a href="#sqlite3">database connection</a> D failed, then the sqlite3_errcode(D) interface +returns the numeric <a href="rescode.html">result code</a> or <a href="rescode.html#extrc">extended result code</a> for that +API call. +The sqlite3_extended_errcode() +interface is the same except that it always returns the +<a href="rescode.html#extrc">extended result code</a> even when extended result codes are +disabled.</p> + +<p>The values returned by sqlite3_errcode() and/or +sqlite3_extended_errcode() might change with each API call. +Except, there are some interfaces that are guaranteed to never +change the value of the error code. The error-code preserving +interfaces include the following:</p> + +<p><ul> +<li> sqlite3_errcode() +<li> sqlite3_extended_errcode() +<li> sqlite3_errmsg() +<li> sqlite3_errmsg16() +<li> sqlite3_error_offset() +</ul></p> + +<p>The sqlite3_errmsg() and sqlite3_errmsg16() return English-language +text that describes the error, as either UTF-8 or UTF-16 respectively, +or NULL if no error message is available. +(See how SQLite handles <a href="invalidutf.html">invalid UTF</a> for exceptions to this rule.) +Memory to hold the error message string is managed internally. +The application does not need to worry about freeing the result. +However, the error string might be overwritten or deallocated by +subsequent calls to other SQLite interface functions.</p> + +<p>The sqlite3_errstr(E) interface returns the English-language text +that describes the <a href="rescode.html">result code</a> E, as UTF-8, or NULL if E is not an +result code for which a text error message is available. +Memory to hold the error message string is managed internally +and must not be freed by the application.</p> + +<p>If the most recent error references a specific token in the input +SQL, the sqlite3_error_offset() interface returns the byte offset +of the start of that token. The byte offset returned by +sqlite3_error_offset() assumes that the input SQL is UTF8. +If the most recent error does not reference a specific token in the input +SQL, then the sqlite3_error_offset() function returns -1.</p> + +<p>When the serialized <a href="threadsafe.html">threading mode</a> is in use, it might be the +case that a second error occurs on a separate thread in between +the time of the first error and the call to these interfaces. +When that happens, the second error will be reported since these +interfaces always report the most recent result. To avoid +this, each thread can obtain exclusive use of the <a href="#sqlite3">database connection</a> D +by invoking <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter</a>(<a href="#sqlite3_db_mutex">sqlite3_db_mutex</a>(D)) before beginning +to use D and invoking <a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave</a>(<a href="#sqlite3_db_mutex">sqlite3_db_mutex</a>(D)) after +all calls to the interfaces listed here are completed.</p> + +<p>If an interface fails with SQLITE_MISUSE, that means the interface +was invoked incorrectly by the application. In that case, the +error code and message may or may not be set. +</p><hr><a name="sqlite3_expanded_sql"></a> +<h2>Retrieving Statement SQL</h2> +</div> +<blockquote><pre> +const char *sqlite3_sql(sqlite3_stmt *pStmt); +char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); +#ifdef SQLITE_ENABLE_NORMALIZE +const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt); +#endif +</pre></blockquote> +<p> +The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 +SQL text used to create <a href="#sqlite3_stmt">prepared statement</a> P if P was +created by <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, +<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>, or <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>. +The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 +string containing the SQL text of prepared statement P with +<a href="lang_expr.html#varparam">bound parameters</a> expanded. +The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8 +string containing the normalized SQL text of prepared statement P. The +semantics used to normalize a SQL statement are unspecified and subject +to change. At a minimum, literal values will be replaced with suitable +placeholders.</p> + +<p>For example, if a prepared statement is created using the SQL +text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 +and parameter :xyz is unbound, then sqlite3_sql() will return +the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() +will return "SELECT 2345,NULL".</p> + +<p>The sqlite3_expanded_sql() interface returns NULL if insufficient memory +is available to hold the result, or if the result would exceed the +the maximum string length determined by the <a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>.</p> + +<p>The <a href="compile.html#trace_size_limit">SQLITE_TRACE_SIZE_LIMIT</a> compile-time option limits the size of +bound parameter expansions. The <a href="compile.html#omit_trace">SQLITE_OMIT_TRACE</a> compile-time +option causes sqlite3_expanded_sql() to always return NULL.</p> + +<p>The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P) +are managed by SQLite and are automatically freed when the prepared +statement is finalized. +The string returned by sqlite3_expanded_sql(P), on the other hand, +is obtained from <a href="#sqlite3_free">sqlite3_malloc()</a> and must be freed by the application +by passing it to <a href="#sqlite3_free">sqlite3_free()</a>.</p> + +<p>The sqlite3_normalized_sql() interface is only available if +the <a href="compile.html#enable_normalize">SQLITE_ENABLE_NORMALIZE</a> compile-time option is defined. +</p><hr><a name="sqlite3_filename_database"></a> +<h2>Translate filenames</h2> +</div> +<blockquote><pre> +const char *sqlite3_filename_database(sqlite3_filename); +const char *sqlite3_filename_journal(sqlite3_filename); +const char *sqlite3_filename_wal(sqlite3_filename); +</pre></blockquote> +<p> +These routines are available to <a href="vfs.html">custom VFS implementations</a> for +translating filenames between the main database file, the journal file, +and the WAL file.</p> + +<p>If F is the name of an sqlite database file, journal file, or WAL file +passed by the SQLite core into the VFS, then sqlite3_filename_database(F) +returns the name of the corresponding database file.</p> + +<p>If F is the name of an sqlite database file, journal file, or WAL file +passed by the SQLite core into the VFS, or if F is a database filename +obtained from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, then sqlite3_filename_journal(F) +returns the name of the corresponding rollback journal file.</p> + +<p>If F is the name of an sqlite database file, journal file, or WAL file +that was passed by the SQLite core into the VFS, or if F is a database +filename obtained from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, then +sqlite3_filename_wal(F) returns the name of the corresponding +WAL file.</p> + +<p>In all of the above, if F is not the name of a database, journal or WAL +filename passed into the VFS from the SQLite core and F is not the +return value from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, then the result is +undefined and is likely a memory access violation. +</p><hr><a name="sqlite3_free"></a> +<h2>Memory Allocation Subsystem</h2> +</div> +<blockquote><pre> +void *sqlite3_malloc(int); +void *sqlite3_malloc64(sqlite3_uint64); +void *sqlite3_realloc(void*, int); +void *sqlite3_realloc64(void*, sqlite3_uint64); +void sqlite3_free(void*); +sqlite3_uint64 sqlite3_msize(void*); +</pre></blockquote> +<p> +The SQLite core uses these three routines for all of its own +internal memory allocation needs. "Core" in the previous sentence +does not include operating-system specific <a href="vfs.html">VFS</a> implementation. The +Windows VFS uses native malloc() and free() for some operations.</p> + +<p>The sqlite3_malloc() routine returns a pointer to a block +of memory at least N bytes in length, where N is the parameter. +If sqlite3_malloc() is unable to obtain sufficient free +memory, it returns a NULL pointer. If the parameter N to +sqlite3_malloc() is zero or negative then sqlite3_malloc() returns +a NULL pointer.</p> + +<p>The sqlite3_malloc64(N) routine works just like +sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead +of a signed 32-bit integer.</p> + +<p>Calling sqlite3_free() with a pointer previously returned +by sqlite3_malloc() or sqlite3_realloc() releases that memory so +that it might be reused. The sqlite3_free() routine is +a no-op if is called with a NULL pointer. Passing a NULL pointer +to sqlite3_free() is harmless. After being freed, memory +should neither be read nor written. Even reading previously freed +memory might result in a segmentation fault or other severe error. +Memory corruption, a segmentation fault, or other severe error +might result if sqlite3_free() is called with a non-NULL pointer that +was not obtained from sqlite3_malloc() or sqlite3_realloc().</p> + +<p>The sqlite3_realloc(X,N) interface attempts to resize a +prior memory allocation X to be at least N bytes. +If the X parameter to sqlite3_realloc(X,N) +is a NULL pointer then its behavior is identical to calling +sqlite3_malloc(N). +If the N parameter to sqlite3_realloc(X,N) is zero or +negative then the behavior is exactly the same as calling +sqlite3_free(X). +sqlite3_realloc(X,N) returns a pointer to a memory allocation +of at least N bytes in size or NULL if insufficient memory is available. +If M is the size of the prior allocation, then min(N,M) bytes +of the prior allocation are copied into the beginning of buffer returned +by sqlite3_realloc(X,N) and the prior allocation is freed. +If sqlite3_realloc(X,N) returns NULL and N is positive, then the +prior allocation is not freed.</p> + +<p>The sqlite3_realloc64(X,N) interfaces works the same as +sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead +of a 32-bit signed integer.</p> + +<p>If X is a memory allocation previously obtained from sqlite3_malloc(), +sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then +sqlite3_msize(X) returns the size of that memory allocation in bytes. +The value returned by sqlite3_msize(X) might be larger than the number +of bytes requested when X was allocated. If X is a NULL pointer then +sqlite3_msize(X) returns zero. If X points to something that is not +the beginning of memory allocation, or if it points to a formerly +valid memory allocation that has now been freed, then the behavior +of sqlite3_msize(X) is undefined and possibly harmful.</p> + +<p>The memory returned by sqlite3_malloc(), sqlite3_realloc(), +sqlite3_malloc64(), and sqlite3_realloc64() +is always aligned to at least an 8 byte boundary, or to a +4 byte boundary if the <a href="compile.html#4_byte_aligned_malloc">SQLITE_4_BYTE_ALIGNED_MALLOC</a> compile-time +option is used.</p> + +<p>The pointer arguments to <a href="#sqlite3_free">sqlite3_free()</a> and <a href="#sqlite3_free">sqlite3_realloc()</a> +must be either NULL or else pointers obtained from a prior +invocation of <a href="#sqlite3_free">sqlite3_malloc()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a> that have +not yet been released.</p> + +<p>The application must not read or write any part of +a block of memory after it has been released using +<a href="#sqlite3_free">sqlite3_free()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a>. +</p><hr><a name="sqlite3_free_table"></a> +<h2>Convenience Routines For Running Queries</h2> +</div> +<blockquote><pre> +int sqlite3_get_table( + sqlite3 *db, /* An open database */ + const char *zSql, /* SQL to be evaluated */ + char ***pazResult, /* Results of the query */ + int *pnRow, /* Number of result rows written here */ + int *pnColumn, /* Number of result columns written here */ + char **pzErrmsg /* Error msg written here */ +); +void sqlite3_free_table(char **result); +</pre></blockquote> +<p> +This is a legacy interface that is preserved for backwards compatibility. +Use of this interface is not recommended.</p> + +<p>Definition: A <b>result table</b> is memory data structure created by the +<a href="#sqlite3_free_table">sqlite3_get_table()</a> interface. A result table records the +complete query results from one or more queries.</p> + +<p>The table conceptually has a number of rows and columns. But +these numbers are not part of the result table itself. These +numbers are obtained separately. Let N be the number of rows +and M be the number of columns.</p> + +<p>A result table is an array of pointers to zero-terminated UTF-8 strings. +There are (N+1)*M elements in the array. The first M pointers point +to zero-terminated strings that contain the names of the columns. +The remaining entries all point to query results. NULL values result +in NULL pointers. All other values are in their UTF-8 zero-terminated +string representation as returned by <a href="#sqlite3_column_blob">sqlite3_column_text()</a>.</p> + +<p>A result table might consist of one or more memory allocations. +It is not safe to pass a result table directly to <a href="#sqlite3_free">sqlite3_free()</a>. +A result table should be deallocated using <a href="#sqlite3_free_table">sqlite3_free_table()</a>.</p> + +<p>As an example of the result table format, suppose a query result +is as follows:</p> + +<p><blockquote><pre> +Name | Age +----------------------- +Alice | 43 +Bob | 28 +Cindy | 21 +</pre></blockquote></p> + +<p>There are two columns (M==2) and three rows (N==3). Thus the +result table has 8 entries. Suppose the result table is stored +in an array named azResult. Then azResult holds this content:</p> + +<p><blockquote><pre> +azResult[0] = "Name"; +azResult[1] = "Age"; +azResult[2] = "Alice"; +azResult[3] = "43"; +azResult[4] = "Bob"; +azResult[5] = "28"; +azResult[6] = "Cindy"; +azResult[7] = "21"; +</pre></blockquote></p> + +<p>The sqlite3_get_table() function evaluates one or more +semicolon-separated SQL statements in the zero-terminated UTF-8 +string of its 2nd parameter and returns a result table to the +pointer given in its 3rd parameter.</p> + +<p>After the application has finished with the result from sqlite3_get_table(), +it must pass the result table pointer to sqlite3_free_table() in order to +release the memory that was malloced. Because of the way the +<a href="#sqlite3_free">sqlite3_malloc()</a> happens within sqlite3_get_table(), the calling +function must not try to call <a href="#sqlite3_free">sqlite3_free()</a> directly. Only +<a href="#sqlite3_free_table">sqlite3_free_table()</a> is able to release the memory properly and safely.</p> + +<p>The sqlite3_get_table() interface is implemented as a wrapper around +<a href="#sqlite3_exec">sqlite3_exec()</a>. The sqlite3_get_table() routine does not have access +to any internal data structures of SQLite. It uses only the public +interface defined here. As a consequence, errors that occur in the +wrapper layer outside of the internal <a href="#sqlite3_exec">sqlite3_exec()</a> call are not +reflected in subsequent calls to <a href="#sqlite3_errcode">sqlite3_errcode()</a> or +<a href="#sqlite3_errcode">sqlite3_errmsg()</a>. +</p><hr><a name="sqlite3_get_auxdata"></a> +<h2>Function Auxiliary Data</h2> +</div> +<blockquote><pre> +void *sqlite3_get_auxdata(sqlite3_context*, int N); +void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); +</pre></blockquote> +<p> +These functions may be used by (non-aggregate) SQL functions to +associate auxiliary data with argument values. If the same argument +value is passed to multiple invocations of the same SQL function during +query execution, under some circumstances the associated auxiliary data +might be preserved. An example of where this might be useful is in a +regular-expression matching function. The compiled version of the regular +expression can be stored as auxiliary data associated with the pattern string. +Then as long as the pattern string remains the same, +the compiled regular expression can be reused on multiple +invocations of the same function.</p> + +<p>The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary data +associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument +value to the application-defined function. N is zero for the left-most +function argument. If there is no auxiliary data +associated with the function argument, the sqlite3_get_auxdata(C,N) interface +returns a NULL pointer.</p> + +<p>The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the +N-th argument of the application-defined function. Subsequent +calls to sqlite3_get_auxdata(C,N) return P from the most recent +sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or +NULL if the auxiliary data has been discarded. +After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, +SQLite will invoke the destructor function X with parameter P exactly +once, when the auxiliary data is discarded. +SQLite is free to discard the auxiliary data at any time, including: <ul> +<li> when the corresponding function parameter changes, or +<li> when <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a> is called for the +SQL statement, or +<li> when sqlite3_set_auxdata() is invoked again on the same +parameter, or +<li> during the original sqlite3_set_auxdata() call when a memory +allocation error occurs. +<li> during the original sqlite3_set_auxdata() call if the function +is evaluated during query planning instead of during query execution, +as sometimes happens with <a href="compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a>. </ul></p> + +<p>Note the last two bullets in particular. The destructor X in +sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the +sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() +should be called near the end of the function implementation and the +function implementation should not make any use of P after +sqlite3_set_auxdata() has been called. Furthermore, a call to +sqlite3_get_auxdata() that occurs immediately after a corresponding call +to sqlite3_set_auxdata() might still return NULL if an out-of-memory +condition occurred during the sqlite3_set_auxdata() call or if the +function is being evaluated during query planning rather than during +query execution.</p> + +<p>In practice, auxiliary data is preserved between function calls for +function parameters that are compile-time constants, including literal +values and <a href="lang_expr.html#varparam">parameters</a> and expressions composed from the same.</p> + +<p>The value of the N parameter to these interfaces should be non-negative. +Future enhancements may make use of negative N values to define new +kinds of function caching behavior.</p> + +<p>These routines must be called from the same thread in which +the SQL function is running.</p> + +<p>See also: <a href="#sqlite3_get_clientdata">sqlite3_get_clientdata()</a> and <a href="#sqlite3_get_clientdata">sqlite3_set_clientdata()</a>. +</p><hr><a name="sqlite3_get_clientdata"></a> +<h2>Database Connection Client Data</h2> +</div> +<blockquote><pre> +void *sqlite3_get_clientdata(sqlite3*,const char*); +int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*)); +</pre></blockquote> +<p> +These functions are used to associate one or more named pointers +with a <a href="#sqlite3">database connection</a>. +A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P +to be attached to <a href="#sqlite3">database connection</a> D using name N. Subsequent +calls to sqlite3_get_clientdata(D,N) will return a copy of pointer P +or a NULL pointer if there were no prior calls to +sqlite3_set_clientdata() with the same values of D and N. +Names are compared using strcmp() and are thus case sensitive.</p> + +<p>If P and X are both non-NULL, then the destructor X is invoked with +argument P on the first of the following occurrences: +<ul> +<li> An out-of-memory error occurs during the call to +sqlite3_set_clientdata() which attempts to register pointer P. +<li> A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made +with the same D and N parameters. +<li> The database connection closes. SQLite does not make any guarantees +about the order in which destructors are called, only that all +destructors will be called exactly once at some point during the +database connection closing process. +</ul></p> + +<p>SQLite does not do anything with client data other than invoke +destructors on the client data at the appropriate time. The intended +use for client data is to provide a mechanism for wrapper libraries +to store additional information about an SQLite database connection.</p> + +<p>There is no limit (other than available memory) on the number of different +client data pointers (with different names) that can be attached to a +single database connection. However, the implementation is optimized +for the case of having only one or two different client data names. +Applications and wrapper libraries are discouraged from using more than +one client data name each.</p> + +<p>There is no way to enumerate the client data pointers +associated with a database connection. The N parameter can be thought +of as a secret key such that only code that knows the secret key is able +to access the associated data.</p> + +<p>Security Warning: These interfaces should not be exposed in scripting +languages or in other circumstances where it might be possible for an +an attacker to invoke them. Any agent that can invoke these interfaces +can probably also take control of the process.</p> + +<p>Database connection client data is only available for SQLite +version 3.44.0 (2023-11-01) and later.</p> + +<p>See also: <a href="#sqlite3_get_auxdata">sqlite3_set_auxdata()</a> and <a href="#sqlite3_get_auxdata">sqlite3_get_auxdata()</a>. +</p><hr><a name="sqlite3_hard_heap_limit64"></a> +<h2>Impose A Limit On Heap Size</h2> +</div> +<blockquote><pre> +sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); +sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N); +</pre></blockquote> +<p> +These interfaces impose limits on the amount of heap memory that will be +by all database connections within a single process.</p> + +<p>The sqlite3_soft_heap_limit64() interface sets and/or queries the +soft limit on the amount of heap memory that may be allocated by SQLite. +SQLite strives to keep heap memory utilization below the soft heap +limit by reducing the number of pages held in the page cache +as heap memory usages approaches the limit. +The soft heap limit is "soft" because even though SQLite strives to stay +below the limit, it will exceed the limit rather than generate +an <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> error. In other words, the soft heap limit +is advisory only.</p> + +<p>The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of +N bytes on the amount of memory that will be allocated. The +sqlite3_hard_heap_limit64(N) interface is similar to +sqlite3_soft_heap_limit64(N) except that memory allocations will fail +when the hard heap limit is reached.</p> + +<p>The return value from both sqlite3_soft_heap_limit64() and +sqlite3_hard_heap_limit64() is the size of +the heap limit prior to the call, or negative in the case of an +error. If the argument N is negative +then no change is made to the heap limit. Hence, the current +size of heap limits can be determined by invoking +sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).</p> + +<p>Setting the heap limits to zero disables the heap limiter mechanism.</p> + +<p>The soft heap limit may not be greater than the hard heap limit. +If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) +is invoked with a value of N that is greater than the hard heap limit, +the soft heap limit is set to the value of the hard heap limit. +The soft heap limit is automatically enabled whenever the hard heap +limit is enabled. When sqlite3_hard_heap_limit64(N) is invoked and +the soft heap limit is outside the range of 1..N, then the soft heap +limit is set to N. Invoking sqlite3_soft_heap_limit64(0) when the +hard heap limit is enabled makes the soft heap limit equal to the +hard heap limit.</p> + +<p>The memory allocation limits can also be adjusted using +<a href="pragma.html#pragma_soft_heap_limit">PRAGMA soft_heap_limit</a> and <a href="pragma.html#pragma_hard_heap_limit">PRAGMA hard_heap_limit</a>.</p> + +<p>The heap limits are not enforced in the current implementation +if one or more of following conditions are true:</p> + +<p><ul> +<li> The limit value is set to zero. +<li> Memory accounting is disabled using a combination of the +<a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a>,...) start-time option and +the <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a> compile-time option. +<li> An alternative page cache implementation is specified using +<a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>,...). +<li> The page cache allocates from its own memory pool supplied +by <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>,...) rather than +from the heap. +</ul></p> + +<p>The circumstances under which SQLite will enforce the heap limits may +changes in future releases of SQLite. +</p><hr><a name="sqlite3_initialize"></a> +<h2>Initialize The SQLite Library</h2> +</div> +<blockquote><pre> +int sqlite3_initialize(void); +int sqlite3_shutdown(void); +int sqlite3_os_init(void); +int sqlite3_os_end(void); +</pre></blockquote> +<p> +The sqlite3_initialize() routine initializes the +SQLite library. The sqlite3_shutdown() routine +deallocates any resources that were allocated by sqlite3_initialize(). +These routines are designed to aid in process initialization and +shutdown on embedded systems. Workstation applications using +SQLite normally do not need to invoke either of these routines.</p> + +<p>A call to sqlite3_initialize() is an "effective" call if it is +the first time sqlite3_initialize() is invoked during the lifetime of +the process, or if it is the first time sqlite3_initialize() is invoked +following a call to sqlite3_shutdown(). Only an effective call +of sqlite3_initialize() does any initialization. All other calls +are harmless no-ops.</p> + +<p>A call to sqlite3_shutdown() is an "effective" call if it is the first +call to sqlite3_shutdown() since the last sqlite3_initialize(). Only +an effective call to sqlite3_shutdown() does any deinitialization. +All other valid calls to sqlite3_shutdown() are harmless no-ops.</p> + +<p>The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() +is not. The sqlite3_shutdown() interface must only be called from a +single thread. All open <a href="#sqlite3">database connections</a> must be closed and all +other SQLite resources must be deallocated prior to invoking +sqlite3_shutdown().</p> + +<p>Among other things, sqlite3_initialize() will invoke +sqlite3_os_init(). Similarly, sqlite3_shutdown() +will invoke sqlite3_os_end().</p> + +<p>The sqlite3_initialize() routine returns <a href="#SQLITE_ABORT">SQLITE_OK</a> on success. +If for some reason, sqlite3_initialize() is unable to initialize +the library (perhaps it is unable to allocate a needed resource such +as a mutex) it returns an <a href="rescode.html">error code</a> other than <a href="#SQLITE_ABORT">SQLITE_OK</a>.</p> + +<p>The sqlite3_initialize() routine is called internally by many other +SQLite interfaces so that an application usually does not need to +invoke sqlite3_initialize() directly. For example, <a href="#sqlite3_open">sqlite3_open()</a> +calls sqlite3_initialize() so the SQLite library will be automatically +initialized when <a href="#sqlite3_open">sqlite3_open()</a> is called if it has not be initialized +already. However, if SQLite is compiled with the <a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a> +compile-time option, then the automatic calls to sqlite3_initialize() +are omitted and the application must call sqlite3_initialize() directly +prior to using any other SQLite interface. For maximum portability, +it is recommended that applications always invoke sqlite3_initialize() +directly prior to using any other SQLite interface. Future releases +of SQLite may require this. In other words, the behavior exhibited +when SQLite is compiled with <a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a> might become the +default behavior in some future release of SQLite.</p> + +<p>The sqlite3_os_init() routine does operating-system specific +initialization of the SQLite library. The sqlite3_os_end() +routine undoes the effect of sqlite3_os_init(). Typical tasks +performed by these routines include allocation or deallocation +of static resources, initialization of global variables, +setting up a default <a href="#sqlite3_vfs">sqlite3_vfs</a> module, or setting up +a default configuration using <a href="#sqlite3_config">sqlite3_config()</a>.</p> + +<p>The application should never invoke either sqlite3_os_init() +or sqlite3_os_end() directly. The application should only invoke +sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() +interface is called automatically by sqlite3_initialize() and +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 <a href="custombuild.html">built for other platforms</a> +(using the <a href="compile.html#os_other">SQLITE_OS_OTHER=1</a> 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() +must return <a href="#SQLITE_ABORT">SQLITE_OK</a> on success and some other <a href="rescode.html">error code</a> upon +failure. +</p><hr><a name="sqlite3_interrupt"></a> +<h2>Interrupt A Long-Running Query</h2> +</div> +<blockquote><pre> +void sqlite3_interrupt(sqlite3*); +int sqlite3_is_interrupted(sqlite3*); +</pre></blockquote> +<p> +This function causes any pending database operation to abort and +return at its earliest opportunity. This routine is typically +called in response to a user action such as pressing "Cancel" +or Ctrl-C where the user wants a long query operation to halt +immediately.</p> + +<p>It is safe to call this routine from a thread different from the +thread that is currently running the database operation. But it +is not safe to call this routine with a <a href="#sqlite3">database connection</a> that +is closed or might close before sqlite3_interrupt() returns.</p> + +<p>If an SQL operation is very nearly finished at the time when +sqlite3_interrupt() is called, then it might not have an opportunity +to be interrupted and might continue to completion.</p> + +<p>An SQL operation that is interrupted will return <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>. +If the interrupted SQL operation is an INSERT, UPDATE, or DELETE +that is inside an explicit transaction, then the entire transaction +will be rolled back automatically.</p> + +<p>The sqlite3_interrupt(D) call is in effect until all currently running +SQL statements on <a href="#sqlite3">database connection</a> D complete. Any new SQL statements +that are started after the sqlite3_interrupt() call and before the +running statement count reaches zero are interrupted as if they had been +running prior to the sqlite3_interrupt() call. New SQL statements +that are started after the running statement count reaches zero are +not effected by the sqlite3_interrupt(). +A call to sqlite3_interrupt(D) that occurs when there are no running +SQL statements is a no-op and has no effect on SQL statements +that are started after the sqlite3_interrupt() call returns.</p> + +<p>The <a href="#sqlite3_interrupt">sqlite3_is_interrupted(D)</a> interface can be used to determine whether +or not an interrupt is currently in effect for <a href="#sqlite3">database connection</a> D. +It returns 1 if an interrupt is currently in effect, or 0 otherwise. +</p><hr><a name="sqlite3_keyword_check"></a> +<h2>SQL Keyword Checking</h2> +</div> +<blockquote><pre> +int sqlite3_keyword_count(void); +int sqlite3_keyword_name(int,const char**,int*); +int sqlite3_keyword_check(const char*,int); +</pre></blockquote> +<p> +These routines provide access to the set of SQL language keywords +recognized by SQLite. Applications can uses these routines to determine +whether or not a specific identifier needs to be escaped (for example, +by enclosing in double-quotes) so as not to confuse the parser.</p> + +<p>The sqlite3_keyword_count() interface returns the number of distinct +keywords understood by SQLite.</p> + +<p>The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and +makes *Z point to that keyword expressed as UTF8 and writes the number +of bytes in the keyword into *L. The string that *Z points to is not +zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns +SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z +or L are NULL or invalid pointers then calls to +sqlite3_keyword_name(N,Z,L) result in undefined behavior.</p> + +<p>The sqlite3_keyword_check(Z,L) interface checks to see whether or not +the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero +if it is and zero if not.</p> + +<p>The parser used by SQLite is forgiving. It is often possible to use +a keyword as an identifier as long as such use does not result in a +parsing ambiguity. For example, the statement +"CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and +creates a new table named "BEGIN" with three columns named +"REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid +using keywords as identifiers. Common techniques used to avoid keyword +name collisions include: +<ul> +<li> Put all identifier names inside double-quotes. This is the official +SQL way to escape identifier names. +<li> Put identifier names inside [...]. This is not standard SQL, +but it is what SQL Server does and so lots of programmers use this +technique. +<li> Begin every identifier with the letter "Z" as no SQL keywords start +with "Z". +<li> Include a digit somewhere in every identifier name. +</ul></p> + +<p>Note that the number of keywords understood by SQLite can depend on +compile-time options. For example, "VACUUM" is not a keyword if +SQLite is compiled with the <a href="compile.html#omit_vacuum">-DSQLITE_OMIT_VACUUM</a> option. Also, +new keywords may be added to future releases of SQLite. +</p><hr><a name="sqlite3_libversion"></a> +<h2>Run-Time Library Version Numbers</h2> +</div> +<blockquote><pre> +SQLITE_EXTERN const char sqlite3_version[]; +const char *sqlite3_libversion(void); +const char *sqlite3_sourceid(void); +int sqlite3_libversion_number(void); +</pre></blockquote> +<p> +These interfaces provide the same information as the <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a>, +<a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a>, and <a href="#SQLITE_SOURCE_ID">SQLITE_SOURCE_ID</a> C preprocessor macros +but are associated with the library instead of the header file. Cautious +programmers might include assert() statements in their application to +verify that values returned by these interfaces match the macros in +the header, and thus ensure that the application is +compiled with matching library and header files.</p> + +<p><blockquote><pre> +assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); +assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 ); +assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); +</pre></blockquote></p> + +<p>The sqlite3_version[] string constant contains the text of <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a> +macro. The sqlite3_libversion() function returns a pointer to the +to the sqlite3_version[] string constant. The sqlite3_libversion() +function is provided for use in DLLs since DLL users usually do not have +direct access to string constants within the DLL. The +sqlite3_libversion_number() function returns an integer equal to +<a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a>. The sqlite3_sourceid() function returns +a pointer to a string constant whose value is the same as the +<a href="#SQLITE_SOURCE_ID">SQLITE_SOURCE_ID</a> C preprocessor macro. Except if SQLite is built +using an edited copy of <a href="amalgamation.html">the amalgamation</a>, then the last four characters +of the hash might be different from <a href="#SQLITE_SOURCE_ID">SQLITE_SOURCE_ID</a>.</p> + +<p>See also: <a href="lang_corefunc.html#sqlite_version">sqlite_version()</a> and <a href="lang_corefunc.html#sqlite_source_id">sqlite_source_id()</a>. +</p><hr><a name="sqlite3_memory_highwater"></a> +<h2>Memory Allocator Statistics</h2> +</div> +<blockquote><pre> +sqlite3_int64 sqlite3_memory_used(void); +sqlite3_int64 sqlite3_memory_highwater(int resetFlag); +</pre></blockquote> +<p> +SQLite provides these two interfaces for reporting on the status +of the <a href="#sqlite3_free">sqlite3_malloc()</a>, <a href="#sqlite3_free">sqlite3_free()</a>, and <a href="#sqlite3_free">sqlite3_realloc()</a> +routines, which form the built-in memory allocation subsystem.</p> + +<p>The <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> routine returns the number of bytes +of memory currently outstanding (malloced but not freed). +The <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> routine returns the maximum +value of <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> since the high-water mark +was last reset. The values returned by <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> and +<a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> include any overhead +added by SQLite in its implementation of <a href="#sqlite3_free">sqlite3_malloc()</a>, +but not overhead added by the any underlying system library +routines that <a href="#sqlite3_free">sqlite3_malloc()</a> may call.</p> + +<p>The memory high-water mark is reset to the current value of +<a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> if and only if the parameter to +<a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> is true. The value returned +by <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater(1)</a> is the high-water mark +prior to the reset. +</p><hr><a name="sqlite3_mprintf"></a> +<h2>Formatted String Printing Functions</h2> +</div> +<blockquote><pre> +char *sqlite3_mprintf(const char*,...); +char *sqlite3_vmprintf(const char*, va_list); +char *sqlite3_snprintf(int,char*,const char*, ...); +char *sqlite3_vsnprintf(int,char*,const char*, va_list); +</pre></blockquote> +<p> +These routines are work-alikes of the "printf()" family of functions +from the standard C library. +These routines understand most of the common formatting options from +the standard library printf() +plus some additional non-standard formats (<a href="printf.html#percentq">%q</a>, <a href="printf.html#percentq">%Q</a>, <a href="printf.html#percentw">%w</a>, and <a href="printf.html#percentz">%z</a>). +See the <a href="printf.html">built-in printf()</a> documentation for details.</p> + +<p>The sqlite3_mprintf() and sqlite3_vmprintf() routines write their +results into memory obtained from <a href="#sqlite3_free">sqlite3_malloc64()</a>. +The strings returned by these two routines should be +released by <a href="#sqlite3_free">sqlite3_free()</a>. Both routines return a +NULL pointer if <a href="#sqlite3_free">sqlite3_malloc64()</a> is unable to allocate enough +memory to hold the resulting string.</p> + +<p>The sqlite3_snprintf() routine is similar to "snprintf()" from +the standard C library. The result is written into the +buffer supplied as the second parameter whose size is given by +the first parameter. Note that the order of the +first two parameters is reversed from snprintf(). This is an +historical accident that cannot be fixed without breaking +backwards compatibility. Note also that sqlite3_snprintf() +returns a pointer to its buffer instead of the number of +characters actually written into the buffer. We admit that +the number of characters written would be a more useful return +value but we cannot change the implementation of sqlite3_snprintf() +now without breaking compatibility.</p> + +<p>As long as the buffer size is greater than zero, sqlite3_snprintf() +guarantees that the buffer is always zero-terminated. The first +parameter "n" is the total size of the buffer, including space for +the zero terminator. So the longest string that can be completely +written will be n-1 characters.</p> + +<p>The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().</p> + +<p>See also: <a href="printf.html">built-in printf()</a>, <a href="lang_corefunc.html#printf">printf() SQL function</a> +</p><hr><a name="sqlite3_mutex_alloc"></a> +<h2>Mutexes</h2> +</div> +<blockquote><pre> +sqlite3_mutex *sqlite3_mutex_alloc(int); +void sqlite3_mutex_free(sqlite3_mutex*); +void sqlite3_mutex_enter(sqlite3_mutex*); +int sqlite3_mutex_try(sqlite3_mutex*); +void sqlite3_mutex_leave(sqlite3_mutex*); +</pre></blockquote> +<p> +The SQLite core uses these routines for thread +synchronization. Though they are intended for internal +use by SQLite, code that links against SQLite is +permitted to use any of these routines.</p> + +<p>The SQLite source code contains multiple implementations +of these mutex routines. An appropriate implementation +is selected automatically at compile-time. The following +implementations are available in the SQLite core:</p> + +<p><ul> +<li> SQLITE_MUTEX_PTHREADS +<li> SQLITE_MUTEX_W32 +<li> SQLITE_MUTEX_NOOP +</ul></p> + +<p>The SQLITE_MUTEX_NOOP implementation is a set of routines +that does no real locking and is appropriate for use in +a single-threaded application. The SQLITE_MUTEX_PTHREADS and +SQLITE_MUTEX_W32 implementations are appropriate for use on Unix +and Windows.</p> + +<p>If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor +macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex +implementation is included with the library. In this case the +application must supply a custom mutex implementation using the +<a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option of the sqlite3_config() function +before calling sqlite3_initialize() or any other public sqlite3_ +function that calls sqlite3_initialize().</p> + +<p>The sqlite3_mutex_alloc() routine allocates a new +mutex and returns a pointer to it. The sqlite3_mutex_alloc() +routine returns NULL if it is unable to allocate the requested +mutex. The argument to sqlite3_mutex_alloc() must one of these +integer constants:</p> + +<p><ul> +<li> SQLITE_MUTEX_FAST +<li> SQLITE_MUTEX_RECURSIVE +<li> SQLITE_MUTEX_STATIC_MAIN +<li> SQLITE_MUTEX_STATIC_MEM +<li> SQLITE_MUTEX_STATIC_OPEN +<li> SQLITE_MUTEX_STATIC_PRNG +<li> SQLITE_MUTEX_STATIC_LRU +<li> SQLITE_MUTEX_STATIC_PMEM +<li> SQLITE_MUTEX_STATIC_APP1 +<li> SQLITE_MUTEX_STATIC_APP2 +<li> SQLITE_MUTEX_STATIC_APP3 +<li> SQLITE_MUTEX_STATIC_VFS1 +<li> SQLITE_MUTEX_STATIC_VFS2 +<li> SQLITE_MUTEX_STATIC_VFS3 +</ul></p> + +<p>The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) +cause sqlite3_mutex_alloc() to create +a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE +is used but not necessarily so when SQLITE_MUTEX_FAST is used. +The mutex implementation does not need to make a distinction +between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does +not want to. SQLite will only request a recursive mutex in +cases where it really needs one. If a faster non-recursive mutex +implementation is available on the host platform, the mutex subsystem +might return such a mutex in response to SQLITE_MUTEX_FAST.</p> + +<p>The other allowed parameters to sqlite3_mutex_alloc() (anything other +than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return +a pointer to a static preexisting mutex. Nine static mutexes are +used by the current version of SQLite. Future versions of SQLite +may add additional static mutexes. Static mutexes are for internal +use by SQLite only. Applications that use SQLite mutexes should +use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or +SQLITE_MUTEX_RECURSIVE.</p> + +<p>Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST +or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() +returns a different mutex on every call. For the static +mutex types, the same mutex is returned on every call that has +the same type number.</p> + +<p>The sqlite3_mutex_free() routine deallocates a previously +allocated dynamic mutex. Attempting to deallocate a static +mutex results in undefined behavior.</p> + +<p>The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt +to enter a mutex. If another thread is already within the mutex, +sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return +SQLITE_BUSY. The sqlite3_mutex_try() interface returns <a href="#SQLITE_ABORT">SQLITE_OK</a> +upon successful entry. Mutexes created using +SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. +In such cases, the +mutex must be exited an equal number of times before another thread +can enter. If the same thread tries to enter any mutex other +than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.</p> + +<p>Some systems (for example, Windows 95) do not support the operation +implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() +will always return SQLITE_BUSY. In most cases the SQLite core only uses +sqlite3_mutex_try() as an optimization, so this is acceptable +behavior. The exceptions are unix builds that set the +SQLITE_ENABLE_SETLK_TIMEOUT build option. In that case a working +sqlite3_mutex_try() is required.</p> + +<p>The sqlite3_mutex_leave() routine exits a mutex that was +previously entered by the same thread. The behavior +is undefined if the mutex is not currently entered by the +calling thread or is not currently allocated.</p> + +<p>If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), +sqlite3_mutex_leave(), or sqlite3_mutex_free() is a NULL pointer, +then any of the four routines behaves as a no-op.</p> + +<p>See also: <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> and <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a>. +</p><hr><a name="sqlite3_mutex_held"></a> +<h2>Mutex Verification Routines</h2> +</div> +<blockquote><pre> +#ifndef NDEBUG +int sqlite3_mutex_held(sqlite3_mutex*); +int sqlite3_mutex_notheld(sqlite3_mutex*); +#endif +</pre></blockquote> +<p> +The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines +are intended for use inside assert() statements. The SQLite core +never uses these routines except inside an assert() and applications +are advised to follow the lead of the core. The SQLite core only +provides implementations for these routines when it is compiled +with the SQLITE_DEBUG flag. External mutex implementations +are only required to provide these routines if SQLITE_DEBUG is +defined and if NDEBUG is not defined.</p> + +<p>These routines should return true if the mutex in their argument +is held or not held, respectively, by the calling thread.</p> + +<p>The implementation is not required to provide 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.</p> + +<p>If the argument to sqlite3_mutex_held() is a NULL pointer then +the routine should return 1. This seems counter-intuitive since +clearly the mutex cannot be held if it does not exist. But +the reason the mutex does not exist is because the build is not +using mutexes. And we do not want the assert() containing the +call to sqlite3_mutex_held() to fail, so a non-zero return is +the appropriate thing to do. The sqlite3_mutex_notheld() +interface should also return 1 when given a NULL pointer. +</p><hr><a name="sqlite3_open"></a> +<h2>Opening A New Database Connection</h2> +</div> +<blockquote><pre> +int sqlite3_open( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +int sqlite3_open16( + const void *filename, /* Database filename (UTF-16) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +int sqlite3_open_v2( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb, /* OUT: SQLite db handle */ + int flags, /* Flags */ + const char *zVfs /* Name of VFS module to use */ +); +</pre></blockquote> +<p> +These routines open an SQLite database file as specified by the +filename argument. The filename argument is interpreted as UTF-8 for +sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte +order for sqlite3_open16(). A <a href="#sqlite3">database connection</a> handle is usually +returned in *ppDb, even if an error occurs. The only exception is that +if SQLite is unable to allocate memory to hold the <a href="#sqlite3">sqlite3</a> object, +a NULL will be written into *ppDb instead of a pointer to the <a href="#sqlite3">sqlite3</a> +object. If the database is opened (and/or created) successfully, then +<a href="#SQLITE_ABORT">SQLITE_OK</a> is returned. Otherwise an <a href="rescode.html">error code</a> is returned. The +<a href="#sqlite3_errcode">sqlite3_errmsg()</a> or <a href="#sqlite3_errcode">sqlite3_errmsg16()</a> routines can be used to obtain +an English language description of the error following a failure of any +of the sqlite3_open() routines.</p> + +<p>The default encoding will be UTF-8 for databases created using +sqlite3_open() or sqlite3_open_v2(). The default encoding for databases +created using sqlite3_open16() will be UTF-16 in the native byte order.</p> + +<p>Whether or not an error occurs when it is opened, resources +associated with the <a href="#sqlite3">database connection</a> handle should be released by +passing it to <a href="#sqlite3_close">sqlite3_close()</a> when it is no longer required.</p> + +<p>The sqlite3_open_v2() interface works like sqlite3_open() +except that it accepts two additional parameters for additional control +over the new database connection. The flags parameter to +sqlite3_open_v2() must include, at a minimum, one of the following +three flag combinations:</p> + +<p><dl> +<dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a></dt> +<dd>The database is opened in read-only mode. If the database does +not already exist, an error is returned.</dd></p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a></dt> +<dd>The database is opened for reading and writing if possible, or +reading only if the file is write protected by the operating +system. In either case the database must already exist, otherwise +an error is returned. For historical reasons, if opening in +read-write mode fails due to OS-level permissions, an attempt is +made to open it in read-only mode. <a href="#sqlite3_db_readonly">sqlite3_db_readonly()</a> can be +used to determine whether the database is actually +read-write.</dd></p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a> | <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a></dt> +<dd>The database is opened for reading and writing, and is created if +it does not already exist. This is the behavior that is always used for +sqlite3_open() and sqlite3_open16().</dd> +</dl></p> + +<p>In addition to the required flags, the following optional flags are +also supported:</p> + +<p><dl> +<dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a></dt> +<dd>The filename can be interpreted as a URI if this flag is set.</dd></p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MEMORY</a></dt> +<dd>The database will be opened as an in-memory database. The database +is named by the "filename" argument for the purposes of cache-sharing, +if shared cache mode is enabled, but the "filename" is otherwise ignored. +</dd></p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOMUTEX</a></dt> +<dd>The new database connection will use the "multi-thread" +<a href="threadsafe.html">threading mode</a>. This means that separate threads are allowed +to use SQLite at the same time, as long as each thread is using +a different <a href="#sqlite3">database connection</a>.</p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_FULLMUTEX</a></dt> +<dd>The new database connection will use the "serialized" +<a href="threadsafe.html">threading mode</a>. This means the multiple threads can safely +attempt to use the same database connection at the same time. +(Mutexes will block any actual concurrency, but in this mode +there is no harm in trying.)</p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a></dt> +<dd>The database is opened <a href="sharedcache.html">shared cache</a> enabled, overriding +the default shared cache setting provided by +<a href="#sqlite3_enable_shared_cache">sqlite3_enable_shared_cache()</a>. +The <a href="sharedcache.html#dontuse">use of shared cache mode is discouraged</a> and hence shared cache +capabilities may be omitted from many builds of SQLite. In such cases, +this option is a no-op.</p> + +<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_PRIVATECACHE</a></dt> +<dd>The database is opened <a href="sharedcache.html">shared cache</a> disabled, overriding +the default shared cache setting provided by +<a href="#sqlite3_enable_shared_cache">sqlite3_enable_shared_cache()</a>.</p> + +<p><a name="openexrescode"></a> + <dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXRESCODE</a></dt> +<dd>The database connection comes up in "extended result code mode". +In other words, the database behaves has if +<a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes(db,1)</a> where called on the database +connection as soon as the connection is created. In addition to setting +the extended result code mode, this flag also causes <a href="#sqlite3_open">sqlite3_open_v2()</a> +to return an extended result code.</dd></p> + +<p><a name="opennofollow"></a> + <dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOFOLLOW</a></dt> +<dd>The database filename is not allowed to contain a symbolic link</dd> +</dl></p> + +<p>If the 3rd parameter to sqlite3_open_v2() is not one of the +required combinations shown above optionally combined with other +<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_* bits</a> +then the behavior is undefined. Historic versions of SQLite +have silently ignored surplus bits in the flags parameter to +sqlite3_open_v2(), however that behavior might not be carried through +into future versions of SQLite and so applications should not rely +upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op +for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause +the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE +flag is intended for use by the <a href="#sqlite3_vfs">VFS interface</a> only, and not +by sqlite3_open_v2().</p> + +<p>The fourth parameter to sqlite3_open_v2() is the name of the +<a href="#sqlite3_vfs">sqlite3_vfs</a> object that defines the operating system interface that +the new database connection should use. If the fourth parameter is +a NULL pointer then the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object is used.</p> + +<p>If the filename is ":memory:", then a private, temporary in-memory database +is created for the connection. This in-memory database will vanish when +the database connection is closed. Future versions of SQLite might +make use of additional special filenames that begin with the ":" character. +It is recommended that when a database filename actually does begin with +a ":" character you should prefix the filename with a pathname such as +"./" to avoid ambiguity.</p> + +<p>If the filename is an empty string, then a private, temporary +on-disk database will be created. This private database will be +automatically deleted as soon as the database connection is closed.</p> + +<p><a name="urifilenamesinsqlite3open"></a> + <h3>URI Filenames</h3></p> + +<p>If <a href="uri.html">URI filename</a> interpretation is enabled, and the filename argument +begins with "file:", then the filename is interpreted as a URI. URI +filename interpretation is enabled if the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flag is +set in the third argument to sqlite3_open_v2(), or if it has +been enabled globally using the <a href="#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the +<a href="#sqlite3_config">sqlite3_config()</a> method or by the <a href="compile.html#use_uri">SQLITE_USE_URI</a> compile-time option. +URI filename interpretation is turned off +by default, but future releases of SQLite might enable URI filename +interpretation by default. See "<a href="uri.html">URI filenames</a>" for additional +information.</p> + +<p>URI filenames are parsed according to RFC 3986. If the URI contains an +authority, then it must be either an empty string or the string +"localhost". If the authority is not an empty string or "localhost", an +error is returned to the caller. The fragment component of a URI, if +present, is ignored.</p> + +<p>SQLite uses the path component of the URI as the name of the disk file +which contains the database. If the path begins with a '/' character, +then it is interpreted as an absolute path. If the path does not begin +with a '/' (meaning that the authority section is omitted from the URI) +then the path is interpreted as a relative path. +On windows, the first component of an absolute path +is a drive specification (e.g. "C:").</p> + +<p><a name="coreuriqueryparameters"></a> + +The query component of a URI may contain parameters that are interpreted +either by SQLite itself, or by a <a href="vfs.html">custom VFS implementation</a>. +SQLite and its built-in <a href="vfs.html">VFSes</a> interpret the +following query parameters:</p> + +<p><ul> +<li> <b>vfs</b>: The "vfs" parameter may be used to specify the name of +a VFS object that provides the operating system interface that should +be used to access the database file on disk. If this option is set to +an empty string the default VFS object is used. Specifying an unknown +VFS is an error. If sqlite3_open_v2() is used and the vfs option is +present, then the VFS specified by the option takes precedence over +the value passed as the fourth parameter to sqlite3_open_v2().</p> + +<p><li> <b>mode</b>: The mode parameter may be set to either "ro", "rw", +"rwc", or "memory". Attempting to set it to any other value is +an error. +If "ro" is specified, then the database is opened for read-only +access, just as if the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a> flag had been set in the +third argument to sqlite3_open_v2(). If the mode option is set to +"rw", then the database is opened for read-write (but not create) +access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had +been set. Value "rwc" is equivalent to setting both +SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If the mode option is +set to "memory" then a pure <a href="inmemorydb.html">in-memory database</a> that never reads +or writes from disk is used. It is an error to specify a value for +the mode parameter that is less restrictive than that specified by +the flags passed in the third parameter to sqlite3_open_v2().</p> + +<p><li> <b>cache</b>: The cache parameter may be set to either "shared" or +"private". Setting it to "shared" is equivalent to setting the +SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to +sqlite3_open_v2(). Setting the cache parameter to "private" is +equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. +If sqlite3_open_v2() is used and the "cache" parameter is present in +a URI filename, its value overrides any behavior requested by setting +SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.</p> + +<p><li> <b>psow</b>: The psow parameter indicates whether or not the +<a href="psow.html">powersafe overwrite</a> property does or does not apply to the +storage media on which the database file resides.</p> + +<p><li> <b>nolock</b>: The nolock parameter is a boolean query parameter +which if set disables file locking in rollback journal modes. This +is useful for accessing a database on a filesystem that does not +support locking. Caution: Database corruption might result if two +or more processes write to the same database and any one of those +processes uses nolock=1.</p> + +<p><li> <b>immutable</b>: The immutable parameter is a boolean query +parameter that indicates that the database file is stored on +read-only media. When immutable is set, SQLite assumes that the +database file cannot be changed, even by a process with higher +privilege, and so the database is opened read-only and all locking +and change detection is disabled. Caution: Setting the immutable +property on a database file that does in fact change can result +in incorrect query results and/or <a href="#SQLITE_ABORT">SQLITE_CORRUPT</a> errors. +See also: <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_IMMUTABLE</a>.</p> + +<p></ul></p> + +<p>Specifying an unknown parameter in the query component of a URI is not an +error. Future versions of SQLite might understand additional query +parameters. See "<a href="uri.html#coreqp">query parameters with special meaning to SQLite</a>" for +additional information.</p> + +<p><a name="urifilenameexamples"></a> + <h3>URI filename examples</h3></p> + +<p><table border="1" align=center cellpadding=5> +<tr><th> URI filenames <th> Results +<tr><td> file:data.db <td> +Open the file "data.db" in the current directory. +<tr><td> file:/home/fred/data.db<br> +file:///home/fred/data.db <br> +file://localhost/home/fred/data.db <br> <td> +Open the database file "/home/fred/data.db". +<tr><td> file://darkstar/home/fred/data.db <td> +An error. "darkstar" is not a recognized authority. +<tr><td style="white-space:nowrap"> +file:///C:/Documents%20and%20Settings/fred/Desktop/data.db +<td> Windows only: Open the file "data.db" on fred's desktop on drive +C:. Note that the %20 escaping in this example is not strictly +necessary - space characters can be used literally +in URI filenames. +<tr><td> file:data.db?mode=ro&cache=private <td> +Open file "data.db" in the current directory for read-only access. +Regardless of whether or not shared-cache mode is enabled by +default, use a private cache. +<tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td> +Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" +that uses dot-files in place of posix advisory locking. +<tr><td> file:data.db?mode=readonly <td> +An error. "readonly" is not a valid option for the "mode" parameter. +Use "ro" instead: "file:data.db?mode=ro". +</table></p> + +<p>URI hexadecimal escape sequences (%HH) are supported within the path and +query components of a URI. A hexadecimal escape sequence consists of a +percent sign - "%" - followed by exactly two hexadecimal digits +specifying an octet value. Before the path or query components of a +URI filename are interpreted, they are encoded using UTF-8 and all +hexadecimal escape sequences replaced by a single byte containing the +corresponding octet. If this process generates an invalid UTF-8 encoding, +the results are undefined.</p> + +<p><b>Note to Windows users:</b> The encoding used for the filename argument +of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever +codepage is currently defined. Filenames containing international +characters must be converted to UTF-8 prior to passing them into +sqlite3_open() or sqlite3_open_v2().</p> + +<p><b>Note to Windows Runtime users:</b> The temporary directory must be set +prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various +features that require the use of temporary files may fail.</p> + +<p>See also: <a href="#sqlite3_temp_directory">sqlite3_temp_directory</a> +</p><hr><a name="sqlite3_preupdate_blobwrite"></a> +<h2>The pre-update hook.</h2> +</div> +<blockquote><pre> +#if defined(SQLITE_ENABLE_PREUPDATE_HOOK) +void *sqlite3_preupdate_hook( + sqlite3 *db, + void(*xPreUpdate)( + void *pCtx, /* Copy of third arg to preupdate_hook() */ + sqlite3 *db, /* Database handle */ + int op, /* SQLITE_UPDATE, DELETE or INSERT */ + char const *zDb, /* Database name */ + char const *zName, /* Table name */ + sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ + sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ + ), + void* +); +int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); +int sqlite3_preupdate_count(sqlite3 *); +int sqlite3_preupdate_depth(sqlite3 *); +int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **); +int sqlite3_preupdate_blobwrite(sqlite3 *); +#endif +</pre></blockquote> +<p> +These interfaces are only available if SQLite is compiled using the +<a href="compile.html#enable_preupdate_hook">SQLITE_ENABLE_PREUPDATE_HOOK</a> compile-time option.</p> + +<p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> interface registers a callback function +that is invoked prior to each <a href="lang_insert.html">INSERT</a>, <a href="lang_update.html">UPDATE</a>, and <a href="lang_delete.html">DELETE</a> operation +on a database table. +At most one preupdate hook may be registered at a time on a single +<a href="#sqlite3">database connection</a>; each call to <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> overrides +the previous setting. +The preupdate hook is disabled by invoking <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> +with a NULL pointer as the second parameter. +The third parameter to <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_hook()</a> is passed through as +the first parameter to callbacks.</p> + +<p>The preupdate hook only fires for changes to real database tables; the +preupdate hook is not invoked for changes to <a href="vtab.html">virtual tables</a> or to +system tables like sqlite_sequence or sqlite_stat1.</p> + +<p>The second parameter to the preupdate callback is a pointer to +the <a href="#sqlite3">database connection</a> that registered the preupdate hook. +The third parameter to the preupdate callback is one of the constants +<a href="#SQLITE_ALTER_TABLE">SQLITE_INSERT</a>, <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a>, or <a href="#SQLITE_ALTER_TABLE">SQLITE_UPDATE</a> to identify the +kind of update operation that is about to occur. +The fourth parameter to the preupdate callback is the name of the +database within the database connection that is being modified. This +will be "main" for the main database or "temp" for TEMP tables or +the name given after the AS keyword in the <a href="lang_attach.html">ATTACH</a> statement for attached +databases. +The fifth parameter to the preupdate callback is the name of the +table that is being modified.</p> + +<p>For an UPDATE or DELETE operation on a <a href="rowidtable.html">rowid table</a>, the sixth +parameter passed to the preupdate callback is the initial <a href="lang_createtable.html#rowid">rowid</a> of the +row being modified or deleted. For an INSERT operation on a rowid table, +or any operation on a WITHOUT ROWID table, the value of the sixth +parameter is undefined. For an INSERT or UPDATE on a rowid table the +seventh parameter is the final rowid value of the row being inserted +or updated. The value of the seventh parameter passed to the callback +function is not defined for operations on WITHOUT ROWID tables, or for +DELETE operations on rowid tables.</p> + +<p>The sqlite3_preupdate_hook(D,C,P) function returns the P argument from +the previous call on the same <a href="#sqlite3">database connection</a> D, or NULL for +the first call on D.</p> + +<p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_old()</a>, <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_new()</a>, +<a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_count()</a>, and <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_depth()</a> interfaces +provide additional information about a preupdate event. These routines +may only be called from within a preupdate callback. Invoking any of +these routines from outside of a preupdate callback or with a +<a href="#sqlite3">database connection</a> pointer that is different from the one supplied +to the preupdate callback results in undefined and probably undesirable +behavior.</p> + +<p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_count(D)</a> interface returns the number of columns +in the row that is being inserted, updated, or deleted.</p> + +<p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_old(D,N,P)</a> interface writes into P a pointer to +a <a href="#sqlite3_value">protected sqlite3_value</a> that contains the value of the Nth column of +the table row before it is updated. The N parameter must be between 0 +and one less than the number of columns or the behavior will be +undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE +preupdate callbacks; if it is used by an SQLITE_INSERT callback then the +behavior is undefined. The <a href="#sqlite3_value">sqlite3_value</a> that P points to +will be destroyed when the preupdate callback returns.</p> + +<p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_new(D,N,P)</a> interface writes into P a pointer to +a <a href="#sqlite3_value">protected sqlite3_value</a> that contains the value of the Nth column of +the table row after it is updated. The N parameter must be between 0 +and one less than the number of columns or the behavior will be +undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE +preupdate callbacks; if it is used by an SQLITE_DELETE callback then the +behavior is undefined. The <a href="#sqlite3_value">sqlite3_value</a> that P points to +will be destroyed when the preupdate callback returns.</p> + +<p>The <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_depth(D)</a> interface returns 0 if the preupdate +callback was invoked as a result of a direct insert, update, or delete +operation; or 1 for inserts, updates, or deletes invoked by top-level +triggers; or 2 for changes resulting from triggers called by top-level +triggers; and so forth.</p> + +<p>When the <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> API is used to update a blob column, +the pre-update hook is invoked with SQLITE_DELETE. This is because the +in this case the new values are not available. In this case, when a +callback made with op==SQLITE_DELETE is actually a write using the +sqlite3_blob_write() API, the <a href="#sqlite3_preupdate_blobwrite">sqlite3_preupdate_blobwrite()</a> returns +the index of the column being written. In other cases, where the +pre-update hook is being invoked for some other reason, including a +regular DELETE, sqlite3_preupdate_blobwrite() returns -1.</p> + +<p>See also: <a href="#sqlite3_update_hook">sqlite3_update_hook()</a> +</p><hr><a name="sqlite3_profile"></a> +<h2>Tracing And Profiling Functions</h2> +</div> +<blockquote><pre> +void *sqlite3_trace(sqlite3*, + void(*xTrace)(void*,const char*), void*); +void *sqlite3_profile(sqlite3*, + void(*xProfile)(void*,const char*,sqlite3_uint64), void*); +</pre></blockquote> +<p> +These routines are deprecated. Use the <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a> interface +instead of the routines described here.</p> + +<p>These routines register callback functions that can be used for +tracing and profiling the execution of SQL statements.</p> + +<p>The callback function registered by sqlite3_trace() is invoked at +various times when an SQL statement is being run by <a href="#sqlite3_step">sqlite3_step()</a>. +The sqlite3_trace() callback is invoked with a UTF-8 rendering of the +SQL statement text as the statement first begins executing. +Additional sqlite3_trace() callbacks might occur +as each triggered subprogram is entered. The callbacks for triggers +contain a UTF-8 SQL comment that identifies the trigger.</p> + +<p>The <a href="compile.html#trace_size_limit">SQLITE_TRACE_SIZE_LIMIT</a> compile-time option can be used to limit +the length of <a href="lang_expr.html#varparam">bound parameter</a> expansion in the output of sqlite3_trace().</p> + +<p>The callback function registered by sqlite3_profile() is invoked +as each SQL statement finishes. The profile callback contains +the original statement text and an estimate of wall-clock time +of how long that statement took to run. The profile callback +time is in units of nanoseconds, however the current implementation +is only capable of millisecond resolution so the six least significant +digits in the time are meaningless. Future versions of SQLite +might provide greater resolution on the profiler callback. Invoking +either <a href="#sqlite3_profile">sqlite3_trace()</a> or <a href="#sqlite3_trace_v2">sqlite3_trace_v2()</a> will cancel the +profile callback. +</p><hr><a name="sqlite3_result_blob"></a> +<h2>Setting The Result Of An SQL Function</h2> +</div> +<blockquote><pre> +void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); +void sqlite3_result_blob64(sqlite3_context*,const void*, + sqlite3_uint64,void(*)(void*)); +void sqlite3_result_double(sqlite3_context*, double); +void sqlite3_result_error(sqlite3_context*, const char*, int); +void sqlite3_result_error16(sqlite3_context*, const void*, int); +void sqlite3_result_error_toobig(sqlite3_context*); +void sqlite3_result_error_nomem(sqlite3_context*); +void sqlite3_result_error_code(sqlite3_context*, int); +void sqlite3_result_int(sqlite3_context*, int); +void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); +void sqlite3_result_null(sqlite3_context*); +void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); +void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64, + void(*)(void*), unsigned char encoding); +void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); +void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); +void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); +void sqlite3_result_value(sqlite3_context*, sqlite3_value*); +void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*)); +void sqlite3_result_zeroblob(sqlite3_context*, int n); +int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); +</pre></blockquote> +<p> +These routines are used by the xFunc or xFinal callbacks that +implement SQL functions and aggregates. See +<a href="#sqlite3_create_function">sqlite3_create_function()</a> and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> +for additional information.</p> + +<p>These functions work very much like the <a href="#sqlite3_bind_blob">parameter binding</a> family of +functions used to bind values to host parameters in prepared statements. +Refer to the <a href="#sqlite3_bind_blob">SQL parameter</a> documentation for additional information.</p> + +<p>The sqlite3_result_blob() interface sets the result from +an application-defined function to be the BLOB whose content is pointed +to by the second parameter and which is N bytes long where N is the +third parameter.</p> + +<p>The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N) +interfaces set the result of the application-defined function to be +a BLOB containing all zero bytes and N bytes in size.</p> + +<p>The sqlite3_result_double() interface sets the result from +an application-defined function to be a floating point value specified +by its 2nd argument.</p> + +<p>The sqlite3_result_error() and sqlite3_result_error16() functions +cause the implemented SQL function to throw an exception. +SQLite uses the string pointed to by the +2nd parameter of sqlite3_result_error() or sqlite3_result_error16() +as the text of an error message. SQLite interprets the error +message string from sqlite3_result_error() as UTF-8. SQLite +interprets the string from sqlite3_result_error16() as UTF-16 using +the same <a href="#byteorderdeterminationrules">byte-order determination rules</a> as <a href="#sqlite3_bind_blob">sqlite3_bind_text16()</a>. +If the third parameter to sqlite3_result_error() +or sqlite3_result_error16() is negative then SQLite takes as the error +message all text up through the first zero character. +If the third parameter to sqlite3_result_error() or +sqlite3_result_error16() is non-negative then SQLite takes that many +bytes (not characters) from the 2nd parameter as the error message. +The sqlite3_result_error() and sqlite3_result_error16() +routines make a private copy of the error message text before +they return. Hence, the calling function can deallocate or +modify the text after they return without harm. +The sqlite3_result_error_code() function changes the error code +returned by SQLite as a result of an error in a function. By default, +the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() +or sqlite3_result_error16() resets the error code to SQLITE_ERROR.</p> + +<p>The sqlite3_result_error_toobig() interface causes SQLite to throw an +error indicating that a string or BLOB is too long to represent.</p> + +<p>The sqlite3_result_error_nomem() interface causes SQLite to throw an +error indicating that a memory allocation failed.</p> + +<p>The sqlite3_result_int() interface sets the return value +of the application-defined function to be the 32-bit signed integer +value given in the 2nd argument. +The sqlite3_result_int64() interface sets the return value +of the application-defined function to be the 64-bit signed integer +value given in the 2nd argument.</p> + +<p>The sqlite3_result_null() interface sets the return value +of the application-defined function to be NULL.</p> + +<p>The sqlite3_result_text(), sqlite3_result_text16(), +sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces +set the return value of the application-defined function to be +a text string which is represented as UTF-8, UTF-16 native byte order, +UTF-16 little endian, or UTF-16 big endian, respectively. +The sqlite3_result_text64() interface sets the return value of an +application-defined function to be a text string in an encoding +specified by the fifth (and last) parameter, which must be one +of <a href="#SQLITE_ANY">SQLITE_UTF8</a>, <a href="#SQLITE_ANY">SQLITE_UTF16</a>, <a href="#SQLITE_ANY">SQLITE_UTF16BE</a>, or <a href="#SQLITE_ANY">SQLITE_UTF16LE</a>. +SQLite takes the text result from the application from +the 2nd parameter of the sqlite3_result_text* interfaces. +If the 3rd parameter to any of the sqlite3_result_text* interfaces +other than sqlite3_result_text64() is negative, then SQLite computes +the string length itself by searching the 2nd parameter for the first +zero character. +If the 3rd parameter to the sqlite3_result_text* interfaces +is non-negative, then as many bytes (not characters) of the text +pointed to by the 2nd parameter are taken as the application-defined +function result. If the 3rd parameter is non-negative, then it +must be the byte offset into the string where the NUL terminator would +appear if the string where NUL terminated. If any NUL characters occur +in the string at a byte offset that is less than the value of the 3rd +parameter, then the resulting string will contain embedded NULs and the +result of expressions operating on strings with embedded NULs is undefined. +If the 4th parameter to the sqlite3_result_text* interfaces +or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that +function as the destructor on the text or BLOB result when it has +finished using that result. +If the 4th parameter to the sqlite3_result_text* interfaces or to +sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite +assumes that the text or BLOB result is in constant space and does not +copy the content of the parameter nor call a destructor on the content +when it has finished using that result. +If the 4th parameter to the sqlite3_result_text* interfaces +or sqlite3_result_blob is the special constant SQLITE_TRANSIENT +then SQLite makes a copy of the result into space obtained +from <a href="#sqlite3_free">sqlite3_malloc()</a> before it returns.</p> + +<p>For the sqlite3_result_text16(), sqlite3_result_text16le(), and +sqlite3_result_text16be() routines, and for sqlite3_result_text64() +when the encoding is not UTF8, if the input UTF16 begins with a +byte-order mark (BOM, U+FEFF) then the BOM is removed from the +string and the rest of the string is interpreted according to the +byte-order specified by the BOM. The byte-order specified by +the BOM at the beginning of the text overrides the byte-order +specified by the interface procedure. So, for example, if +sqlite3_result_text16le() is invoked with text that begins +with bytes 0xfe, 0xff (a big-endian byte-order mark) then the +first two bytes of input are skipped and the remaining input +is interpreted as UTF16BE text.</p> + +<p>For UTF16 input text to the sqlite3_result_text16(), +sqlite3_result_text16be(), sqlite3_result_text16le(), and +sqlite3_result_text64() routines, if the text contains invalid +UTF16 characters, the invalid characters might be converted +into the unicode replacement character, U+FFFD.</p> + +<p>The sqlite3_result_value() interface sets the result of +the application-defined function to be a copy of the +<a href="#sqlite3_value">unprotected sqlite3_value</a> object specified by the 2nd parameter. The +sqlite3_result_value() interface makes a copy of the <a href="#sqlite3_value">sqlite3_value</a> +so that the <a href="#sqlite3_value">sqlite3_value</a> specified in the parameter may change or +be deallocated after sqlite3_result_value() returns without harm. +A <a href="#sqlite3_value">protected sqlite3_value</a> object may always be used where an +<a href="#sqlite3_value">unprotected sqlite3_value</a> object is required, so either +kind of <a href="#sqlite3_value">sqlite3_value</a> object can be used with this interface.</p> + +<p>The sqlite3_result_pointer(C,P,T,D) interface sets the result to an +SQL NULL value, just like <a href="#sqlite3_result_blob">sqlite3_result_null(C)</a>, except that it +also associates the host-language pointer P or type T with that +NULL value such that the pointer can be retrieved within an +<a href="appfunc.html">application-defined SQL function</a> using <a href="#sqlite3_value_blob">sqlite3_value_pointer()</a>. +If the D parameter is not NULL, then it is a pointer to a destructor +for the P parameter. SQLite invokes D with P as its only argument +when SQLite is finished with P. The T parameter should be a static +string and preferably a string literal. The sqlite3_result_pointer() +routine is part of the <a href="bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p> + +<p>If these routines are called from within the different thread +than the one containing the application-defined function that received +the <a href="#sqlite3_context">sqlite3_context</a> pointer, the results are undefined. +</p><hr><a name="sqlite3_status"></a> +<h2>SQLite Runtime Status</h2> +</div> +<blockquote><pre> +int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); +int sqlite3_status64( + int op, + sqlite3_int64 *pCurrent, + sqlite3_int64 *pHighwater, + int resetFlag +); +</pre></blockquote> +<p> +These interfaces are used to retrieve runtime status information +about the performance of SQLite, and optionally to reset various +highwater marks. The first argument is an integer code for +the specific parameter to measure. Recognized integer codes +are of the form <a href="#SQLITE_STATUS_MALLOC_COUNT">SQLITE_STATUS_...</a>. +The current value of the parameter is returned into *pCurrent. +The highest recorded value is returned in *pHighwater. If the +resetFlag is true, then the highest record value is reset after +*pHighwater is written. Some parameters do not record the highest +value. For those parameters +nothing is written into *pHighwater and the resetFlag is ignored. +Other parameters record only the highwater mark and not the current +value. For these latter parameters nothing is written into *pCurrent.</p> + +<p>The sqlite3_status() and sqlite3_status64() routines return +SQLITE_OK on success and a non-zero <a href="rescode.html">error code</a> on failure.</p> + +<p>If either the current value or the highwater mark is too large to +be represented by a 32-bit integer, then the values returned by +sqlite3_status() are undefined.</p> + +<p>See also: <a href="#sqlite3_db_status">sqlite3_db_status()</a> +</p><hr><a name="sqlite3_stmt_scanstatus"></a> +<h2>Prepared Statement Scan Status</h2> +</div> +<blockquote><pre> +int sqlite3_stmt_scanstatus( + sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ + int idx, /* Index of loop to report on */ + int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ + void *pOut /* Result written here */ +); +int sqlite3_stmt_scanstatus_v2( + sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ + int idx, /* Index of loop to report on */ + int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ + int flags, /* Mask of flags defined below */ + void *pOut /* Result written here */ +); +</pre></blockquote> +<p> +These interfaces return information about the predicted and measured +performance for pStmt. Advanced applications can use this +interface to compare the predicted and the measured performance and +issue warnings and/or rerun <a href="lang_analyze.html">ANALYZE</a> if discrepancies are found.</p> + +<p>Since this interface is expected to be rarely used, it is only +available if SQLite is compiled using the <a href="compile.html#enable_stmt_scanstatus">SQLITE_ENABLE_STMT_SCANSTATUS</a> +compile-time option.</p> + +<p>The "iScanStatusOp" parameter determines which status information to return. +The "iScanStatusOp" must be one of the <a href="#SQLITE_SCANSTAT_EST">scanstatus options</a> or the behavior +of this interface is undefined. The requested measurement is written into +a variable pointed to by the "pOut" parameter.</p> + +<p>The "flags" parameter must be passed a mask of flags. At present only +one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX +is specified, then status information is available for all elements +of a query plan that are reported by "EXPLAIN QUERY PLAN" output. If +SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements +that correspond to query loops (the "SCAN..." and "SEARCH..." elements of +the EXPLAIN QUERY PLAN output) are available. Invoking API +sqlite3_stmt_scanstatus() is equivalent to calling +sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter.</p> + +<p>Parameter "idx" identifies the specific query element to retrieve statistics +for. Query elements are numbered starting from zero. A value of -1 may be +to query for statistics regarding the entire query. If idx is out of range +- less than -1 or greater than or equal to the total number of query +elements used to implement the statement - a non-zero value is returned and +the variable that pOut points to is unchanged.</p> + +<p>See also: <a href="#sqlite3_stmt_scanstatus_reset">sqlite3_stmt_scanstatus_reset()</a> +</p><hr><a name="sqlite3_str_append"></a> +<h2>Add Content To A Dynamic String</h2> +</div> +<blockquote><pre> +void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...); +void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list); +void sqlite3_str_append(sqlite3_str*, const char *zIn, int N); +void sqlite3_str_appendall(sqlite3_str*, const char *zIn); +void sqlite3_str_appendchar(sqlite3_str*, int N, char C); +void sqlite3_str_reset(sqlite3_str*); +</pre></blockquote> +<p> +These interfaces add content to an sqlite3_str object previously obtained +from <a href="#sqlite3_str_new">sqlite3_str_new()</a>.</p> + +<p>The <a href="#sqlite3_str_append">sqlite3_str_appendf(X,F,...)</a> and +<a href="#sqlite3_str_append">sqlite3_str_vappendf(X,F,V)</a> interfaces uses the <a href="printf.html">built-in printf</a> +functionality of SQLite to append formatted text onto the end of +<a href="#sqlite3_str">sqlite3_str</a> object X.</p> + +<p>The <a href="#sqlite3_str_append">sqlite3_str_append(X,S,N)</a> method appends exactly N bytes from string S +onto the end of the <a href="#sqlite3_str">sqlite3_str</a> object X. N must be non-negative. +S must contain at least N non-zero bytes of content. To append a +zero-terminated string in its entirety, use the <a href="#sqlite3_str_append">sqlite3_str_appendall()</a> +method instead.</p> + +<p>The <a href="#sqlite3_str_append">sqlite3_str_appendall(X,S)</a> method appends the complete content of +zero-terminated string S onto the end of <a href="#sqlite3_str">sqlite3_str</a> object X.</p> + +<p>The <a href="#sqlite3_str_append">sqlite3_str_appendchar(X,N,C)</a> method appends N copies of the +single-byte character C onto the end of <a href="#sqlite3_str">sqlite3_str</a> object X. +This method can be used, for example, to add whitespace indentation.</p> + +<p>The <a href="#sqlite3_str_append">sqlite3_str_reset(X)</a> method resets the string under construction +inside <a href="#sqlite3_str">sqlite3_str</a> object X back to zero bytes in length.</p> + +<p>These methods do not return a result code. If an error occurs, that fact +is recorded in the <a href="#sqlite3_str">sqlite3_str</a> object and can be recovered by a +subsequent call to <a href="#sqlite3_str_errcode">sqlite3_str_errcode(X)</a>. +</p><hr><a name="sqlite3_str_errcode"></a> +<h2>Status Of A Dynamic String</h2> +</div> +<blockquote><pre> +int sqlite3_str_errcode(sqlite3_str*); +int sqlite3_str_length(sqlite3_str*); +char *sqlite3_str_value(sqlite3_str*); +</pre></blockquote> +<p> +These interfaces return the current status of an <a href="#sqlite3_str">sqlite3_str</a> object.</p> + +<p>If any prior errors have occurred while constructing the dynamic string +in sqlite3_str X, then the <a href="#sqlite3_str_errcode">sqlite3_str_errcode(X)</a> method will return +an appropriate error code. The <a href="#sqlite3_str_errcode">sqlite3_str_errcode(X)</a> method returns +<a href="#SQLITE_ABORT">SQLITE_NOMEM</a> following any out-of-memory error, or +<a href="#SQLITE_ABORT">SQLITE_TOOBIG</a> if the size of the dynamic string exceeds +<a href="limits.html#max_length">SQLITE_MAX_LENGTH</a>, or <a href="#SQLITE_ABORT">SQLITE_OK</a> if there have been no errors.</p> + +<p>The <a href="#sqlite3_str_errcode">sqlite3_str_length(X)</a> method returns the current length, in bytes, +of the dynamic string under construction in <a href="#sqlite3_str">sqlite3_str</a> object X. +The length returned by <a href="#sqlite3_str_errcode">sqlite3_str_length(X)</a> does not include the +zero-termination byte.</p> + +<p>The <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> method returns a pointer to the current +content of the dynamic string under construction in X. The value +returned by <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> is managed by the sqlite3_str object X +and might be freed or altered by any subsequent method on the same +<a href="#sqlite3_str">sqlite3_str</a> object. Applications must not used the pointer returned +<a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> after any subsequent method call on the same +object. Applications may change the content of the string returned +by <a href="#sqlite3_str_errcode">sqlite3_str_value(X)</a> as long as they do not write into any bytes +outside the range of 0 to <a href="#sqlite3_str_errcode">sqlite3_str_length(X)</a> and do not read or +write any byte after any subsequent sqlite3_str method call. +</p><hr><a name="sqlite3_stricmp"></a> +<h2>String Comparison</h2> +</div> +<blockquote><pre> +int sqlite3_stricmp(const char *, const char *); +int sqlite3_strnicmp(const char *, const char *, int); +</pre></blockquote> +<p> +The <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a> APIs allow applications +and extensions to compare the contents of two buffers containing UTF-8 +strings in a case-independent fashion, using the same definition of "case +independence" that SQLite uses internally when comparing identifiers. +</p><hr><a name="sqlite3_total_changes"></a> +<h2>Total Number Of Rows Modified</h2> +</div> +<blockquote><pre> +int sqlite3_total_changes(sqlite3*); +sqlite3_int64 sqlite3_total_changes64(sqlite3*); +</pre></blockquote> +<p> +These functions return the total number of rows inserted, modified or +deleted by all <a href="lang_insert.html">INSERT</a>, <a href="lang_update.html">UPDATE</a> or <a href="lang_delete.html">DELETE</a> statements completed +since the database connection was opened, including those executed as +part of trigger programs. The two functions are identical except for the +type of the return value and that if the number of rows modified by the +connection exceeds the maximum value supported by type "int", then +the return value of sqlite3_total_changes() is undefined. Executing +any other type of SQL statement does not affect the value returned by +sqlite3_total_changes().</p> + +<p>Changes made as part of <a href="foreignkeys.html#fk_actions">foreign key actions</a> are included in the +count, but those made as part of REPLACE constraint resolution are +not. Changes to a view that are intercepted by INSTEAD OF triggers +are not counted.</p> + +<p>The <a href="#sqlite3_total_changes">sqlite3_total_changes(D)</a> interface only reports the number +of rows that changed due to SQL statement run against database +connection D. Any changes by other database connections are ignored. +To detect changes against a database file from other database +connections use the <a href="pragma.html#pragma_data_version">PRAGMA data_version</a> command or the +<a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> <a href="#sqlite3_file_control">file control</a>.</p> + +<p>If a separate thread makes changes on the same database connection +while <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> is running then the value +returned is unpredictable and not meaningful.</p> + +<p>See also: +<ul> +<li> the <a href="#sqlite3_changes">sqlite3_changes()</a> interface +<li> the <a href="pragma.html#pragma_count_changes">count_changes pragma</a> +<li> the <a href="lang_corefunc.html#changes">changes() SQL function</a> +<li> the <a href="pragma.html#pragma_data_version">data_version pragma</a> +<li> the <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> <a href="#sqlite3_file_control">file control</a> +</ul> +</p><hr><a name="sqlite3_uri_boolean"></a> +<h2>Obtain Values For URI Parameters</h2> +</div> +<blockquote><pre> +const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam); +int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault); +sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64); +const char *sqlite3_uri_key(sqlite3_filename z, int N); +</pre></blockquote> +<p> +These are utility routines, useful to <a href="vfs.html">custom VFS implementations</a>, +that check if a database file was a URI that contained a specific query +parameter, and if so obtains the value of that query parameter.</p> + +<p>The first parameter to these interfaces (hereafter referred to +as F) must be one of: +<ul> +<li> A database filename pointer created by the SQLite core and +passed into the xOpen() method of a VFS implementation, or +<li> A filename obtained from <a href="#sqlite3_db_filename">sqlite3_db_filename()</a>, or +<li> A new filename constructed using <a href="#sqlite3_create_filename">sqlite3_create_filename()</a>. +</ul> +If the F parameter is not one of the above, then the behavior is +undefined and probably undesirable. Older versions of SQLite were +more tolerant of invalid F parameters than newer versions.</p> + +<p>If F is a suitable filename (as described in the previous paragraph) +and if P is the name of the query parameter, then +sqlite3_uri_parameter(F,P) returns the value of the P +parameter if it exists or a NULL pointer if P does not appear as a +query parameter on F. If P is a query parameter of F and it +has no explicit value, then sqlite3_uri_parameter(F,P) returns +a pointer to an empty string.</p> + +<p>The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean +parameter and returns true (1) or false (0) according to the value +of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the +value of query parameter P is one of "yes", "true", or "on" in any +case or if the value begins with a non-zero number. The +sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of +query parameter P is one of "no", "false", or "off" in any case or +if the value begins with a numeric zero. If P is not a query +parameter on F or if the value of P does not match any of the +above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).</p> + +<p>The sqlite3_uri_int64(F,P,D) routine converts the value of P into a +64-bit signed integer and returns that integer, or D if P does not +exist. If the value of P is something other than an integer, then +zero is returned.</p> + +<p>The sqlite3_uri_key(F,N) returns a pointer to the name (not +the value) of the N-th query parameter for filename F, or a NULL +pointer if N is less than zero or greater than the number of query +parameters minus 1. The N value is zero-based so N should be 0 to obtain +the name of the first query parameter, 1 for the second parameter, and +so forth.</p> + +<p>If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and +sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and +is not a database file pathname pointer that the SQLite core passed +into the xOpen VFS method, then the behavior of this routine is undefined +and probably undesirable.</p> + +<p>Beginning with SQLite <a href="releaselog/3_31_0.html">version 3.31.0</a> (2020-01-22) the input F +parameter can also be the name of a rollback journal file or WAL file +in addition to the main database file. Prior to version 3.31.0, these +routines would only work if F was the name of the main database file. +When the F parameter is the name of the rollback journal or WAL file, +it has access to all the same query parameters as were found on the +main database file.</p> + +<p>See the <a href="uri.html">URI filename</a> documentation for additional information. +</p><hr><a name="sqlite3_value_blob"></a> +<h2>Obtaining SQL Values</h2> +</div> +<blockquote><pre> +const void *sqlite3_value_blob(sqlite3_value*); +double sqlite3_value_double(sqlite3_value*); +int sqlite3_value_int(sqlite3_value*); +sqlite3_int64 sqlite3_value_int64(sqlite3_value*); +void *sqlite3_value_pointer(sqlite3_value*, const char*); +const unsigned char *sqlite3_value_text(sqlite3_value*); +const void *sqlite3_value_text16(sqlite3_value*); +const void *sqlite3_value_text16le(sqlite3_value*); +const void *sqlite3_value_text16be(sqlite3_value*); +int sqlite3_value_bytes(sqlite3_value*); +int sqlite3_value_bytes16(sqlite3_value*); +int sqlite3_value_type(sqlite3_value*); +int sqlite3_value_numeric_type(sqlite3_value*); +int sqlite3_value_nochange(sqlite3_value*); +int sqlite3_value_frombind(sqlite3_value*); +</pre></blockquote> +<p> +<b>Summary:</b> +<blockquote><table border=0 cellpadding=0 cellspacing=0> +<tr><td><b>sqlite3_value_blob</b><td>→<td>BLOB value +<tr><td><b>sqlite3_value_double</b><td>→<td>REAL value +<tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value +<tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value +<tr><td><b>sqlite3_value_pointer</b><td>→<td>Pointer value +<tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value +<tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in +the native byteorder +<tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value +<tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value +<tr><td> <td> <td> +<tr><td><b>sqlite3_value_bytes</b><td>→<td>Size of a BLOB +or a UTF-8 TEXT in bytes +<tr><td><b>sqlite3_value_bytes16 </b> +<td>→ <td>Size of UTF-16 +TEXT in bytes +<tr><td><b>sqlite3_value_type</b><td>→<td>Default +datatype of the value +<tr><td><b>sqlite3_value_numeric_type </b> +<td>→ <td>Best numeric datatype of the value +<tr><td><b>sqlite3_value_nochange </b> +<td>→ <td>True if the column is unchanged in an UPDATE +against a virtual table. +<tr><td><b>sqlite3_value_frombind </b> +<td>→ <td>True if value originated from a <a href="lang_expr.html#varparam">bound parameter</a> +</table></blockquote></p> + +<p><b>Details:</b></p> + +<p>These routines extract type, size, and content information from +<a href="#sqlite3_value">protected sqlite3_value</a> objects. Protected sqlite3_value objects +are used to pass parameter information into the functions that +implement <a href="appfunc.html">application-defined SQL functions</a> and <a href="vtab.html">virtual tables</a>.</p> + +<p>These routines work only with <a href="#sqlite3_value">protected sqlite3_value</a> objects. +Any attempt to use these routines on an <a href="#sqlite3_value">unprotected sqlite3_value</a> +is not threadsafe.</p> + +<p>These routines work just like the corresponding <a href="#sqlite3_column_blob">column access functions</a> +except that these routines take a single <a href="#sqlite3_value">protected sqlite3_value</a> object +pointer instead of a <a href="#sqlite3_stmt">sqlite3_stmt*</a> pointer and an integer column number.</p> + +<p>The sqlite3_value_text16() interface extracts a UTF-16 string +in the native byte-order of the host machine. The +sqlite3_value_text16be() and sqlite3_value_text16le() interfaces +extract UTF-16 strings as big-endian and little-endian respectively.</p> + +<p>If <a href="#sqlite3_value">sqlite3_value</a> object V was initialized +using <a href="#sqlite3_bind_blob">sqlite3_bind_pointer(S,I,P,X,D)</a> or <a href="#sqlite3_result_blob">sqlite3_result_pointer(C,P,X,D)</a> +and if X and Y are strings that compare equal according to strcmp(X,Y), +then sqlite3_value_pointer(V,Y) will return the pointer P. Otherwise, +sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer() +routine is part of the <a href="bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p> + +<p>The sqlite3_value_type(V) interface returns the +<a href="#SQLITE_BLOB">datatype code</a> for the initial datatype of the +<a href="#sqlite3_value">sqlite3_value</a> object V. The returned value is one of <a href="#SQLITE_BLOB">SQLITE_INTEGER</a>, +<a href="#SQLITE_BLOB">SQLITE_FLOAT</a>, <a href="#SQLITE_BLOB">SQLITE_TEXT</a>, <a href="#SQLITE_BLOB">SQLITE_BLOB</a>, or <a href="#SQLITE_BLOB">SQLITE_NULL</a>. +Other interfaces might change the datatype for an sqlite3_value object. +For example, if the datatype is initially SQLITE_INTEGER and +sqlite3_value_text(V) is called to extract a text value for that +integer, then subsequent calls to sqlite3_value_type(V) might return +SQLITE_TEXT. Whether or not a persistent internal datatype conversion +occurs is undefined and may change from one release of SQLite to the next.</p> + +<p>The sqlite3_value_numeric_type() interface attempts to apply +numeric affinity to the value. This means that an attempt is +made to convert the value to an integer or floating point. If +such a conversion is possible without loss of information (in other +words, if the value is a string that looks like a number) +then the conversion is performed. Otherwise no conversion occurs. +The <a href="#SQLITE_BLOB">datatype</a> after conversion is returned.</p> + +<p>Within the <a href="vtab.html#xupdate">xUpdate</a> method of a <a href="vtab.html">virtual table</a>, the +sqlite3_value_nochange(X) interface returns true if and only if +the column corresponding to X is unchanged by the UPDATE operation +that the xUpdate method call was invoked to implement and if +and the prior <a href="vtab.html#xcolumn">xColumn</a> method call that was invoked to extracted +the value for that column returned without setting a result (probably +because it queried <a href="#sqlite3_vtab_nochange">sqlite3_vtab_nochange()</a> and found that the column +was unchanging). Within an <a href="vtab.html#xupdate">xUpdate</a> method, any value for which +sqlite3_value_nochange(X) is true will in all other respects appear +to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other +than within an <a href="vtab.html#xupdate">xUpdate</a> method call for an UPDATE statement, then +the return value is arbitrary and meaningless.</p> + +<p>The sqlite3_value_frombind(X) interface returns non-zero if the +value X originated from one of the <a href="#sqlite3_bind_blob">sqlite3_bind()</a> +interfaces. If X comes from an SQL literal value, or a table column, +or an expression, then sqlite3_value_frombind(X) returns zero.</p> + +<p>Please pay particular attention to the fact that the pointer returned +from <a href="#sqlite3_value_blob">sqlite3_value_blob()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>, or +<a href="#sqlite3_value_blob">sqlite3_value_text16()</a> can be invalidated by a subsequent call to +<a href="#sqlite3_value_blob">sqlite3_value_bytes()</a>, <a href="#sqlite3_value_blob">sqlite3_value_bytes16()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>, +or <a href="#sqlite3_value_blob">sqlite3_value_text16()</a>.</p> + +<p>These routines must be called from the same thread as +the SQL function that supplied the <a href="#sqlite3_value">sqlite3_value*</a> parameters.</p> + +<p>As long as the input parameter is correct, these routines can only +fail if an out-of-memory error occurs during a format conversion. +Only the following subset of interfaces are subject to out-of-memory +errors:</p> + +<p><ul> +<li> sqlite3_value_blob() +<li> sqlite3_value_text() +<li> sqlite3_value_text16() +<li> sqlite3_value_text16le() +<li> sqlite3_value_text16be() +<li> sqlite3_value_bytes() +<li> sqlite3_value_bytes16() +</ul></p> + +<p>If an out-of-memory error occurs, then the return value from these +routines is the same as if the column had contained an SQL NULL value. +Valid SQL NULL returns can be distinguished from out-of-memory errors +by invoking the <a href="#sqlite3_errcode">sqlite3_errcode()</a> immediately after the suspect +return value is obtained and before any +other SQLite interface is called on the same <a href="#sqlite3">database connection</a>. +</p><hr><a name="sqlite3_value_dup"></a> +<h2>Copy And Free SQL Values</h2> +</div> +<blockquote><pre> +sqlite3_value *sqlite3_value_dup(const sqlite3_value*); +void sqlite3_value_free(sqlite3_value*); +</pre></blockquote> +<p> +The sqlite3_value_dup(V) interface makes a copy of the <a href="#sqlite3_value">sqlite3_value</a> +object D and returns a pointer to that copy. The <a href="#sqlite3_value">sqlite3_value</a> returned +is a <a href="#sqlite3_value">protected sqlite3_value</a> object even if the input is not. +The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a +memory allocation fails. If V is a <a href="bindptr.html">pointer value</a>, then the result +of sqlite3_value_dup(V) is a NULL value.</p> + +<p>The sqlite3_value_free(V) interface frees an <a href="#sqlite3_value">sqlite3_value</a> object +previously obtained from <a href="#sqlite3_value_dup">sqlite3_value_dup()</a>. If V is a NULL pointer +then sqlite3_value_free(V) is a harmless no-op. +</p><hr><a name="sqlite3_vfs_find"></a> +<h2>Virtual File System Objects</h2> +</div> +<blockquote><pre> +sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); +int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); +int sqlite3_vfs_unregister(sqlite3_vfs*); +</pre></blockquote> +<p> +A virtual filesystem (VFS) is an <a href="#sqlite3_vfs">sqlite3_vfs</a> object +that SQLite uses to interact +with the underlying operating system. Most SQLite builds come with a +single default VFS that is appropriate for the host computer. +New VFSes can be registered and existing VFSes can be unregistered. +The following interfaces are provided.</p> + +<p>The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. +Names are case sensitive. +Names are zero-terminated UTF-8 strings. +If there is no match, a NULL pointer is returned. +If zVfsName is NULL then the default VFS is returned.</p> + +<p>New VFSes are registered with sqlite3_vfs_register(). +Each new VFS becomes the default VFS if the makeDflt flag is set. +The same VFS can be registered multiple times without injury. +To make an existing VFS into the default VFS, register it again +with the makeDflt flag set. If two different VFSes with the +same name are registered, the behavior is undefined. If a +VFS is registered with a name that is NULL or an empty string, +then the behavior is undefined.</p> + +<p>Unregister a VFS with the sqlite3_vfs_unregister() interface. +If the default VFS is unregistered, another VFS is chosen as +the default. The choice for the new VFS is arbitrary. +</p><hr><a name="sqlite3_vtab_in_first"></a> +<h2>Find all elements on the right-hand side of an IN constraint.</h2> +</div> +<blockquote><pre> +int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut); +int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut); +</pre></blockquote> +<p> +These interfaces are only useful from within the +<a href="vtab.html#xfilter">xFilter() method</a> of a <a href="vtab.html">virtual table</a> implementation. +The result of invoking these interfaces from any other context +is undefined and probably harmful.</p> + +<p>The X parameter in a call to sqlite3_vtab_in_first(X,P) or +sqlite3_vtab_in_next(X,P) should be one of the parameters to the +xFilter method which invokes these routines, and specifically +a parameter that was previously selected for all-at-once IN constraint +processing use the <a href="#sqlite3_vtab_in">sqlite3_vtab_in()</a> interface in the +<a href="vtab.html#xbestindex">xBestIndex method</a>. If the X parameter is not +an xFilter argument that was selected for all-at-once IN constraint +processing, then these routines return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</p> + +<p>Use these routines to access all values on the right-hand side +of the IN constraint using code like the following:</p> + +<p><blockquote><pre> + for(rc=sqlite3_vtab_in_first(pList, &pVal); + rc==SQLITE_OK && pVal; + rc=sqlite3_vtab_in_next(pList, &pVal) + ){ + // do something with pVal + } + if( rc!=SQLITE_OK ){ + // an error has occurred + } +</pre></blockquote></p> + +<p>On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P) +routines return SQLITE_OK and set *P to point to the first or next value +on the RHS of the IN constraint. If there are no more values on the +right hand side of the IN constraint, then *P is set to NULL and these +routines return <a href="#SQLITE_ABORT">SQLITE_DONE</a>. The return value might be +some other value, such as SQLITE_NOMEM, in the event of a malfunction.</p> + +<p>The *ppOut values returned by these routines are only valid until the +next call to either of these routines or until the end of the xFilter +method from which these routines were called. If the virtual table +implementation needs to retain the *ppOut values for longer, it must make +copies. The *ppOut values are <a href="#sqlite3_value">protected</a>. +</p><hr><a name="sqlite3_win32_set_directory"></a> +<h2>Win32 Specific Interface</h2> +</div> +<blockquote><pre> +int sqlite3_win32_set_directory( + unsigned long type, /* Identifier for directory being set or reset */ + void *zValue /* New value for directory being set or reset */ +); +int sqlite3_win32_set_directory8(unsigned long type, const char *zValue); +int sqlite3_win32_set_directory16(unsigned long type, const void *zValue); +</pre></blockquote> +<p> +These interfaces are available only on Windows. The +<a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory</a> interface is used to set the value associated +with the <a href="#sqlite3_temp_directory">sqlite3_temp_directory</a> or <a href="#sqlite3_data_directory">sqlite3_data_directory</a> variable, to +zValue, depending on the value of the type parameter. The zValue parameter +should be NULL to cause the previous value to be freed via <a href="#sqlite3_free">sqlite3_free</a>; +a non-NULL value will be copied into memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a> +prior to being used. The <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory</a> interface returns +<a href="#SQLITE_ABORT">SQLITE_OK</a> to indicate success, <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if the type is unsupported, +or <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> if memory could not be allocated. The value of the +<a href="#sqlite3_data_directory">sqlite3_data_directory</a> variable is intended to act as a replacement for +the current directory on the sub-platforms of Win32 where that concept is +not present, e.g. WinRT and UWP. The <a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory8</a> and +<a href="#sqlite3_win32_set_directory">sqlite3_win32_set_directory16</a> interfaces behave exactly the same as the +sqlite3_win32_set_directory interface except the string parameter must be +UTF-8 or UTF-16, respectively. +</p><hr><a name="sqlite3_bind_blob"></a> +<h2>Binding Values To Prepared Statements</h2> +</div> +<blockquote><pre> +int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); +int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64, + void(*)(void*)); +int sqlite3_bind_double(sqlite3_stmt*, int, double); +int sqlite3_bind_int(sqlite3_stmt*, int, int); +int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); +int sqlite3_bind_null(sqlite3_stmt*, int); +int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); +int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); +int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, + void(*)(void*), unsigned char encoding); +int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); +int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*)); +int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); +int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); +</pre></blockquote> +<p> +In the SQL statement text input to <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and its variants, +literals may be replaced by a <a href="lang_expr.html#varparam">parameter</a> that matches one of following +templates:</p> + +<p><ul> +<li> ? +<li> ?NNN +<li> :VVV +<li> @VVV +<li> $VVV +</ul></p> + +<p>In the templates above, NNN represents an integer literal, +and VVV represents an alphanumeric identifier. The values of these +parameters (also called "host parameter names" or "SQL parameters") +can be set using the sqlite3_bind_*() routines defined here.</p> + +<p>The first argument to the sqlite3_bind_*() routines is always +a pointer to the <a href="#sqlite3_stmt">sqlite3_stmt</a> object returned from +<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or its variants.</p> + +<p>The second argument is the index of the SQL parameter to be set. +The leftmost SQL parameter has an index of 1. When the same named +SQL parameter is used more than once, second and subsequent +occurrences have the same index as the first occurrence. +The index for named parameters can be looked up using the +<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a> API if desired. The index +for "?NNN" parameters is the value of NNN. +The NNN value must be between 1 and the <a href="#sqlite3_limit">sqlite3_limit()</a> +parameter <a href="#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 32766).</p> + +<p>The third argument is the value to bind to the parameter. +If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() +or sqlite3_bind_blob() is a NULL pointer then the fourth parameter +is ignored and the end result is the same as sqlite3_bind_null(). +If the third parameter to sqlite3_bind_text() is not NULL, then +it should be a pointer to well-formed UTF8 text. +If the third parameter to sqlite3_bind_text16() is not NULL, then +it should be a pointer to well-formed UTF16 text. +If the third parameter to sqlite3_bind_text64() is not NULL, then +it should be a pointer to a well-formed unicode string that is +either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16 +otherwise.</p> + +<p><a name="byteorderdeterminationrules"></a> + The byte-order of +UTF16 input text is determined by the byte-order mark (BOM, U+FEFF) +found in first character, which is removed, or in the absence of a BOM +the byte order is the native byte order of the host +machine for sqlite3_bind_text16() or the byte order specified in +the 6th parameter for sqlite3_bind_text64(). +If UTF16 input text contains invalid unicode +characters, then SQLite might change those invalid characters +into the unicode replacement character: U+FFFD.</p> + +<p>In those routines that have a fourth argument, its value is the +number of bytes in the parameter. To be clear: the value is the +number of <u>bytes</u> in the value, not the number of characters. +If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() +is negative, then the length of the string is +the number of bytes up to the first zero terminator. +If the fourth parameter to sqlite3_bind_blob() is negative, then +the behavior is undefined. +If a non-negative fourth parameter is provided to sqlite3_bind_text() +or sqlite3_bind_text16() or sqlite3_bind_text64() then +that parameter must be the byte offset +where the NUL terminator would occur assuming the string were NUL +terminated. If any NUL characters occurs at byte offsets less than +the value of the fourth parameter then the resulting string value will +contain embedded NULs. The result of expressions involving strings +with embedded NULs is undefined.</p> + +<p>The fifth argument to the BLOB and string binding interfaces controls +or indicates the lifetime of the object referenced by the third parameter. +These three options exist: + (1) A destructor to dispose of the BLOB or string after SQLite has finished +with it may be passed. It is called to dispose of the BLOB or string even +if the call to the bind API fails, except the destructor is not called if +the third parameter is a NULL pointer or the fourth parameter is negative. + (2) The special constant, <a href="#SQLITE_STATIC">SQLITE_STATIC</a>, may be passed to indicate that +the application remains responsible for disposing of the object. In this +case, the object and the provided pointer to it must remain valid until +either the prepared statement is finalized or the same SQL parameter is +bound to something else, whichever occurs sooner. + (3) The constant, <a href="#SQLITE_STATIC">SQLITE_TRANSIENT</a>, may be passed to indicate that the +object is to be copied prior to the return from sqlite3_bind_*(). The +object and pointer to it must remain valid until then. SQLite will then +manage the lifetime of its private copy.</p> + +<p>The sixth argument to sqlite3_bind_text64() must be one of +<a href="#SQLITE_ANY">SQLITE_UTF8</a>, <a href="#SQLITE_ANY">SQLITE_UTF16</a>, <a href="#SQLITE_ANY">SQLITE_UTF16BE</a>, or <a href="#SQLITE_ANY">SQLITE_UTF16LE</a> +to specify the encoding of the text in the third parameter. If +the sixth argument to sqlite3_bind_text64() is not one of the +allowed values shown above, or if the text encoding is different +from the encoding specified by the sixth parameter, then the behavior +is undefined.</p> + +<p>The sqlite3_bind_zeroblob() routine binds a BLOB of length N that +is filled with zeroes. A zeroblob uses a fixed amount of memory +(just an integer to hold its size) while it is being processed. +Zeroblobs are intended to serve as placeholders for BLOBs whose +content is later written using +<a href="#sqlite3_blob_open">incremental BLOB I/O</a> routines. +A negative value for the zeroblob results in a zero-length BLOB.</p> + +<p>The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in +<a href="#sqlite3_stmt">prepared statement</a> S to have an SQL value of NULL, but to also be +associated with the pointer P of type T. D is either a NULL pointer or +a pointer to a destructor function for P. SQLite will invoke the +destructor D with a single argument of P when it is finished using +P. The T parameter should be a static string, preferably a string +literal. The sqlite3_bind_pointer() routine is part of the +<a href="bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p> + +<p>If any of the sqlite3_bind_*() routines are called with a NULL pointer +for the <a href="#sqlite3_stmt">prepared statement</a> or with a prepared statement for which +<a href="#sqlite3_step">sqlite3_step()</a> has been called more recently than <a href="#sqlite3_reset">sqlite3_reset()</a>, +then the call will return <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. If any sqlite3_bind_() +routine is passed a <a href="#sqlite3_stmt">prepared statement</a> that has been finalized, the +result is undefined and probably harmful.</p> + +<p>Bindings are not cleared by the <a href="#sqlite3_reset">sqlite3_reset()</a> routine. +Unbound parameters are interpreted as NULL.</p> + +<p>The sqlite3_bind_* routines return <a href="#SQLITE_ABORT">SQLITE_OK</a> on success or an +<a href="rescode.html">error code</a> if anything goes wrong. +<a href="#SQLITE_ABORT">SQLITE_TOOBIG</a> might be returned if the size of a string or BLOB +exceeds limits imposed by <a href="#sqlite3_limit">sqlite3_limit</a>(<a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>) or +<a href="limits.html#max_length">SQLITE_MAX_LENGTH</a>. +<a href="#SQLITE_ABORT">SQLITE_RANGE</a> is returned if the parameter +index is out of range. <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> is returned if malloc() fails.</p> + +<p>See also: <a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, +<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and <a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>. +</p><hr><a name="sqlite3_prepare"></a> +<h2>Compiling An SQL Statement</h2> +</div> +<blockquote><pre> +int sqlite3_prepare( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare_v2( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare_v3( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare16( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare16_v2( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare16_v3( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +</pre></blockquote> +<p> +To execute an SQL statement, it must first be compiled into a byte-code +program using one of these routines. Or, in other words, these routines +are constructors for the <a href="#sqlite3_stmt">prepared statement</a> object.</p> + +<p>The preferred routine to use is <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>. The +<a href="#sqlite3_prepare">sqlite3_prepare()</a> interface is legacy and should be avoided. +<a href="#sqlite3_prepare">sqlite3_prepare_v3()</a> has an extra "prepFlags" option that is used +for special purposes.</p> + +<p>The use of the UTF-8 interfaces is preferred, as SQLite currently +does all parsing using UTF-8. The UTF-16 interfaces are provided +as a convenience. The UTF-16 interfaces work by converting the +input text into UTF-8, then invoking the corresponding UTF-8 interface.</p> + +<p>The first argument, "db", is a <a href="#sqlite3">database connection</a> obtained from a +prior successful call to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a> or +<a href="#sqlite3_open">sqlite3_open16()</a>. The database connection must not have been closed.</p> + +<p>The second argument, "zSql", is the statement to be compiled, encoded +as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(), +and sqlite3_prepare_v3() +interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(), +and sqlite3_prepare16_v3() use UTF-16.</p> + +<p>If the nByte argument is negative, then zSql is read up to the +first zero terminator. If nByte is positive, then it is the +number of bytes read from zSql. If nByte is zero, then no prepared +statement is generated. +If the caller knows that the supplied string is nul-terminated, then +there is a small performance advantage to passing an nByte parameter that +is the number of bytes in the input string <i>including</i> +the nul-terminator.</p> + +<p>If pzTail is not NULL then *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 statement in zSql, so *pzTail is left pointing to +what remains uncompiled.</p> + +<p>*ppStmt is left pointing to a compiled <a href="#sqlite3_stmt">prepared statement</a> that can be +executed using <a href="#sqlite3_step">sqlite3_step()</a>. If there is an error, *ppStmt is set +to NULL. If the input text contains no SQL (if the input is an empty +string or a comment) then *ppStmt is set to NULL. +The calling procedure is responsible for deleting the compiled +SQL statement using <a href="#sqlite3_finalize">sqlite3_finalize()</a> after it has finished with it. +ppStmt may not be NULL.</p> + +<p>On success, the sqlite3_prepare() family of routines return <a href="#SQLITE_ABORT">SQLITE_OK</a>; +otherwise an <a href="rescode.html">error code</a> is returned.</p> + +<p>The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(), +and sqlite3_prepare16_v3() interfaces are recommended for all new programs. +The older interfaces (sqlite3_prepare() and sqlite3_prepare16()) +are retained for backwards compatibility, but their use is discouraged. +In the "vX" interfaces, the prepared statement +that is returned (the <a href="#sqlite3_stmt">sqlite3_stmt</a> object) contains a copy of the +original SQL text. This causes the <a href="#sqlite3_step">sqlite3_step()</a> interface to +behave differently in three ways:</p> + +<p><ol> +<li> +If the database schema changes, instead of returning <a href="#SQLITE_ABORT">SQLITE_SCHEMA</a> as it +always used to do, <a href="#sqlite3_step">sqlite3_step()</a> will automatically recompile the SQL +statement and try to run it again. As many as <a href="compile.html#max_schema_retry">SQLITE_MAX_SCHEMA_RETRY</a> +retries will occur before sqlite3_step() gives up and returns an error. +</li></p> + +<p><li> +When an error occurs, <a href="#sqlite3_step">sqlite3_step()</a> will return one of the detailed +<a href="rescode.html">error codes</a> or <a href="rescode.html#extrc">extended error codes</a>. The legacy behavior was that +<a href="#sqlite3_step">sqlite3_step()</a> would only return a generic <a href="#SQLITE_ABORT">SQLITE_ERROR</a> result code +and the application would have to make a second call to <a href="#sqlite3_reset">sqlite3_reset()</a> +in order to find the underlying cause of the problem. With the "v2" prepare +interfaces, the underlying reason for the error is returned immediately. +</li></p> + +<p><li> +If the specific value bound to a <a href="lang_expr.html#varparam">host parameter</a> in the +WHERE clause might influence the choice of query plan for a statement, +then the statement will be automatically recompiled, as if there had been +a schema change, on the first <a href="#sqlite3_step">sqlite3_step()</a> call following any change +to the <a href="#sqlite3_bind_blob">bindings</a> of that <a href="lang_expr.html#varparam">parameter</a>. +The specific value of a WHERE-clause <a href="lang_expr.html#varparam">parameter</a> might influence the +choice of query plan if the parameter is the left-hand side of a <a href="lang_expr.html#like">LIKE</a> +or <a href="lang_expr.html#glob">GLOB</a> operator or if the parameter is compared to an indexed column +and the <a href="compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a> compile-time option is enabled. +</li> +</ol></p> + +<p><p>sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having +the extra prepFlags parameter, which is a bit array consisting of zero or +more of the <a href="#sqlitepreparepersistent">SQLITE_PREPARE_*</a> flags. The +sqlite3_prepare_v2() interface works exactly the same as +sqlite3_prepare_v3() with a zero prepFlags parameter. +</p><hr><a name="sqlite3_set_authorizer"></a> +<h2>Compile-Time Authorization Callbacks</h2> +</div> +<blockquote><pre> +int sqlite3_set_authorizer( + sqlite3*, + int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), + void *pUserData +); +</pre></blockquote> +<p> +This routine registers an authorizer callback with a particular +<a href="#sqlite3">database connection</a>, supplied in the first argument. +The authorizer callback is invoked as SQL statements are being compiled +by <a href="#sqlite3_prepare">sqlite3_prepare()</a> or its variants <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, +<a href="#sqlite3_prepare">sqlite3_prepare_v3()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16()</a>, <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>, +and <a href="#sqlite3_prepare">sqlite3_prepare16_v3()</a>. At various +points during the compilation process, as logic is being created +to perform various actions, the authorizer callback is invoked to +see if those actions are allowed. The authorizer callback should +return <a href="#SQLITE_ABORT">SQLITE_OK</a> to allow the action, <a href="#SQLITE_DENY">SQLITE_IGNORE</a> to disallow the +specific action but allow the SQL statement to continue to be +compiled, or <a href="#SQLITE_DENY">SQLITE_DENY</a> to cause the entire SQL statement to be +rejected with an error. If the authorizer callback returns +any value other than <a href="#SQLITE_DENY">SQLITE_IGNORE</a>, <a href="#SQLITE_ABORT">SQLITE_OK</a>, or <a href="#SQLITE_DENY">SQLITE_DENY</a> +then the <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or equivalent call that triggered +the authorizer will fail with an error message.</p> + +<p>When the callback returns <a href="#SQLITE_ABORT">SQLITE_OK</a>, that means the operation +requested is ok. When the callback returns <a href="#SQLITE_DENY">SQLITE_DENY</a>, the +<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or equivalent call that triggered the +authorizer will fail with an error message explaining that +access is denied.</p> + +<p>The first parameter to the authorizer callback is a copy of the third +parameter to the sqlite3_set_authorizer() interface. The second parameter +to the callback is an integer <a href="#SQLITE_ALTER_TABLE">action code</a> that specifies +the particular action to be authorized. The third through sixth parameters +to the callback are either NULL pointers or zero-terminated strings +that contain additional details about the action to be authorized. +Applications must always be prepared to encounter a NULL pointer in any +of the third through the sixth parameters of the authorization callback.</p> + +<p>If the action code is <a href="#SQLITE_ALTER_TABLE">SQLITE_READ</a> +and the callback returns <a href="#SQLITE_DENY">SQLITE_IGNORE</a> then the +<a href="#sqlite3_stmt">prepared statement</a> statement is constructed to substitute +a NULL value in place of the table column that would have +been read if <a href="#SQLITE_ABORT">SQLITE_OK</a> had been returned. The <a href="#SQLITE_DENY">SQLITE_IGNORE</a> +return can be used to deny an untrusted user access to individual +columns of a table. +When a table is referenced by a <a href="lang_select.html">SELECT</a> but no column values are +extracted from that table (for example in a query like +"SELECT count(*) FROM tab") then the <a href="#SQLITE_ALTER_TABLE">SQLITE_READ</a> authorizer callback +is invoked once for that table with a column name that is an empty string. +If the action code is <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a> and the callback returns +<a href="#SQLITE_DENY">SQLITE_IGNORE</a> then the <a href="lang_delete.html">DELETE</a> operation proceeds but the +<a href="lang_delete.html#truncateopt">truncate optimization</a> is disabled and all rows are deleted individually.</p> + +<p>An authorizer is used when <a href="#sqlite3_prepare">preparing</a> +SQL statements from an untrusted source, to ensure that the SQL statements +do not try to access data they are not allowed to see, or that they do not +try to execute malicious statements that damage the database. For +example, an application may allow a user to enter arbitrary +SQL queries for evaluation by a database. But the application does +not want the user to be able to make arbitrary changes to the +database. An authorizer could then be put in place while the +user-entered SQL is being <a href="#sqlite3_prepare">prepared</a> that +disallows everything except <a href="lang_select.html">SELECT</a> statements.</p> + +<p>Applications that need to process SQL from untrusted sources +might also consider lowering resource limits using <a href="#sqlite3_limit">sqlite3_limit()</a> +and limiting database size using the <a href="pragma.html#pragma_max_page_count">max_page_count</a> <a href="pragma.html#syntax">PRAGMA</a> +in addition to using an authorizer.</p> + +<p>Only a single authorizer can be in place on a database connection +at a time. Each call to sqlite3_set_authorizer overrides the +previous call. Disable the authorizer by installing a NULL callback. +The authorizer is disabled by default.</p> + +<p>The authorizer callback must not do anything that will modify +the database connection that invoked the authorizer callback. +Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their +database connections for the meaning of "modify" in this paragraph.</p> + +<p>When <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> is used to prepare a statement, the +statement might be re-prepared during <a href="#sqlite3_step">sqlite3_step()</a> due to a +schema change. Hence, the application should ensure that the +correct authorizer callback remains in place during the <a href="#sqlite3_step">sqlite3_step()</a>.</p> + +<p>Note that the authorizer callback is invoked only during +<a href="#sqlite3_prepare">sqlite3_prepare()</a> or its variants. Authorization is not +performed during statement evaluation in <a href="#sqlite3_step">sqlite3_step()</a>, unless +as stated in the previous paragraph, sqlite3_step() invokes +sqlite3_prepare_v2() to reprepare a statement after a schema change. +</p><hr><a name="sqlite3_get_autocommit"></a> +<h2>Test For Auto-Commit Mode</h2> +</div> +<blockquote><pre> +int sqlite3_get_autocommit(sqlite3*); +</pre></blockquote> +<p> +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. +Autocommit mode is disabled by a <a href="lang_transaction.html">BEGIN</a> statement. +Autocommit mode is re-enabled by a <a href="lang_transaction.html">COMMIT</a> or <a href="lang_transaction.html">ROLLBACK</a>.</p> + +<p>If certain kinds of errors occur on a statement within a multi-statement +transaction (errors including <a href="#SQLITE_ABORT">SQLITE_FULL</a>, <a href="#SQLITE_ABORT">SQLITE_IOERR</a>, +<a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, and <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>) then the +transaction might be rolled back automatically. The only way to +find out whether SQLite automatically rolled back the transaction after +an error is to use this function.</p> + +<p>If another thread changes the autocommit status of the database +connection while this routine is running, then the return value +is undefined. +</p><hr><a name="sqlite3_busy_handler"></a> +<h2>Register A Callback To Handle SQLITE_BUSY Errors</h2> +</div> +<blockquote><pre> +int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*); +</pre></blockquote> +<p> +The sqlite3_busy_handler(D,X,P) routine sets a callback function X +that might be invoked with argument P whenever +an attempt is made to access a database table associated with +<a href="#sqlite3">database connection</a> D when another thread +or process has the table locked. +The sqlite3_busy_handler() interface is used to implement +<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> and <a href="pragma.html#pragma_busy_timeout">PRAGMA busy_timeout</a>.</p> + +<p>If the busy callback is NULL, then <a href="#SQLITE_ABORT">SQLITE_BUSY</a> +is returned immediately upon encountering the lock. If the busy callback +is not NULL, then the callback might be invoked with two arguments.</p> + +<p>The first argument to the busy handler is a copy of the void* pointer which +is the third argument to sqlite3_busy_handler(). The second argument to +the busy handler callback is the number of times that the busy handler has +been invoked previously for the same locking event. If the +busy callback returns 0, then no additional attempts are made to +access the database and <a href="#SQLITE_ABORT">SQLITE_BUSY</a> is returned +to the application. +If the callback returns non-zero, then another attempt +is made to access the database and the cycle repeats.</p> + +<p>The presence of a busy handler does not guarantee that it will be invoked +when there is lock contention. If SQLite determines that invoking the busy +handler could result in a deadlock, it will go ahead and return <a href="#SQLITE_ABORT">SQLITE_BUSY</a> +to the application instead of invoking the +busy handler. +Consider a scenario where one process is holding a read lock that +it is trying to promote to a reserved lock and +a second process is holding a reserved lock that it is trying +to promote to an exclusive lock. The first process cannot proceed +because it is blocked by the second and the second process cannot +proceed because it is blocked by the first. If both processes +invoke the busy handlers, neither will make any progress. Therefore, +SQLite returns <a href="#SQLITE_ABORT">SQLITE_BUSY</a> for the first process, hoping that this +will induce the first process to release its read lock and allow +the second process to proceed.</p> + +<p>The default busy callback is NULL.</p> + +<p>There can only be a single busy handler defined for each +<a href="#sqlite3">database connection</a>. Setting a new busy handler clears any +previously set handler. Note that calling <a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> +or evaluating <a href="pragma.html#pragma_busy_timeout">PRAGMA busy_timeout=N</a> will change the +busy handler and thus clear any previously set busy handler.</p> + +<p>The busy callback should not take any actions which modify the +database connection that invoked the busy handler. In other words, +the busy handler is not reentrant. Any such actions +result in undefined behavior.</p> + +<p>A busy handler must not close the database connection +or <a href="#sqlite3_stmt">prepared statement</a> that invoked the busy handler. +</p><hr><a name="sqlite3_column_blob"></a> +<h2>Result Values From A Query</h2> +</div> +<blockquote><pre> +const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); +double sqlite3_column_double(sqlite3_stmt*, int iCol); +int sqlite3_column_int(sqlite3_stmt*, int iCol); +sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); +const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); +const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); +sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); +int sqlite3_column_bytes(sqlite3_stmt*, int iCol); +int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); +int sqlite3_column_type(sqlite3_stmt*, int iCol); +</pre></blockquote> +<p> +<b>Summary:</b> +<blockquote><table border=0 cellpadding=0 cellspacing=0> +<tr><td><b>sqlite3_column_blob</b><td>→<td>BLOB result +<tr><td><b>sqlite3_column_double</b><td>→<td>REAL result +<tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result +<tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result +<tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result +<tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result +<tr><td><b>sqlite3_column_value</b><td>→<td>The result as an +<a href="#sqlite3_value">unprotected sqlite3_value</a> object. +<tr><td> <td> <td> +<tr><td><b>sqlite3_column_bytes</b><td>→<td>Size of a BLOB +or a UTF-8 TEXT result in bytes +<tr><td><b>sqlite3_column_bytes16 </b> +<td>→ <td>Size of UTF-16 +TEXT in bytes +<tr><td><b>sqlite3_column_type</b><td>→<td>Default +datatype of the result +</table></blockquote></p> + +<p><b>Details:</b></p> + +<p>These routines return information about a single column of the current +result row of a query. In every case the first argument is a pointer +to the <a href="#sqlite3_stmt">prepared statement</a> that is being evaluated (the <a href="#sqlite3_stmt">sqlite3_stmt*</a> +that was returned from <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or one of its variants) +and the second argument is the index of the column for which information +should be returned. The leftmost column of the result set has the index 0. +The number of columns in the result can be determined using +<a href="#sqlite3_column_count">sqlite3_column_count()</a>.</p> + +<p>If the SQL statement does not currently point to a valid row, or if the +column index is out of range, the result is undefined. +These routines may only be called when the most recent call to +<a href="#sqlite3_step">sqlite3_step()</a> has returned <a href="#SQLITE_ABORT">SQLITE_ROW</a> and neither +<a href="#sqlite3_reset">sqlite3_reset()</a> nor <a href="#sqlite3_finalize">sqlite3_finalize()</a> have been called subsequently. +If any of these routines are called after <a href="#sqlite3_reset">sqlite3_reset()</a> or +<a href="#sqlite3_finalize">sqlite3_finalize()</a> or after <a href="#sqlite3_step">sqlite3_step()</a> has returned +something other than <a href="#SQLITE_ABORT">SQLITE_ROW</a>, the results are undefined. +If <a href="#sqlite3_step">sqlite3_step()</a> or <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a> +are called from a different thread while any of these routines +are pending, then the results are undefined.</p> + +<p>The first six interfaces (_blob, _double, _int, _int64, _text, and _text16) +each return the value of a result column in a specific data format. If +the result column is not initially in the requested format (for example, +if the query returns an integer but the sqlite3_column_text() interface +is used to extract the value) then an automatic type conversion is performed.</p> + +<p>The sqlite3_column_type() routine returns the +<a href="#SQLITE_BLOB">datatype code</a> for the initial data type +of the result column. The returned value is one of <a href="#SQLITE_BLOB">SQLITE_INTEGER</a>, +<a href="#SQLITE_BLOB">SQLITE_FLOAT</a>, <a href="#SQLITE_BLOB">SQLITE_TEXT</a>, <a href="#SQLITE_BLOB">SQLITE_BLOB</a>, or <a href="#SQLITE_BLOB">SQLITE_NULL</a>. +The return value of sqlite3_column_type() can be used to decide which +of the first six interface should be used to extract the column value. +The value returned by sqlite3_column_type() is only meaningful if no +automatic type conversions have occurred for the value in question. +After a type conversion, the result of calling sqlite3_column_type() +is undefined, though harmless. Future +versions of SQLite may change the behavior of sqlite3_column_type() +following a type conversion.</p> + +<p>If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes() +or sqlite3_column_bytes16() interfaces can be used to determine the size +of that BLOB or string.</p> + +<p>If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() +routine returns the number of bytes in that BLOB or string. +If the result is a UTF-16 string, then sqlite3_column_bytes() converts +the string to UTF-8 and then returns the number of bytes. +If the result is a numeric value then sqlite3_column_bytes() uses +<a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to convert that value to a UTF-8 string and returns +the number of bytes in that string. +If the result is NULL, then sqlite3_column_bytes() returns zero.</p> + +<p>If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() +routine returns the number of bytes in that BLOB or string. +If the result is a UTF-8 string, then sqlite3_column_bytes16() converts +the string to UTF-16 and then returns the number of bytes. +If the result is a numeric value then sqlite3_column_bytes16() uses +<a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to convert that value to a UTF-16 string and returns +the number of bytes in that string. +If the result is NULL, then sqlite3_column_bytes16() returns zero.</p> + +<p>The values returned by <a href="#sqlite3_column_blob">sqlite3_column_bytes()</a> and +<a href="#sqlite3_column_blob">sqlite3_column_bytes16()</a> do not include the zero terminators at the end +of the string. For clarity: the values returned by +<a href="#sqlite3_column_blob">sqlite3_column_bytes()</a> and <a href="#sqlite3_column_blob">sqlite3_column_bytes16()</a> are the number of +bytes in the string, not the number of characters.</p> + +<p>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 a NULL pointer.</p> + +<p>Strings returned by sqlite3_column_text16() always have the endianness +which is native to the platform, regardless of the text encoding set +for the database.</p> + +<p><b>Warning:</b> The object returned by <a href="#sqlite3_column_blob">sqlite3_column_value()</a> is an +<a href="#sqlite3_value">unprotected sqlite3_value</a> object. In a multithreaded environment, +an unprotected sqlite3_value object may only be used safely with +<a href="#sqlite3_bind_blob">sqlite3_bind_value()</a> and <a href="#sqlite3_result_blob">sqlite3_result_value()</a>. +If the <a href="#sqlite3_value">unprotected sqlite3_value</a> object returned by +<a href="#sqlite3_column_blob">sqlite3_column_value()</a> is used in any other way, including calls +to routines like <a href="#sqlite3_value_blob">sqlite3_value_int()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>, +or <a href="#sqlite3_value_blob">sqlite3_value_bytes()</a>, the behavior is not threadsafe. +Hence, the sqlite3_column_value() interface +is normally only useful within the implementation of +<a href="appfunc.html">application-defined SQL functions</a> or <a href="vtab.html">virtual tables</a>, not within +top-level application code.</p> + +<p>These routines may attempt to convert the datatype of the result. +For example, if the internal representation is FLOAT and a text result +is requested, <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> is used internally to perform the +conversion automatically. The following table details the conversions +that are applied:</p> + +<p><blockquote> +<table border="1"> +<tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion</p> + +<p><tr><td> NULL <td> INTEGER <td> Result is 0 +<tr><td> NULL <td> FLOAT <td> Result is 0.0 +<tr><td> NULL <td> TEXT <td> Result is a NULL pointer +<tr><td> NULL <td> BLOB <td> Result is a NULL pointer +<tr><td> INTEGER <td> FLOAT <td> Convert from integer to float +<tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer +<tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT +<tr><td> FLOAT <td> INTEGER <td> <a href="lang_expr.html#castexpr">CAST</a> to INTEGER +<tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float +<tr><td> FLOAT <td> BLOB <td> <a href="lang_expr.html#castexpr">CAST</a> to BLOB +<tr><td> TEXT <td> INTEGER <td> <a href="lang_expr.html#castexpr">CAST</a> to INTEGER +<tr><td> TEXT <td> FLOAT <td> <a href="lang_expr.html#castexpr">CAST</a> to REAL +<tr><td> TEXT <td> BLOB <td> No change +<tr><td> BLOB <td> INTEGER <td> <a href="lang_expr.html#castexpr">CAST</a> to INTEGER +<tr><td> BLOB <td> FLOAT <td> <a href="lang_expr.html#castexpr">CAST</a> to REAL +<tr><td> BLOB <td> TEXT <td> <a href="lang_expr.html#castexpr">CAST</a> to TEXT, ensure zero terminator +</table> +</blockquote></p> + +<p>Note that when type conversions occur, pointers returned by prior +calls to sqlite3_column_blob(), sqlite3_column_text(), and/or +sqlite3_column_text16() may be invalidated. +Type conversions and pointer invalidations might occur +in the following cases:</p> + +<p><ul> +<li> The initial content is a BLOB and sqlite3_column_text() or +sqlite3_column_text16() is called. A zero-terminator might +need to be added to the string.</li> +<li> The initial content is UTF-8 text and sqlite3_column_bytes16() or +sqlite3_column_text16() is called. The content must be converted +to UTF-16.</li> +<li> The initial content is UTF-16 text and sqlite3_column_bytes() or +sqlite3_column_text() is called. The content must be converted +to UTF-8.</li> +</ul></p> + +<p>Conversions between UTF-16be and UTF-16le are always done in place and do +not invalidate a prior pointer, though of course the content of the buffer +that the prior pointer references will have been modified. Other kinds +of conversion are done in place when it is possible, but sometimes they +are not possible and in those cases prior pointers are invalidated.</p> + +<p>The safest policy is to invoke these routines +in one of the following ways:</p> + +<p><ul> +<li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> +<li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> +<li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> +</ul></p> + +<p>In other words, you should call sqlite3_column_text(), +sqlite3_column_blob(), or sqlite3_column_text16() first to force the result +into the desired format, then invoke sqlite3_column_bytes() or +sqlite3_column_bytes16() to find the size of the result. Do not mix calls +to sqlite3_column_text() or sqlite3_column_blob() with calls to +sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() +with calls to sqlite3_column_bytes().</p> + +<p>The pointers returned are valid until a type conversion occurs as +described above, or until <a href="#sqlite3_step">sqlite3_step()</a> or <a href="#sqlite3_reset">sqlite3_reset()</a> or +<a href="#sqlite3_finalize">sqlite3_finalize()</a> is called. The memory space used to hold strings +and BLOBs is freed automatically. Do not pass the pointers returned +from <a href="#sqlite3_column_blob">sqlite3_column_blob()</a>, <a href="#sqlite3_column_blob">sqlite3_column_text()</a>, etc. into +<a href="#sqlite3_free">sqlite3_free()</a>.</p> + +<p>As long as the input parameters are correct, these routines will only +fail if an out-of-memory error occurs during a format conversion. +Only the following subset of interfaces are subject to out-of-memory +errors:</p> + +<p><ul> +<li> sqlite3_column_blob() +<li> sqlite3_column_text() +<li> sqlite3_column_text16() +<li> sqlite3_column_bytes() +<li> sqlite3_column_bytes16() +</ul></p> + +<p>If an out-of-memory error occurs, then the return value from these +routines is the same as if the column had contained an SQL NULL value. +Valid SQL NULL returns can be distinguished from out-of-memory errors +by invoking the <a href="#sqlite3_errcode">sqlite3_errcode()</a> immediately after the suspect +return value is obtained and before any +other SQLite interface is called on the same <a href="#sqlite3">database connection</a>. +</p><hr><a name="sqlite3_file_control"></a> +<h2>Low-Level Control Of Database Files</h2> +</div> +<blockquote><pre> +int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); +</pre></blockquote> +<p> +The <a href="#sqlite3_file_control">sqlite3_file_control()</a> interface makes a direct call to the +xFileControl method for the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object associated +with a particular database identified by the second argument. The +name of the database is "main" for the main database or "temp" for the +TEMP database, or the name that appears after the AS keyword for +databases that are added using the <a href="lang_attach.html">ATTACH</a> SQL command. +A NULL pointer can be used in place of "main" to refer to the +main database file. +The third and fourth parameters to this routine +are passed directly through to the second and third parameters of +the xFileControl method. The return value of the xFileControl +method becomes the return value of this routine.</p> + +<p>A few opcodes for <a href="#sqlite3_file_control">sqlite3_file_control()</a> are handled directly +by the SQLite core and never invoke the +sqlite3_io_methods.xFileControl method. +The <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> value for the op parameter causes +a pointer to the underlying <a href="#sqlite3_file">sqlite3_file</a> object to be written into +the space pointed to by the 4th parameter. The +<a href="#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a> works similarly except that it returns +the <a href="#sqlite3_file">sqlite3_file</a> object associated with the journal file instead of +the main database. The <a href="#sqlitefcntlvfspointer">SQLITE_FCNTL_VFS_POINTER</a> opcode returns +a pointer to the underlying <a href="#sqlite3_vfs">sqlite3_vfs</a> object for the file. +The <a href="#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> returns the data version counter +from the pager.</p> + +<p>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 <a href="#sqlite3_errcode">sqlite3_errcode()</a> +or <a href="#sqlite3_errcode">sqlite3_errmsg()</a>. 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.</p> + +<p>See also: <a href="#SQLITE_FCNTL_BEGIN_ATOMIC_WRITE">file control opcodes</a> +</p><hr><a name="sqlite3_create_function"></a> +<h2>Create Or Redefine SQL Functions</h2> +</div> +<blockquote><pre> +int sqlite3_create_function( + sqlite3 *db, + const char *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*) +); +int sqlite3_create_function16( + sqlite3 *db, + const void *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*) +); +int sqlite3_create_function_v2( + sqlite3 *db, + const char *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*), + void(*xDestroy)(void*) +); +int sqlite3_create_window_function( + sqlite3 *db, + const char *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*), + void (*xValue)(sqlite3_context*), + void (*xInverse)(sqlite3_context*,int,sqlite3_value**), + void(*xDestroy)(void*) +); +</pre></blockquote> +<p> +These functions (collectively known as "function creation routines") +are used to add SQL functions or aggregates or to redefine the behavior +of existing SQL functions or aggregates. The only differences between +the three "sqlite3_create_function*" routines are the text encoding +expected for the second parameter (the name of the function being +created) and the presence or absence of a destructor callback for +the application data pointer. Function sqlite3_create_window_function() +is similar, but allows the user to supply the extra callback functions +needed by <a href="windowfunctions.html#aggwinfunc">aggregate window functions</a>.</p> + +<p>The first parameter is the <a href="#sqlite3">database connection</a> to which the SQL +function is to be added. If an application uses more than one database +connection then application-defined SQL functions must be added +to each database connection separately.</p> + +<p>The second parameter is the name of the SQL function to be created or +redefined. The length of the name is limited to 255 bytes in a UTF-8 +representation, exclusive of the zero-terminator. Note that the name +length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. +Any attempt to create a function with a longer name +will result in <a href="#SQLITE_ABORT">SQLITE_MISUSE</a> being returned.</p> + +<p>The third parameter (nArg) +is the number of arguments that the SQL function or +aggregate takes. If this parameter is -1, then the SQL function or +aggregate may take any number of arguments between 0 and the limit +set by <a href="#sqlite3_limit">sqlite3_limit</a>(<a href="#sqlitelimitfunctionarg">SQLITE_LIMIT_FUNCTION_ARG</a>). If the third +parameter is less than -1 or greater than 127 then the behavior is +undefined.</p> + +<p>The fourth parameter, eTextRep, specifies what +<a href="#SQLITE_ANY">text encoding</a> this SQL function prefers for +its parameters. The application should set this parameter to +<a href="#SQLITE_ANY">SQLITE_UTF16LE</a> if the function implementation invokes +<a href="#sqlite3_value_blob">sqlite3_value_text16le()</a> on an input, or <a href="#SQLITE_ANY">SQLITE_UTF16BE</a> if the +implementation invokes <a href="#sqlite3_value_blob">sqlite3_value_text16be()</a> on an input, or +<a href="#SQLITE_ANY">SQLITE_UTF16</a> if <a href="#sqlite3_value_blob">sqlite3_value_text16()</a> is used, or <a href="#SQLITE_ANY">SQLITE_UTF8</a> +otherwise. The same SQL function may be registered multiple times using +different preferred text encodings, with different implementations for +each encoding. +When multiple implementations of the same function are available, SQLite +will pick the one that involves the least amount of data conversion.</p> + +<p>The fourth parameter may optionally be ORed with <a href="#sqlitedeterministic">SQLITE_DETERMINISTIC</a> +to signal that the function will always return the same result given +the same inputs within a single SQL statement. Most SQL functions are +deterministic. The built-in <a href="lang_corefunc.html#random">random()</a> SQL function is an example of a +function that is not deterministic. The SQLite query planner is able to +perform additional optimizations on deterministic functions, so use +of the <a href="#sqlitedeterministic">SQLITE_DETERMINISTIC</a> flag is recommended where possible.</p> + +<p>The fourth parameter may also optionally include the <a href="#sqlitedirectonly">SQLITE_DIRECTONLY</a> +flag, which if present prevents the function from being invoked from +within VIEWs, TRIGGERs, CHECK constraints, generated column expressions, +index expressions, or the WHERE clause of partial indexes.</p> + +<p>For best security, the <a href="#sqlitedirectonly">SQLITE_DIRECTONLY</a> flag is recommended for +all application-defined SQL functions that do not need to be +used inside of triggers, view, CHECK constraints, or other elements of +the database schema. This flags is especially recommended for SQL +functions that have side effects or reveal internal application state. +Without this flag, an attacker might be able to modify the schema of +a database file to include invocations of the function with parameters +chosen by the attacker, which the application will then execute when +the database file is opened and read.</p> + +<p>The fifth parameter is an arbitrary pointer. The implementation of the +function can gain access to this pointer using <a href="#sqlite3_user_data">sqlite3_user_data()</a>.</p> + +<p>The sixth, seventh and eighth parameters passed to the three +"sqlite3_create_function*" functions, xFunc, xStep and xFinal, are +pointers to C-language functions that implement the SQL function or +aggregate. A scalar SQL function requires an implementation of the xFunc +callback only; NULL pointers must be passed as the xStep and xFinal +parameters. An aggregate SQL function requires an implementation of xStep +and xFinal and NULL pointer must be passed for xFunc. To delete an existing +SQL function or aggregate, pass NULL pointers for all three function +callbacks.</p> + +<p>The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue +and xInverse) passed to sqlite3_create_window_function are pointers to +C-language callbacks that implement the new function. xStep and xFinal +must both be non-NULL. xValue and xInverse may either both be NULL, in +which case a regular aggregate function is created, or must both be +non-NULL, in which case the new function may be used as either an aggregate +or aggregate window function. More details regarding the implementation +of aggregate window functions are +<a href="windowfunctions.html#udfwinfunc">available here</a>.</p> + +<p>If the final parameter to sqlite3_create_function_v2() or +sqlite3_create_window_function() is not NULL, then it is destructor for +the application data pointer. The destructor is invoked when the function +is deleted, either by being overloaded or when the database connection +closes. The destructor is also invoked if the call to +sqlite3_create_function_v2() fails. When the destructor callback is +invoked, it is passed a single argument which is a copy of the application +data pointer which was the fifth parameter to sqlite3_create_function_v2().</p> + +<p>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 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 +matches the database encoding is a better +match than a function where the encoding is different. +A function where the encoding difference is between UTF16le and UTF16be +is a closer match than a function where the encoding difference is +between UTF8 and UTF16.</p> + +<p>Built-in functions may be overloaded by new application-defined functions.</p> + +<p>An application-defined function is permitted to call other +SQLite interfaces. However, such calls must not +close the database connection nor finalize or reset the prepared +statement in which the function is running. +</p><hr> + + |