~ubuntu-branches/ubuntu/wily/sqlite3/wily : revision 0.34.1

1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

2

3

4

<title>C/C++ Interface For SQLite Version 3</title>

5

6

body {

7

margin: auto;

8

font-family: Verdana, sans-serif;

9

padding: 8px 1%;

10

}

11

12

a { color: #044a64 }

13

a:visited { color: #734559 }

14

15

.logo { position:absolute; margin:3px; }

16

.tagline {

17

float:right;

18

text-align:right;

19

font-style:italic;

20

width:300px;

21

margin:12px;

22

margin-top:58px;

23

}

24

25

.toolbar {

26

text-align: center;

27

line-height: 1.6em;

28

margin: 0;

29

padding: 0px 8px;

30

}

31

.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }

32

.toolbar a:visited { color: white; }

33

.toolbar a:hover { color: #044a64; background: white; }

34

35

.content { margin: 5%; }

36

.content dt { font-weight:bold; }

37

.content dd { margin-bottom: 25px; margin-left:20%; }

38

.content ul { padding:0px; padding-left: 15px; margin:0px; }

39

40

/* rounded corners */

41

.se { background: url(images/se.gif) 100% 100% no-repeat #044a64}

42

.sw { background: url(images/sw.gif) 0% 100% no-repeat }

43

.ne { background: url(images/ne.gif) 100% 0% no-repeat }

44

.nw { background: url(images/nw.gif) 0% 0% no-repeat }

45

46

/* Things for "fancyformat" documents start here. */

47

.fancy img+p {font-style:italic}

48

.fancy .codeblock i { color: darkblue; }

49

.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}

50

.fancy h2 { margin-left: 10px }

51

.fancy h3 { margin-left: 20px }

52

.fancy h4 { margin-left: 30px }

53

.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}

54

.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}

55

.fancy #toc a { color: darkblue ; text-decoration: none }

56

.fancy .todo { color: #AA3333 ; font-style : italic }

57

.fancy .todo:before { content: 'TODO:' }

58

.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }

59

.fancy img { display:block; }

60

.fancy :link:hover, .fancy :visited:hover { background: wheat }

61

.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }

62

.fancy li p { margin: 1em 0 }

63

/* End of "fancyformat" specific rules. */

64

65

</style>

66

67

</head>

68

<body>

69

70

71

72

<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"

73

border="0"></a>

74

75

<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>

76

77

78

79

80

81

82

<a href="about.html">About</a>

83

<a href="sitemap.html">Sitemap</a>

84

<a href="docs.html">Documentation</a>

85

<a href="download.html">Download</a>

86

<a href="copyright.html">License</a>

87

88

<a href="support.html">Support</a>

89

</div>

90

91

gMsg = "Search SQLite Docs..."

92

function entersearch() {

93

var q = document.getElementById("q");

94

if( q.value == gMsg ) { q.value = "" }

95

q.style.color = "black"

96

q.style.fontStyle = "normal"

97

}

98

function leavesearch() {

99

var q = document.getElementById("q");

100

if( q.value == "" ) {

101

q.value = gMsg

102

q.style.color = "#044a64"

103

q.style.fontStyle = "italic"

104

}

105

}

106

</script>

107

<td>

108

109

110

<input id=q name=q type=text

111

onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

121

122

<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>

123

124

125

126

<p>This page defined the C-language interface to SQLite.</p>

127

128

<p>This is not a tutorial. These

129

pages are designed to be precise, not easy to read.

130

For a tutorial introduction see

131

<a href="quickstart.html">SQLite In 3 Minutes Or Less</a> and/or

132

the <a href="cintro.html">Introduction To The SQLite C/C++ Interface</a>.

133

</p>

134

135

<p>This page contains all C-language interface information

136

in a single HTML file. The same information is also

137

available broken out into

138

<a href="c3ref/intro.html">lots of small pages</a>

139

for easier viewing, if you prefer.</p>

140

141

<p>This document is created by a script which scans comments

142

in the source code files.</p>

143

144

<hr>

145

146

147

148

<h2>Experimental And Deprecated Interfaces</h2>

149

150

<p>SQLite interfaces can be subdivided into three categories:</p>

151

152

<ol>

153

<li>Stable</li>

154

<li>Experimental</li>

155

<li>Deprecated</li>

156

</ol>

157

158

<p>Stable interfaces will be maintained indefinitely in a backwards

159

compatible way. An application that uses only stable interfaces

160

should always be able to relink against a newer version of SQLite

161

without any changes.</p>

162

163

<p>Experimental interfaces are subject to change.

164

Applications that use experimental interfaces

165

may need to be modified when upgrading to a newer SQLite release, though

166

this is rare.

167

When new interfaces are added to SQLite, they generally begin

168

as experimental interfaces. After an interface has been in use for

169

a while and the developers are confident that the design of the interface

170

is sound and worthy of long-term support, the interface is marked

171

as stable.</p>

172

173

<p>Deprecated interfaces have been superceded by better methods of

174

accomplishing the same thing and should be avoided in new applications.

175

Deprecated interfaces continue to be supported for the sake of

176

backwards compatibility. At some point in the future, it is possible

177

that deprecated interfaces may be removed.</p>

178

179

<p>Key points:</p>

180

181

<ul>

182

<li>Experimental interfaces are subject to change and/or removal

183

at any time.</li>

184

185

<li>Deprecated interfaces should not be used in new code and might

186

be removed in some future release.</li>

187

</ul>

188

189

<hr>

190

<h2>Objects:</h2>

191

<p>Note: Objects marked with "<a href="capi3ref.html"><small><i>exp</i></small></a>"

192

are <a href="capi3ref.html">experimental</a> and objects marked with

193

"<a href="capi3ref.html"><small><i>(obs)</i></small></a>" are <a href="capi3ref.html">deprecated</a>.</p>

194

195

<td valign="top"><ul><li><a href="#sqlite3">sqlite3</a></li>

196

<li><a href="#sqlite3_backup">sqlite3_backup</a></li>

197

<li><a href="#sqlite3_blob">sqlite3_blob</a></li>

198

<li><a href="#sqlite3_context">sqlite3_context</a></li>

199

<li><a href="#sqlite3_data_directory">sqlite3_data_directory</a></li>

200

<li><a href="#sqlite3_file">sqlite3_file</a></li>

201

<li><a href="#sqlite3_index_info">sqlite3_index_info</a></li>

202

<li><a href="#sqlite3_int64">sqlite3_int64</a></li>

203

<li><a href="#sqlite3_int64">sqlite3_uint64</a></li>

204

</ul></td>

205

<td valign="top"><ul><li><a href="#sqlite3_int64">sqlite_int64</a></li>

206

<li><a href="#sqlite3_int64">sqlite_uint64</a></li>

207

<li><a href="#sqlite3_io_methods">sqlite3_io_methods</a></li>

208

<li><a href="#sqlite3_mem_methods">sqlite3_mem_methods</a></li>

209

<li><a href="#sqlite3_module">sqlite3_module</a></li>

210

<li><a href="#sqlite3_mutex">sqlite3_mutex</a></li>

211

<li><a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a></li>

212

<li><a href="#sqlite3_pcache">sqlite3_pcache</a></li>

213

<li><a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a></li>

214

</ul></td>

215

<td valign="top"><ul><li><a href="#sqlite3_pcache_page">sqlite3_pcache_page</a></li>

216

<li><a href="#sqlite3_stmt">sqlite3_stmt</a></li>

217

<li><a href="#sqlite3_temp_directory">sqlite3_temp_directory</a></li>

218

<li><a href="#sqlite3_value">sqlite3_value</a></li>

219

<li><a href="#sqlite3_vfs">sqlite3_vfs</a></li>

220

<li><a href="#sqlite3_vtab">sqlite3_vtab</a></li>

221

<li><a href="#sqlite3_vtab_cursor">sqlite3_vtab_cursor</a></li>

222

</ul></td>

223

</tr></table>

224

<hr>

225

226

<h2>Constants:</h2>

227

<p>Note: Constants marked with "<a href="capi3ref.html"><small><i>(exp)</i></small></a>"

228

are <a href="capi3ref.html">experimental</a> and constants marked with

229

"<a href="capi3ref.html"><small><i>(obs)</i></small></a>" are <a href="capi3ref.html">deprecated</a></p>

230

231

<td valign="top"><ul><li><a href="#SQLITE_ABORT">SQLITE_ABORT</a></li>

232

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_ABORT_ROLLBACK</a></li>

233

<li><a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_EXISTS</a></li>

234

<li><a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READ</a></li>

235

<li><a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READWRITE</a></li>

236

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_ALTER_TABLE</a></li>

237

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_ANALYZE</a></li>

238

<li><a href="#SQLITE_ANY">SQLITE_ANY</a></li>

239

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_ATTACH</a></li>

240

<li><a href="#SQLITE_ABORT">SQLITE_AUTH</a></li>

241

<li><a href="#SQLITE_BLOB">SQLITE_BLOB</a></li>

242

<li><a href="#SQLITE_ABORT">SQLITE_BUSY</a></li>

243

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_BUSY_RECOVERY</a></li>

244

<li><a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a></li>

245

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_CANTOPEN_ISDIR</a></li>

246

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_CANTOPEN_NOTEMPDIR</a></li>

247

<li><a href="#SQLITE_CHECKPOINT_FULL">SQLITE_CHECKPOINT_FULL</a></li>

248

<li><a href="#SQLITE_CHECKPOINT_FULL">SQLITE_CHECKPOINT_PASSIVE</a></li>

249

<li><a href="#SQLITE_CHECKPOINT_FULL">SQLITE_CHECKPOINT_RESTART</a></li>

250

<li><a href="#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a></li>

251

<li><a href="#sqliteconfiggetmutex">SQLITE_CONFIG_GETMUTEX</a></li>

252

<li><a href="#sqliteconfiggetpcache">SQLITE_CONFIG_GETPCACHE</a></li>

253

<li><a href="#sqliteconfiggetpcache2">SQLITE_CONFIG_GETPCACHE2</a></li>

254

<li><a href="#sqliteconfigheap">SQLITE_CONFIG_HEAP</a></li>

255

<li><a href="#sqliteconfiglog">SQLITE_CONFIG_LOG</a></li>

256

<li><a href="#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a></li>

257

<li><a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a></li>

258

<li><a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a></li>

259

<li><a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a></li>

260

<li><a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a></li>

261

<li><a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a></li>

262

<li><a href="#sqliteconfigpcache">SQLITE_CONFIG_PCACHE</a></li>

263

<li><a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a></li>

264

<li><a href="#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a></li>

265

<li><a href="#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a></li>

266

<li><a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a></li>

267

<li><a href="#sqliteconfiguri">SQLITE_CONFIG_URI</a></li>

268

<li><a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a></li>

269

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_COPY</a></li>

270

<li><a href="#SQLITE_ABORT">SQLITE_CORRUPT</a></li>

271

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_CORRUPT_VTAB</a></li>

272

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_INDEX</a></li>

273

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_TABLE</a></li>

274

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_TEMP_INDEX</a></li>

275

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_TEMP_TABLE</a></li>

276

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_TEMP_TRIGGER</a></li>

277

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_TEMP_VIEW</a></li>

278

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_TRIGGER</a></li>

279

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_VIEW</a></li>

280

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_CREATE_VTABLE</a></li>

281

<li><a href="#SQLITE_DBCONFIG_ENABLE_FKEY">SQLITE_DBCONFIG_ENABLE_FKEY</a></li>

282

<li><a href="#SQLITE_DBCONFIG_ENABLE_FKEY">SQLITE_DBCONFIG_ENABLE_TRIGGER</a></li>

283

<li><a href="#SQLITE_DBCONFIG_ENABLE_FKEY">SQLITE_DBCONFIG_LOOKASIDE</a></li>

284

<li><a href="#sqlitedbstatuscachehit">SQLITE_DBSTATUS_CACHE_HIT</a></li>

285

<li><a href="#sqlitedbstatuscachemiss">SQLITE_DBSTATUS_CACHE_MISS</a></li>

286

<li><a href="#sqlitedbstatuscacheused">SQLITE_DBSTATUS_CACHE_USED</a></li>

287

<li><a href="#sqlitedbstatuscachewrite">SQLITE_DBSTATUS_CACHE_WRITE</a></li>

288

<li><a href="#sqlitedbstatuslookasidehit">SQLITE_DBSTATUS_LOOKASIDE_HIT</a></li>

289

<li><a href="#sqlitedbstatuslookasidemissfull">SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</a></li>

290

<li><a href="#sqlitedbstatuslookasidemisssize">SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</a></li>

291

<li><a href="#sqlitedbstatuslookasideused">SQLITE_DBSTATUS_LOOKASIDE_USED</a></li>

292

<li><a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS_MAX</a></li>

293

<li><a href="#sqlitedbstatusschemaused">SQLITE_DBSTATUS_SCHEMA_USED</a></li>

294

<li><a href="#sqlitedbstatusstmtused">SQLITE_DBSTATUS_STMT_USED</a></li>

295

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a></li>

296

<li><a href="#SQLITE_DENY">SQLITE_DENY</a></li>

297

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DETACH</a></li>

298

<li><a href="#SQLITE_ABORT">SQLITE_DONE</a></li>

299

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_INDEX</a></li>

300

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_TABLE</a></li>

301

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_TEMP_INDEX</a></li>

302

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_TEMP_TABLE</a></li>

303

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_TEMP_TRIGGER</a></li>

304

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_TEMP_VIEW</a></li>

305

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_TRIGGER</a></li>

306

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_VIEW</a></li>

307

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_DROP_VTABLE</a></li>

308

<li><a href="#SQLITE_ABORT">SQLITE_EMPTY</a></li>

309

<li><a href="#SQLITE_ABORT">SQLITE_ERROR</a></li>

310

<li><a href="#SQLITE_FAIL">SQLITE_FAIL</a></li>

311

<li><a href="#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a></li>

312

<li><a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a></li>

313

<li><a href="#SQLITE_FCNTL_CHUNK_SIZE">SQLITE_FCNTL_LOCKSTATE</a></li>

314

<li><a href="#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a></li>

315

<li><a href="#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a></li>

316

<li><a href="#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a></li>

317

<li><a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a></li>

318

<li><a href="#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a></li>

319

<li><a href="#sqlitefcntlsyncomitted">SQLITE_FCNTL_SYNC_OMITTED</a></li>

320

<li><a href="#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a></li>

321

<li><a href="#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a></li>

322

<li><a href="#SQLITE_BLOB">SQLITE_FLOAT</a></li>

323

<li><a href="#SQLITE_ABORT">SQLITE_FORMAT</a></li>

324

<li><a href="#SQLITE_ABORT">SQLITE_FULL</a></li>

325

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_FUNCTION</a></li>

326

<li><a href="#SQLITE_FCNTL_CHUNK_SIZE">SQLITE_GET_LOCKPROXYFILE</a></li>

327

<li><a href="#SQLITE_DENY">SQLITE_IGNORE</a></li>

328

<li><a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_EQ</a></li>

329

<li><a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_GE</a></li>

330

<li><a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_GT</a></li>

331

<li><a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_LE</a></li>

332

<li><a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_LT</a></li>

333

<li><a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_MATCH</a></li>

334

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_INSERT</a></li>

335

<li><a href="#SQLITE_BLOB">SQLITE_INTEGER</a></li>

336

<li><a href="#SQLITE_ABORT">SQLITE_INTERNAL</a></li>

337

<li><a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a></li>

338

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC</a></li>

339

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC16K</a></li>

340

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC1K</a></li>

341

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC2K</a></li>

342

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC32K</a></li>

343

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC4K</a></li>

344

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC512</a></li>

345

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC64K</a></li>

346

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC8K</a></li>

347

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a></li>

348

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SAFE_APPEND</a></li>

349

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SEQUENTIAL</a></li>

350

<li><a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a></li>

351

<li><a href="#SQLITE_ABORT">SQLITE_IOERR</a></li>

352

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_ACCESS</a></li>

353

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a></li>

354

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_CHECKRESERVEDLOCK</a></li>

355

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_CLOSE</a></li>

356

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_DELETE</a></li>

357

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_DIR_CLOSE</a></li>

358

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_DIR_FSYNC</a></li>

359

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_FSTAT</a></li>

360

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_FSYNC</a></li>

361

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_LOCK</a></li>

362

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_NOMEM</a></li>

363

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_RDLOCK</a></li>

364

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_READ</a></li>

365

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_SEEK</a></li>

366

</ul></td>

367

<td valign="top"><ul><li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_SHMLOCK</a></li>

368

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_SHMMAP</a></li>

369

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_SHMOPEN</a></li>

370

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_SHMSIZE</a></li>

371

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_SHORT_READ</a></li>

372

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_TRUNCATE</a></li>

373

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_UNLOCK</a></li>

374

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_WRITE</a></li>

375

<li><a href="#SQLITE_FCNTL_CHUNK_SIZE">SQLITE_LAST_ERRNO</a></li>

376

<li><a href="#sqlitelimitattached">SQLITE_LIMIT_ATTACHED</a></li>

377

<li><a href="#sqlitelimitcolumn">SQLITE_LIMIT_COLUMN</a></li>

378

<li><a href="#sqlitelimitcompoundselect">SQLITE_LIMIT_COMPOUND_SELECT</a></li>

379

<li><a href="#sqlitelimitexprdepth">SQLITE_LIMIT_EXPR_DEPTH</a></li>

380

<li><a href="#sqlitelimitfunctionarg">SQLITE_LIMIT_FUNCTION_ARG</a></li>

381

<li><a href="#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a></li>

382

<li><a href="#sqlitelimitlikepatternlength">SQLITE_LIMIT_LIKE_PATTERN_LENGTH</a></li>

383

<li><a href="#sqlitelimitsqllength">SQLITE_LIMIT_SQL_LENGTH</a></li>

384

<li><a href="#sqlitelimittriggerdepth">SQLITE_LIMIT_TRIGGER_DEPTH</a></li>

385

<li><a href="#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a></li>

386

<li><a href="#sqlitelimitvdbeop">SQLITE_LIMIT_VDBE_OP</a></li>

387

<li><a href="#SQLITE_ABORT">SQLITE_LOCKED</a></li>

388

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_LOCKED_SHAREDCACHE</a></li>

389

<li><a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a></li>

390

<li><a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a></li>

391

<li><a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a></li>

392

<li><a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a></li>

393

<li><a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a></li>

394

<li><a href="#SQLITE_ABORT">SQLITE_MISMATCH</a></li>

395

<li><a href="#SQLITE_ABORT">SQLITE_MISUSE</a></li>

396

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_FAST</a></li>

397

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_RECURSIVE</a></li>

398

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_LRU</a></li>

399

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_LRU2</a></li>

400

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MASTER</a></li>

401

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MEM</a></li>

402

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MEM2</a></li>

403

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_OPEN</a></li>

404

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_PMEM</a></li>

405

<li><a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_PRNG</a></li>

406

<li><a href="#SQLITE_ABORT">SQLITE_NOLFS</a></li>

407

<li><a href="#SQLITE_ABORT">SQLITE_NOMEM</a></li>

408

<li><a href="#SQLITE_ABORT">SQLITE_NOTADB</a></li>

409

<li><a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a></li>

410

<li><a href="#SQLITE_BLOB">SQLITE_NULL</a></li>

411

<li><a href="#SQLITE_ABORT">SQLITE_OK</a></li>

412

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_AUTOPROXY</a></li>

413

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a></li>

414

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a></li>

415

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a></li>

416

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_FULLMUTEX</a></li>

417

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_DB</a></li>

418

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_JOURNAL</a></li>

419

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MASTER_JOURNAL</a></li>

420

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MEMORY</a></li>

421

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOMUTEX</a></li>

422

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_PRIVATECACHE</a></li>

423

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a></li>

424

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a></li>

425

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a></li>

426

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SUBJOURNAL</a></li>

427

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_DB</a></li>

428

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_JOURNAL</a></li>

429

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TRANSIENT_DB</a></li>

430

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a></li>

431

<li><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_WAL</a></li>

432

<li><a href="#SQLITE_ABORT">SQLITE_PERM</a></li>

433

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_PRAGMA</a></li>

434

<li><a href="#SQLITE_ABORT">SQLITE_PROTOCOL</a></li>

435

<li><a href="#SQLITE_ABORT">SQLITE_RANGE</a></li>

436

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_READ</a></li>

437

<li><a href="#SQLITE_ABORT">SQLITE_READONLY</a></li>

438

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_READONLY_CANTLOCK</a></li>

439

<li><a href="#SQLITE_ABORT_ROLLBACK">SQLITE_READONLY_RECOVERY</a></li>

440

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_REINDEX</a></li>

441

<li><a href="#SQLITE_FAIL">SQLITE_REPLACE</a></li>

442

<li><a href="#SQLITE_FAIL">SQLITE_ROLLBACK</a></li>

443

<li><a href="#SQLITE_ABORT">SQLITE_ROW</a></li>

444

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_SAVEPOINT</a></li>

445

<li><a href="#SQLITE_ABORT">SQLITE_SCHEMA</a></li>

446

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_SELECT</a></li>

447

<li><a href="#SQLITE_FCNTL_CHUNK_SIZE">SQLITE_SET_LOCKPROXYFILE</a></li>

448

<li><a href="#SQLITE_SHM_EXCLUSIVE">SQLITE_SHM_EXCLUSIVE</a></li>

449

<li><a href="#SQLITE_SHM_EXCLUSIVE">SQLITE_SHM_LOCK</a></li>

450

<li><a href="#SQLITE_SHM_NLOCK">SQLITE_SHM_NLOCK</a></li>

451

<li><a href="#SQLITE_SHM_EXCLUSIVE">SQLITE_SHM_SHARED</a></li>

452

<li><a href="#SQLITE_SHM_EXCLUSIVE">SQLITE_SHM_UNLOCK</a></li>

453

<li><a href="#SQLITE_SOURCE_ID">SQLITE_SOURCE_ID</a></li>

454

<li><a href="#SQLITE_STATIC">SQLITE_STATIC</a></li>

455

<li><a href="#sqlitestatusmalloccount">SQLITE_STATUS_MALLOC_COUNT</a></li>

456

<li><a href="#sqlitestatusmallocsize">SQLITE_STATUS_MALLOC_SIZE</a></li>

457

<li><a href="#sqlitestatusmemoryused">SQLITE_STATUS_MEMORY_USED</a></li>

458

<li><a href="#sqlitestatuspagecacheoverflow">SQLITE_STATUS_PAGECACHE_OVERFLOW</a></li>

459

<li><a href="#sqlitestatuspagecachesize">SQLITE_STATUS_PAGECACHE_SIZE</a></li>

460

<li><a href="#sqlitestatuspagecacheused">SQLITE_STATUS_PAGECACHE_USED</a></li>

461

<li><a href="#sqlitestatusparserstack">SQLITE_STATUS_PARSER_STACK</a></li>

462

<li><a href="#sqlitestatusscratchoverflow">SQLITE_STATUS_SCRATCH_OVERFLOW</a></li>

463

<li><a href="#sqlitestatusscratchsize">SQLITE_STATUS_SCRATCH_SIZE</a></li>

464

<li><a href="#sqlitestatusscratchused">SQLITE_STATUS_SCRATCH_USED</a></li>

465

<li><a href="#sqlitestmtstatusautoindex">SQLITE_STMTSTATUS_AUTOINDEX</a></li>

466

<li><a href="#sqlitestmtstatusfullscanstep">SQLITE_STMTSTATUS_FULLSCAN_STEP</a></li>

467

<li><a href="#sqlitestmtstatussort">SQLITE_STMTSTATUS_SORT</a></li>

468

<li><a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_DATAONLY</a></li>

469

<li><a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_FULL</a></li>

470

<li><a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_NORMAL</a></li>

471

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_ALWAYS</a></li>

472

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_ASSERT</a></li>

473

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS</a></li>

474

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_BITVEC_TEST</a></li>

475

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_EXPLAIN_STMT</a></li>

476

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_FAULT_INSTALL</a></li>

477

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_FIRST</a></li>

478

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_ISKEYWORD</a></li>

479

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_LAST</a></li>

480

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_LOCALTIME_FAULT</a></li>

481

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_OPTIMIZATIONS</a></li>

482

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_PENDING_BYTE</a></li>

483

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_PRNG_RESET</a></li>

484

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_PRNG_RESTORE</a></li>

485

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_PRNG_SAVE</a></li>

486

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_RESERVE</a></li>

487

<li><a href="#SQLITE_TESTCTRL_ALWAYS">SQLITE_TESTCTRL_SCRATCHMALLOC</a></li>

488

<li><a href="#SQLITE_BLOB">SQLITE_TEXT</a></li>

489

<li><a href="#SQLITE_ABORT">SQLITE_TOOBIG</a></li>

490

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_TRANSACTION</a></li>

491

<li><a href="#SQLITE_STATIC">SQLITE_TRANSIENT</a></li>

492

<li><a href="#SQLITE_ALTER_TABLE">SQLITE_UPDATE</a></li>

493

<li><a href="#SQLITE_ANY">SQLITE_UTF16</a></li>

494

<li><a href="#SQLITE_ANY">SQLITE_UTF16BE</a></li>

495

<li><a href="#SQLITE_ANY">SQLITE_UTF16LE</a></li>

496

<li><a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a></li>

497

<li><a href="#SQLITE_ANY">SQLITE_UTF8</a></li>

498

<li><a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a></li>

499

<li><a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a></li>

500

<li><a href="#SQLITE_VTAB_CONSTRAINT_SUPPORT">SQLITE_VTAB_CONSTRAINT_SUPPORT</a></li>

501

</ul></td>

502

</tr></table>

503

<hr>

504

505

<h2>Functions:</h2>

506

<p>Note: Functions marked with "<a href="capi3ref.html"><small><i>(exp)</i></small></a>"

507

are <a href="capi3ref.html">experimental</a> and functions marked with

508

<a href="capi3ref.html"><small><i>(obs)</i></small></a> are <a href="capi3ref.html">deprecated</a>.</p>

509

510

<td valign="top"><ul><li><a href="#sqlite3_aggregate_context">sqlite3_aggregate_context</a></li>

511

<li><a href="#sqlite3_aggregate_count">sqlite3_aggregate_count</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

512

<li><a href="#sqlite3_auto_extension">sqlite3_auto_extension</a></li>

513

<li><a href="#sqlite3backupfinish">sqlite3_backup_finish</a></li>

514

<li><a href="#sqlite3backupfinish">sqlite3_backup_init</a></li>

515

<li><a href="#sqlite3backupfinish">sqlite3_backup_pagecount</a></li>

516

<li><a href="#sqlite3backupfinish">sqlite3_backup_remaining</a></li>

517

<li><a href="#sqlite3backupfinish">sqlite3_backup_step</a></li>

518

<li><a href="#sqlite3_bind_blob">sqlite3_bind_blob</a></li>

519

<li><a href="#sqlite3_bind_blob">sqlite3_bind_double</a></li>

520

<li><a href="#sqlite3_bind_blob">sqlite3_bind_int</a></li>

521

<li><a href="#sqlite3_bind_blob">sqlite3_bind_int64</a></li>

522

<li><a href="#sqlite3_bind_blob">sqlite3_bind_null</a></li>

523

<li><a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count</a></li>

524

<li><a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index</a></li>

525

<li><a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name</a></li>

526

<li><a href="#sqlite3_bind_blob">sqlite3_bind_text</a></li>

527

<li><a href="#sqlite3_bind_blob">sqlite3_bind_text16</a></li>

528

<li><a href="#sqlite3_bind_blob">sqlite3_bind_value</a></li>

529

<li><a href="#sqlite3_bind_blob">sqlite3_bind_zeroblob</a></li>

530

<li><a href="#sqlite3_blob_bytes">sqlite3_blob_bytes</a></li>

531

<li><a href="#sqlite3_blob_close">sqlite3_blob_close</a></li>

532

<li><a href="#sqlite3_blob_open">sqlite3_blob_open</a></li>

533

<li><a href="#sqlite3_blob_read">sqlite3_blob_read</a></li>

534

<li><a href="#sqlite3_blob_reopen">sqlite3_blob_reopen</a></li>

535

<li><a href="#sqlite3_blob_write">sqlite3_blob_write</a></li>

536

<li><a href="#sqlite3_busy_handler">sqlite3_busy_handler</a></li>

537

<li><a href="#sqlite3_busy_timeout">sqlite3_busy_timeout</a></li>

538

<li><a href="#sqlite3_changes">sqlite3_changes</a></li>

539

<li><a href="#sqlite3_clear_bindings">sqlite3_clear_bindings</a></li>

540

<li><a href="#sqlite3_close">sqlite3_close</a></li>

541

<li><a href="#sqlite3_collation_needed">sqlite3_collation_needed</a></li>

542

<li><a href="#sqlite3_collation_needed">sqlite3_collation_needed16</a></li>

543

<li><a href="#sqlite3_column_blob">sqlite3_column_blob</a></li>

544

<li><a href="#sqlite3_column_blob">sqlite3_column_bytes</a></li>

545

<li><a href="#sqlite3_column_blob">sqlite3_column_bytes16</a></li>

546

<li><a href="#sqlite3_column_count">sqlite3_column_count</a></li>

547

<li><a href="#sqlite3_column_database_name">sqlite3_column_database_name</a></li>

548

<li><a href="#sqlite3_column_database_name">sqlite3_column_database_name16</a></li>

549

<li><a href="#sqlite3_column_decltype">sqlite3_column_decltype</a></li>

550

<li><a href="#sqlite3_column_decltype">sqlite3_column_decltype16</a></li>

551

<li><a href="#sqlite3_column_blob">sqlite3_column_double</a></li>

552

<li><a href="#sqlite3_column_blob">sqlite3_column_int</a></li>

553

<li><a href="#sqlite3_column_blob">sqlite3_column_int64</a></li>

554

<li><a href="#sqlite3_column_name">sqlite3_column_name</a></li>

555

<li><a href="#sqlite3_column_name">sqlite3_column_name16</a></li>

556

<li><a href="#sqlite3_column_database_name">sqlite3_column_origin_name</a></li>

557

<li><a href="#sqlite3_column_database_name">sqlite3_column_origin_name16</a></li>

558

<li><a href="#sqlite3_column_database_name">sqlite3_column_table_name</a></li>

559

<li><a href="#sqlite3_column_database_name">sqlite3_column_table_name16</a></li>

560

<li><a href="#sqlite3_column_blob">sqlite3_column_text</a></li>

561

<li><a href="#sqlite3_column_blob">sqlite3_column_text16</a></li>

562

<li><a href="#sqlite3_column_blob">sqlite3_column_type</a></li>

563

<li><a href="#sqlite3_column_blob">sqlite3_column_value</a></li>

564

<li><a href="#sqlite3_commit_hook">sqlite3_commit_hook</a></li>

565

<li><a href="#sqlite3_compileoption_get">sqlite3_compileoption_get</a></li>

566

<li><a href="#sqlite3_compileoption_get">sqlite3_compileoption_used</a></li>

567

<li><a href="#sqlite3_complete">sqlite3_complete</a></li>

568

<li><a href="#sqlite3_complete">sqlite3_complete16</a></li>

569

<li><a href="#sqlite3_config">sqlite3_config</a></li>

570

<li><a href="#sqlite3_context_db_handle">sqlite3_context_db_handle</a></li>

571

<li><a href="#sqlite3_create_collation">sqlite3_create_collation</a></li>

572

<li><a href="#sqlite3_create_collation">sqlite3_create_collation16</a></li>

573

<li><a href="#sqlite3_create_collation">sqlite3_create_collation_v2</a></li>

574

<li><a href="#sqlite3_create_function">sqlite3_create_function</a></li>

575

<li><a href="#sqlite3_create_function">sqlite3_create_function16</a></li>

576

<li><a href="#sqlite3_create_function">sqlite3_create_function_v2</a></li>

577

<li><a href="#sqlite3_create_module">sqlite3_create_module</a></li>

578

</ul></td>

579

<td valign="top"><ul><li><a href="#sqlite3_create_module">sqlite3_create_module_v2</a></li>

580

<li><a href="#sqlite3_data_count">sqlite3_data_count</a></li>

581

<li><a href="#sqlite3_db_config">sqlite3_db_config</a></li>

582

<li><a href="#sqlite3_db_filename">sqlite3_db_filename</a></li>

583

<li><a href="#sqlite3_db_handle">sqlite3_db_handle</a></li>

584

<li><a href="#sqlite3_db_mutex">sqlite3_db_mutex</a></li>

585

<li><a href="#sqlite3_db_readonly">sqlite3_db_readonly</a></li>

586

<li><a href="#sqlite3_db_release_memory">sqlite3_db_release_memory</a></li>

587

<li><a href="#sqlite3_db_status">sqlite3_db_status</a></li>

588

<li><a href="#sqlite3_declare_vtab">sqlite3_declare_vtab</a></li>

589

<li><a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension</a></li>

590

<li><a href="#sqlite3_enable_shared_cache">sqlite3_enable_shared_cache</a></li>

591

<li><a href="#sqlite3_errcode">sqlite3_errcode</a></li>

592

<li><a href="#sqlite3_errcode">sqlite3_errmsg</a></li>

593

<li><a href="#sqlite3_errcode">sqlite3_errmsg16</a></li>

594

<li><a href="#sqlite3_exec">sqlite3_exec</a></li>

595

<li><a href="#sqlite3_aggregate_count">sqlite3_expired</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

596

<li><a href="#sqlite3_errcode">sqlite3_extended_errcode</a></li>

597

<li><a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes</a></li>

598

<li><a href="#sqlite3_file_control">sqlite3_file_control</a></li>

599

<li><a href="#sqlite3_finalize">sqlite3_finalize</a></li>

600

<li><a href="#sqlite3_free">sqlite3_free</a></li>

601

<li><a href="#sqlite3_free_table">sqlite3_free_table</a></li>

602

<li><a href="#sqlite3_get_autocommit">sqlite3_get_autocommit</a></li>

603

<li><a href="#sqlite3_get_auxdata">sqlite3_get_auxdata</a></li>

604

<li><a href="#sqlite3_free_table">sqlite3_get_table</a></li>

605

<li><a href="#sqlite3_aggregate_count">sqlite3_global_recover</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

606

<li><a href="#sqlite3_initialize">sqlite3_initialize</a></li>

607

<li><a href="#sqlite3_interrupt">sqlite3_interrupt</a></li>

608

<li><a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid</a></li>

609

<li><a href="#sqlite3_libversion">sqlite3_libversion</a></li>

610

<li><a href="#sqlite3_libversion">sqlite3_libversion_number</a></li>

611

<li><a href="#sqlite3_limit">sqlite3_limit</a></li>

612

<li><a href="#sqlite3_load_extension">sqlite3_load_extension</a></li>

613

<li><a href="#sqlite3_log">sqlite3_log</a></li>

614

<li><a href="#sqlite3_free">sqlite3_malloc</a></li>

615

<li><a href="#sqlite3_aggregate_count">sqlite3_memory_alarm</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

616

<li><a href="#sqlite3_memory_highwater">sqlite3_memory_highwater</a></li>

617

<li><a href="#sqlite3_memory_highwater">sqlite3_memory_used</a></li>

618

<li><a href="#sqlite3_mprintf">sqlite3_mprintf</a></li>

619

<li><a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc</a></li>

620

<li><a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter</a></li>

621

<li><a href="#sqlite3_mutex_alloc">sqlite3_mutex_free</a></li>

622

<li><a href="#sqlite3_mutex_held">sqlite3_mutex_held</a></li>

623

<li><a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave</a></li>

624

<li><a href="#sqlite3_mutex_held">sqlite3_mutex_notheld</a></li>

625

<li><a href="#sqlite3_mutex_alloc">sqlite3_mutex_try</a></li>

626

<li><a href="#sqlite3_next_stmt">sqlite3_next_stmt</a></li>

627

<li><a href="#sqlite3_open">sqlite3_open</a></li>

628

<li><a href="#sqlite3_open">sqlite3_open16</a></li>

629

<li><a href="#sqlite3_open">sqlite3_open_v2</a></li>

630

<li><a href="#sqlite3_initialize">sqlite3_os_end</a></li>

631

<li><a href="#sqlite3_initialize">sqlite3_os_init</a></li>

632

<li><a href="#sqlite3_overload_function">sqlite3_overload_function</a></li>

633

<li><a href="#sqlite3_prepare">sqlite3_prepare</a></li>

634

<li><a href="#sqlite3_prepare">sqlite3_prepare16</a></li>

635

<li><a href="#sqlite3_prepare">sqlite3_prepare16_v2</a></li>

636

<li><a href="#sqlite3_prepare">sqlite3_prepare_v2</a></li>

637

<li><a href="#sqlite3_profile">sqlite3_profile</a></li>

638

<li><a href="#sqlite3_progress_handler">sqlite3_progress_handler</a></li>

639

<li><a href="#sqlite3_randomness">sqlite3_randomness</a></li>

640

<li><a href="#sqlite3_free">sqlite3_realloc</a></li>

641

<li><a href="#sqlite3_release_memory">sqlite3_release_memory</a></li>

642

<li><a href="#sqlite3_reset">sqlite3_reset</a></li>

643

<li><a href="#sqlite3_reset_auto_extension">sqlite3_reset_auto_extension</a></li>

644

<li><a href="#sqlite3_result_blob">sqlite3_result_blob</a></li>

645

<li><a href="#sqlite3_result_blob">sqlite3_result_double</a></li>

646

<li><a href="#sqlite3_result_blob">sqlite3_result_error</a></li>

647

</ul></td>

648

<td valign="top"><ul><li><a href="#sqlite3_result_blob">sqlite3_result_error16</a></li>

649

<li><a href="#sqlite3_result_blob">sqlite3_result_error_code</a></li>

650

<li><a href="#sqlite3_result_blob">sqlite3_result_error_nomem</a></li>

651

<li><a href="#sqlite3_result_blob">sqlite3_result_error_toobig</a></li>

652

<li><a href="#sqlite3_result_blob">sqlite3_result_int</a></li>

653

<li><a href="#sqlite3_result_blob">sqlite3_result_int64</a></li>

654

<li><a href="#sqlite3_result_blob">sqlite3_result_null</a></li>

655

<li><a href="#sqlite3_result_blob">sqlite3_result_text</a></li>

656

<li><a href="#sqlite3_result_blob">sqlite3_result_text16</a></li>

657

<li><a href="#sqlite3_result_blob">sqlite3_result_text16be</a></li>

658

<li><a href="#sqlite3_result_blob">sqlite3_result_text16le</a></li>

659

<li><a href="#sqlite3_result_blob">sqlite3_result_value</a></li>

660

<li><a href="#sqlite3_result_blob">sqlite3_result_zeroblob</a></li>

661

<li><a href="#sqlite3_commit_hook">sqlite3_rollback_hook</a></li>

662

<li><a href="#sqlite3_set_authorizer">sqlite3_set_authorizer</a></li>

663

<li><a href="#sqlite3_get_auxdata">sqlite3_set_auxdata</a></li>

664

<li><a href="#sqlite3_initialize">sqlite3_shutdown</a></li>

665

<li><a href="#sqlite3_sleep">sqlite3_sleep</a></li>

666

<li><a href="#sqlite3_mprintf">sqlite3_snprintf</a></li>

667

<li><a href="#sqlite3_soft_heap_limit">sqlite3_soft_heap_limit</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

668

<li><a href="#sqlite3_soft_heap_limit64">sqlite3_soft_heap_limit64</a></li>

669

<li><a href="#sqlite3_libversion">sqlite3_sourceid</a></li>

670

<li><a href="#sqlite3_sql">sqlite3_sql</a></li>

671

<li><a href="#sqlite3_status">sqlite3_status</a></li>

672

<li><a href="#sqlite3_step">sqlite3_step</a></li>

673

<li><a href="#sqlite3_stmt_busy">sqlite3_stmt_busy</a></li>

674

<li><a href="#sqlite3_stmt_readonly">sqlite3_stmt_readonly</a></li>

675

<li><a href="#sqlite3_stmt_status">sqlite3_stmt_status</a></li>

676

<li><a href="#sqlite3_stricmp">sqlite3_stricmp</a></li>

677

<li><a href="#sqlite3_stricmp">sqlite3_strnicmp</a></li>

678

<li><a href="#sqlite3_table_column_metadata">sqlite3_table_column_metadata</a></li>

679

<li><a href="#sqlite3_test_control">sqlite3_test_control</a></li>

680

<li><a href="#sqlite3_aggregate_count">sqlite3_thread_cleanup</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

681

<li><a href="#sqlite3_threadsafe">sqlite3_threadsafe</a></li>

682

<li><a href="#sqlite3_total_changes">sqlite3_total_changes</a></li>

683

<li><a href="#sqlite3_profile">sqlite3_trace</a></li>

684

<li><a href="#sqlite3_aggregate_count">sqlite3_transfer_bindings</a>  <a href="capi3ref.html"><small><i>(obs)</i></small></a></li>

685

<li><a href="#sqlite3_unlock_notify">sqlite3_unlock_notify</a></li>

686

<li><a href="#sqlite3_update_hook">sqlite3_update_hook</a></li>

687

<li><a href="#sqlite3_uri_boolean">sqlite3_uri_boolean</a></li>

688

<li><a href="#sqlite3_uri_boolean">sqlite3_uri_int64</a></li>

689

<li><a href="#sqlite3_uri_boolean">sqlite3_uri_parameter</a></li>

690

<li><a href="#sqlite3_user_data">sqlite3_user_data</a></li>

691

<li><a href="#sqlite3_value_blob">sqlite3_value_blob</a></li>

692

<li><a href="#sqlite3_value_blob">sqlite3_value_bytes</a></li>

693

<li><a href="#sqlite3_value_blob">sqlite3_value_bytes16</a></li>

694

<li><a href="#sqlite3_value_blob">sqlite3_value_double</a></li>

695

<li><a href="#sqlite3_value_blob">sqlite3_value_int</a></li>

696

<li><a href="#sqlite3_value_blob">sqlite3_value_int64</a></li>

697

<li><a href="#sqlite3_value_blob">sqlite3_value_numeric_type</a></li>

698

<li><a href="#sqlite3_value_blob">sqlite3_value_text</a></li>

699

<li><a href="#sqlite3_value_blob">sqlite3_value_text16</a></li>

700

<li><a href="#sqlite3_value_blob">sqlite3_value_text16be</a></li>

701

<li><a href="#sqlite3_value_blob">sqlite3_value_text16le</a></li>

702

<li><a href="#sqlite3_value_blob">sqlite3_value_type</a></li>

703

<li><a href="#sqlite3_libversion">sqlite3_version,</a></li>

704

<li><a href="#sqlite3_vfs_find">sqlite3_vfs_find</a></li>

705

<li><a href="#sqlite3_vfs_find">sqlite3_vfs_register</a></li>

706

<li><a href="#sqlite3_vfs_find">sqlite3_vfs_unregister</a></li>

707

<li><a href="#sqlite3_mprintf">sqlite3_vmprintf</a></li>

708

<li><a href="#sqlite3_mprintf">sqlite3_vsnprintf</a></li>

709

<li><a href="#sqlite3_vtab_config">sqlite3_vtab_config</a></li>

710

<li><a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict</a></li>

711

<li><a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint</a></li>

712

<li><a href="#sqlite3_wal_checkpoint">sqlite3_wal_checkpoint</a></li>

713

<li><a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2</a></li>

714

<li><a href="#sqlite3_wal_hook">sqlite3_wal_hook</a></li>

715

</ul></td>

716

</tr></table>

717

<hr>

718

719

<h2>Maximum xShmLock index</h2><blockquote><pre>#define SQLITE_SHM_NLOCK 8

720

</pre></blockquote><p>

721

The xShmLock method on <a href="#sqlite3_io_methods">sqlite3_io_methods</a> may use values

722

between 0 and this upper bound as its "offset" argument.

723

The SQLite core will never attempt to acquire or release a

724

lock outside of this range

725

</p><hr><a name="SQLITE_VTAB_CONSTRAINT_SUPPORT"></a>

726

<h2>Virtual Table Configuration Options</h2><blockquote><pre>#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1

727

</pre></blockquote><p>

728

These macros define the various options to the

729

<a href="#sqlite3_vtab_config">sqlite3_vtab_config()</a> interface that <a href="vtab.html">virtual table</a> implementations

730

can use to customize and optimize their behavior.</p>

731

732

<p><dl>

733

<dt>SQLITE_VTAB_CONSTRAINT_SUPPORT

734

<dd>Calls of the form

735

<a href="#sqlite3_vtab_config">sqlite3_vtab_config</a>(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,

736

where X is an integer. If X is zero, then the <a href="vtab.html">virtual table</a> whose

737

<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

738

support constraints. In this configuration (which is the default) if

739

a call to the <a href="vtab.html#xupdate">xUpdate</a> method returns <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, then the entire

740

statement is rolled back as if <a href="lang_conflict.html">OR ABORT</a> had been

741

specified as part of the users SQL statement, regardless of the actual

742

ON CONFLICT mode specified.</p>

743

744

<p>If X is non-zero, then the virtual table implementation guarantees

745

that if <a href="vtab.html#xupdate">xUpdate</a> returns <a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, it will do so before

746

any modifications to internal or persistent data structures have been made.

747

If the <a href="lang_conflict.html">ON CONFLICT</a> mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite

748

is able to roll back a statement or database transaction, and abandon

749

or continue processing the current SQL statement as appropriate.

750

If the ON CONFLICT mode is REPLACE and the <a href="vtab.html#xupdate">xUpdate</a> method returns

751

<a href="#SQLITE_ABORT">SQLITE_CONSTRAINT</a>, SQLite handles this as if the ON CONFLICT mode

752

had been ABORT.</p>

753

754

<p>Virtual table implementations that are required to handle OR REPLACE

755

must do so within the <a href="vtab.html#xupdate">xUpdate</a> method. If a call to the

756

<a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> function indicates that the current ON

757

CONFLICT policy is REPLACE, the virtual table implementation should

758

silently replace the appropriate rows within the xUpdate callback and

759

return SQLITE_OK. Or, if this is not possible, it may return

760

SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT

761

constraint handling.

762

</dl>

763

</p><hr><a name="sqlite3_backup"></a>

764

<h2>Online Backup Object</h2><blockquote><pre>typedef struct sqlite3_backup sqlite3_backup;

765

</pre></blockquote><p>

766

The sqlite3_backup object records state information about an ongoing

767

online backup operation. The sqlite3_backup object is created by

768

a call to <a href="#sqlite3backupinit">sqlite3_backup_init()</a> and is destroyed by a call to

769

<a href="#sqlite3backupfinish">sqlite3_backup_finish()</a>.</p>

770

771

<p>See Also: <a href="backup.html">Using the SQLite Online Backup API</a>

772

</p><hr><a name="sqlite3_context"></a>

773

<h2>SQL Function Context Object</h2><blockquote><pre>typedef struct sqlite3_context sqlite3_context;

774

</pre></blockquote><p>

775

The context in which an SQL function executes is stored in an

776

sqlite3_context object. A pointer to an sqlite3_context object

777

is always first parameter to <a href="#sqlite3_create_function">application-defined SQL functions</a>.

778

The application-defined SQL function implementation will pass this

779

pointer through into calls to <a href="#sqlite3_result_blob">sqlite3_result()</a>,

780

<a href="#sqlite3_aggregate_context">sqlite3_aggregate_context()</a>, <a href="#sqlite3_user_data">sqlite3_user_data()</a>,

781

<a href="#sqlite3_context_db_handle">sqlite3_context_db_handle()</a>, <a href="#sqlite3_get_auxdata">sqlite3_get_auxdata()</a>,

782

and/or <a href="#sqlite3_get_auxdata">sqlite3_set_auxdata()</a>.

783

</p><hr><a name="sqlite3_data_directory"></a>

784

<h2>Name Of The Folder Holding Database Files</h2><blockquote><pre>SQLITE_EXTERN char *sqlite3_data_directory;

785

</pre></blockquote><p>

786

If this global variable is made to point to a string which is

787

the name of a folder (a.k.a. directory), then all database files

788

specified with a relative pathname and created or accessed by

789

SQLite when using a built-in windows <a href="#sqlite3_vfs">VFS</a> will be assumed

790

to be relative to that directory. If this variable is a NULL

791

pointer, then SQLite assumes that all database files specified

792

with a relative pathname are relative to the current directory

793

for the process. Only the windows VFS makes use of this global

794

variable; it is ignored by the unix VFS.</p>

795

796

<p>Changing the value of this variable while a database connection is

797

open can result in a corrupt database.</p>

798

799

<p>It is not safe to read or modify this variable in more than one

800

thread at a time. It is not safe to read or modify this variable

801

if a <a href="#sqlite3">database connection</a> is being used at the same time in a separate

802

thread.

803

It is intended that this variable be set once

804

as part of process initialization and before any SQLite interface

805

routines have been called and that this variable remain unchanged

806

thereafter.</p>

807

808

<p>The <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> may modify this variable and cause

809

it to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>. Furthermore,

810

the <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> always assumes that any string

811

that this variable points to is held in memory obtained from

812

<a href="#sqlite3_free">sqlite3_malloc</a> and the pragma may attempt to free that memory

813

using <a href="#sqlite3_free">sqlite3_free</a>.

814

Hence, if this variable is modified directly, either it should be

815

made NULL or made to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>

816

or else the use of the <a href="pragma.html#pragma_data_store_directory">data_store_directory pragma</a> should be avoided.

817

</p><hr><a name="sqlite3_file"></a>

818

<h2>OS Interface Open File Handle</h2><blockquote><pre>typedef struct sqlite3_file sqlite3_file;

819

struct sqlite3_file {

820

const struct sqlite3_io_methods *pMethods; /* Methods for an open file */

821

};

822

</pre></blockquote><p>

823

An <a href="#sqlite3_file">sqlite3_file</a> object represents an open file in the

824

<a href="#sqlite3_vfs">OS interface layer</a>. Individual OS interface

825

implementations will

826

want to subclass this object by appending additional fields

827

for their own use. The pMethods entry is a pointer to an

828

<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object that defines methods for performing

829

I/O operations on the open file.

830

</p><hr><a name="sqlite3_index_info"></a>

831

<h2>Virtual Table Indexing Information</h2><blockquote><pre>struct sqlite3_index_info {

832

/* Inputs */

833

int nConstraint; /* Number of entries in aConstraint */

834

struct sqlite3_index_constraint {

835

int iColumn; /* Column on left-hand side of constraint */

836

unsigned char op; /* Constraint operator */

837

unsigned char usable; /* True if this constraint is usable */

838

int iTermOffset; /* Used internally - xBestIndex should ignore */

839

} *aConstraint; /* Table of WHERE clause constraints */

840

int nOrderBy; /* Number of terms in the ORDER BY clause */

841

struct sqlite3_index_orderby {

842

int iColumn; /* Column number */

843

unsigned char desc; /* True for DESC. False for ASC. */

844

} *aOrderBy; /* The ORDER BY clause */

845

/* Outputs */

846

struct sqlite3_index_constraint_usage {

847

int argvIndex; /* if >0, constraint is part of argv to xFilter */

848

unsigned char omit; /* Do not code a test for this constraint */

849

} *aConstraintUsage;

850

int idxNum; /* Number used to identify the index */

851

char *idxStr; /* String, possibly obtained from sqlite3_malloc */

852

int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */

853

int orderByConsumed; /* True if output is already ordered */

854

double estimatedCost; /* Estimated cost of using this index */

855

};

856

</pre></blockquote><p>

857

The sqlite3_index_info structure and its substructures is used as part

858

of the <a href="vtab.html">virtual table</a> interface to

859

pass information into and receive the reply from the <a href="vtab.html#xbestindex">xBestIndex</a>

860

method of a <a href="#sqlite3_module">virtual table module</a>. The fields under **Inputs** are the

861

inputs to xBestIndex and are read-only. xBestIndex inserts its

862

results into the **Outputs** fields.</p>

863

864

<p>The aConstraint[] array records WHERE clause constraints of the form:</p>

865

866

<p><blockquote>column OP expr</blockquote></p>

867

868

<p>where OP is =, <, <=, >, or >=. The particular operator is

869

stored in aConstraint[].op using one of the

870

<a href="#SQLITE_INDEX_CONSTRAINT_EQ">SQLITE_INDEX_CONSTRAINT_ values</a>.

871

The index of the column is stored in

872

aConstraint[].iColumn. aConstraint[].usable is TRUE if the

873

expr on the right-hand side can be evaluated (and thus the constraint

874

is usable) and false if it cannot.</p>

875

876

<p>The optimizer automatically inverts terms of the form "expr OP column"

877

and makes other simplifications to the WHERE clause in an attempt to

878

get as many WHERE clause terms into the form shown above as possible.

879

The aConstraint[] array only reports WHERE clause terms that are

880

relevant to the particular virtual table being queried.</p>

881

882

<p>Information about the ORDER BY clause is stored in aOrderBy[].

883

Each term of aOrderBy records a column of the ORDER BY clause.</p>

884

885

<p>The <a href="vtab.html#xbestindex">xBestIndex</a> method must fill aConstraintUsage[] with information

886

about what parameters to pass to xFilter. If argvIndex>0 then

887

the right-hand side of the corresponding aConstraint[] is evaluated

888

and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit

889

is true, then the constraint is assumed to be fully handled by the

890

virtual table and is not checked again by SQLite.</p>

891

892

<p>The idxNum and idxPtr values are recorded and passed into the

893

<a href="vtab.html#xfilter">xFilter</a> method.

894

<a href="#sqlite3_free">sqlite3_free()</a> is used to free idxPtr if and only if

895

needToFreeIdxPtr is true.</p>

896

897

<p>The orderByConsumed means that output from <a href="vtab.html#xfilter">xFilter</a>/<a href="vtab.html#xnext">xNext</a> will occur in

898

the correct order to satisfy the ORDER BY clause so that no separate

899

sorting step is required.</p>

900

901

<p>The estimatedCost value is an estimate of the cost of doing the

902

particular lookup. A full scan of a table with N entries should have

903

a cost of N. A binary search of a table of N entries should have a

904

cost of approximately log(N).

905

</p><hr><a name="sqlite3_io_methods"></a>

906

<h2>OS Interface File Virtual Methods Object</h2><blockquote><pre>typedef struct sqlite3_io_methods sqlite3_io_methods;

907

struct sqlite3_io_methods {

908

int iVersion;

909

int (*xClose)(sqlite3_file*);

910

int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);

911

int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);

912

int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);

913

int (*xSync)(sqlite3_file*, int flags);

914

int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);

915

int (*xLock)(sqlite3_file*, int);

916

int (*xUnlock)(sqlite3_file*, int);

917

int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);

918

int (*xFileControl)(sqlite3_file*, int op, void *pArg);

919

int (*xSectorSize)(sqlite3_file*);

920

int (*xDeviceCharacteristics)(sqlite3_file*);

921

/* Methods above are valid for version 1 */

922

int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);

923

int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);

924

void (*xShmBarrier)(sqlite3_file*);

925

int (*xShmUnmap)(sqlite3_file*, int deleteFlag);

926

/* Methods above are valid for version 2 */

927

/* Additional methods may be added in future releases */

928

};

929

</pre></blockquote><p>

930

Every file opened by the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method populates an

931

<a href="#sqlite3_file">sqlite3_file</a> object (or, more commonly, a subclass of the

932

<a href="#sqlite3_file">sqlite3_file</a> object) with a pointer to an instance of this object.

933

This object defines the methods used to perform various operations

934

against the open file represented by the <a href="#sqlite3_file">sqlite3_file</a> object.</p>

935

936

<p>If the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method sets the sqlite3_file.pMethods element

937

to a non-NULL pointer, then the sqlite3_io_methods.xClose method

938

may be invoked even if the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> reported that it failed. The

939

only way to prevent a call to xClose following a failed <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a>

940

is for the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> to set the sqlite3_file.pMethods element

941

to NULL.</p>

942

943

<p>The flags argument to xSync may be one of <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_NORMAL</a> or

944

<a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_FULL</a>. The first choice is the normal fsync().

945

The second choice is a Mac OS X style fullsync. The <a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_DATAONLY</a>

946

flag may be ORed in to indicate that only the data of the file

947

and not its inode needs to be synced.</p>

948

949

<p>The integer values to xLock() and xUnlock() are one of

950

<ul>

951

<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>,

952

<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,

953

<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>,

954

<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or

955

<li> <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>.

956

</ul>

957

xLock() increases the lock. xUnlock() decreases the lock.

958

The xCheckReservedLock() method checks whether any database connection,

959

either in this process or in some other process, is holding a RESERVED,

960

PENDING, or EXCLUSIVE lock on the file. It returns true

961

if such a lock exists and false otherwise.</p>

962

963

<p>The xFileControl() method is a generic interface that allows custom

964

VFS implementations to directly control an open file using the

965

<a href="#sqlite3_file_control">sqlite3_file_control()</a> interface. The second "op" argument is an

966

integer opcode. The third argument is a generic pointer intended to

967

point to a structure that may contain arguments or space in which to

968

write return values. Potential uses for xFileControl() might be

969

functions to enable blocking locks with timeouts, to change the

970

locking strategy (for example to use dot-file locks), to inquire

971

about the status of a lock, or to break stale locks. The SQLite

972

core reserves all opcodes less than 100 for its own use.

973

A <a href="#SQLITE_FCNTL_CHUNK_SIZE">list of opcodes</a> less than 100 is available.

974

Applications that define a custom xFileControl method should use opcodes

975

greater than 100 to avoid conflicts. VFS implementations should

976

return <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a> for file control opcodes that they do not

977

recognize.</p>

978

979

<p>The xSectorSize() method returns the sector size of the

980

device that underlies the file. The sector size is the

981

minimum write that can be performed without disturbing

982

other bytes in the file. The xDeviceCharacteristics()

983

method returns a bit vector describing behaviors of the

984

underlying device:</p>

985

986

<p><ul>

987

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC</a>

988

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC512</a>

989

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC1K</a>

990

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC2K</a>

991

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC4K</a>

992

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC8K</a>

993

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC16K</a>

994

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC32K</a>

995

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC64K</a>

996

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SAFE_APPEND</a>

997

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SEQUENTIAL</a>

998

</ul></p>

999

1000

<p>The SQLITE_IOCAP_ATOMIC property means that all writes of

1001

any size are atomic. The SQLITE_IOCAP_ATOMICnnn values

1002

mean that writes of blocks that are nnn bytes in size and

1003

are aligned to an address which is an integer multiple of

1004

nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means

1005

that when data is appended to a file, the data is appended

1006

first then the size of the file is extended, never the other

1007

way around. The SQLITE_IOCAP_SEQUENTIAL property means that

1008

information is written to disk in the same order as calls

1009

to xWrite().</p>

1010

1011

<p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill

1012

in the unread portions of the buffer with zeros. A VFS that

1013

fails to zero-fill short reads might seem to work. However,

1014

failure to zero-fill short reads will eventually lead to

1015

database corruption.

1016

</p><hr><a name="sqlite3_mem_methods"></a>

1017

<h2>Memory Allocation Routines</h2><blockquote><pre>typedef struct sqlite3_mem_methods sqlite3_mem_methods;

1018

struct sqlite3_mem_methods {

1019

void *(*xMalloc)(int); /* Memory allocation function */

1020

void (*xFree)(void*); /* Free a prior allocation */

1021

void *(*xRealloc)(void*,int); /* Resize an allocation */

1022

int (*xSize)(void*); /* Return the size of an allocation */

1023

int (*xRoundup)(int); /* Round up request size to allocation size */

1024

int (*xInit)(void*); /* Initialize the memory allocator */

1025

void (*xShutdown)(void*); /* Deinitialize the memory allocator */

1026

void *pAppData; /* Argument to xInit() and xShutdown() */

1027

};

1028

</pre></blockquote><p>

1029

An instance of this object defines the interface between SQLite

1030

and low-level memory allocation routines.</p>

1031

1032

<p>This object is used in only one place in the SQLite interface.

1033

A pointer to an instance of this object is the argument to

1034

<a href="#sqlite3_config">sqlite3_config()</a> when the configuration option is

1035

<a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> or <a href="#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a>.

1036

By creating an instance of this object

1037

and passing it to <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>)

1038

during configuration, an application can specify an alternative

1039

memory allocation subsystem for SQLite to use for all of its

1040

dynamic memory needs.</p>

1041

1042

<p>Note that SQLite comes with several <a href="malloc.html#altalloc">built-in memory allocators</a>

1043

that are perfectly adequate for the overwhelming majority of applications

1044

and that this object is only useful to a tiny minority of applications

1045

with specialized memory allocation requirements. This object is

1046

also used during testing of SQLite in order to specify an alternative

1047

memory allocator that simulates memory out-of-memory conditions in

1048

order to verify that SQLite recovers gracefully from such

1049

conditions.</p>

1050

1051

<p>The xMalloc, xRealloc, and xFree methods must work like the

1052

malloc(), realloc() and free() functions from the standard C library.

1053

SQLite guarantees that the second argument to

1054

xRealloc is always a value returned by a prior call to xRoundup.</p>

1055

1056

<p>xSize should return the allocated size of a memory allocation

1057

previously obtained from xMalloc or xRealloc. The allocated size

1058

is always at least as big as the requested size but may be larger.</p>

1059

1060

<p>The xRoundup method returns what would be the allocated size of

1061

a memory allocation given a particular requested size. Most memory

1062

allocators round up memory allocations at least to the next multiple

1063

of 8. Some allocators round up to a larger multiple or to a power of 2.

1064

Every memory allocation request coming in through <a href="#sqlite3_free">sqlite3_malloc()</a>

1065

or <a href="#sqlite3_free">sqlite3_realloc()</a> first calls xRoundup. If xRoundup returns 0,

1066

that causes the corresponding memory allocation to fail.</p>

1067

1068

<p>The xInit method initializes the memory allocator. (For example,

1069

it might allocate any require mutexes or initialize internal data

1070

structures. The xShutdown method is invoked (indirectly) by

1071

<a href="#sqlite3_initialize">sqlite3_shutdown()</a> and should deallocate any resources acquired

1072

by xInit. The pAppData pointer is used as the only parameter to

1073

xInit and xShutdown.</p>

1074

1075

<p>SQLite holds the <a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MASTER</a> mutex when it invokes

1076

the xInit method, so the xInit method need not be threadsafe. The

1077

xShutdown method is only called from <a href="#sqlite3_initialize">sqlite3_shutdown()</a> so it does

1078

not need to be threadsafe either. For all other methods, SQLite

1079

holds the <a href="#SQLITE_MUTEX_FAST">SQLITE_MUTEX_STATIC_MEM</a> mutex as long as the

1080

<a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> configuration option is turned on (which

1081

it is by default) and so the methods are automatically serialized.

1082

However, if <a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled, then the other

1083

methods must be threadsafe or else make their own arrangements for

1084

serialization.</p>

1085

1086

<p>SQLite will never invoke xInit() more than once without an intervening

1087

call to xShutdown().

1088

</p><hr><a name="sqlite3_mutex"></a>

1089

<h2>Mutex Handle</h2><blockquote><pre>typedef struct sqlite3_mutex sqlite3_mutex;

1090

</pre></blockquote><p>

1091

The mutex module within SQLite defines <a href="#sqlite3_mutex">sqlite3_mutex</a> to be an

1092

abstract type for a mutex object. The SQLite core never looks

1093

at the internal representation of an <a href="#sqlite3_mutex">sqlite3_mutex</a>. It only

1094

deals with pointers to the <a href="#sqlite3_mutex">sqlite3_mutex</a> object.</p>

1095

1096

<p>Mutexes are created using <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a>.

1097

</p><hr><a name="sqlite3_mutex_methods"></a>

1098

<h2>Mutex Methods Object</h2><blockquote><pre>typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;

1099

struct sqlite3_mutex_methods {

1100

int (*xMutexInit)(void);

1101

int (*xMutexEnd)(void);

1102

sqlite3_mutex *(*xMutexAlloc)(int);

1103

void (*xMutexFree)(sqlite3_mutex *);

1104

void (*xMutexEnter)(sqlite3_mutex *);

1105

int (*xMutexTry)(sqlite3_mutex *);

1106

void (*xMutexLeave)(sqlite3_mutex *);

1107

int (*xMutexHeld)(sqlite3_mutex *);

1108

int (*xMutexNotheld)(sqlite3_mutex *);

1109

};

1110

</pre></blockquote><p>

1111

An instance of this structure defines the low-level routines

1112

used to allocate and use mutexes.</p>

1113

1114

<p>Usually, the default mutex implementations provided by SQLite are

1115

sufficient, however the user has the option of substituting a custom

1116

implementation for specialized deployments or systems for which SQLite

1117

does not provide a suitable implementation. In this case, the user

1118

creates and populates an instance of this structure to pass

1119

to sqlite3_config() along with the <a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option.

1120

Additionally, an instance of this structure can be used as an

1121

output variable when querying the system for the current mutex

1122

implementation, using the <a href="#sqliteconfiggetmutex">SQLITE_CONFIG_GETMUTEX</a> option.</p>

1123

1124

<p>The xMutexInit method defined by this structure is invoked as

1125

part of system initialization by the sqlite3_initialize() function.

1126

The xMutexInit routine is called by SQLite exactly once for each

1127

effective call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>.</p>

1128

1129

<p>The xMutexEnd method defined by this structure is invoked as

1130

part of system shutdown by the sqlite3_shutdown() function. The

1131

implementation of this method is expected to release all outstanding

1132

resources obtained by the mutex methods implementation, especially

1133

those obtained by the xMutexInit method. The xMutexEnd()

1134

interface is invoked exactly once for each call to <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.</p>

1135

1136

<p>The remaining seven methods defined by this structure (xMutexAlloc,

1137

xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and

1138

xMutexNotheld) implement the following interfaces (respectively):</p>

1139

1140

<p><ul>

1141

<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> </li>

1142

<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_free()</a> </li>

1143

<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter()</a> </li>

1144

<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_try()</a> </li>

1145

<li> <a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave()</a> </li>

1146

<li> <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> </li>

1147

<li> <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a> </li>

1148

</ul></p>

1149

1150

<p>The only difference is that the public sqlite3_XXX functions enumerated

1151

above silently ignore any invocations that pass a NULL pointer instead

1152

of a valid mutex handle. The implementations of the methods defined

1153

by this structure are not required to handle this case, the results

1154

of passing a NULL pointer instead of a valid mutex handle are undefined

1155

(i.e. it is acceptable to provide an implementation that segfaults if

1156

it is passed a NULL pointer).</p>

1157

1158

<p>The xMutexInit() method must be threadsafe. It must be harmless to

1159

invoke xMutexInit() multiple times within the same process and without

1160

intervening calls to xMutexEnd(). Second and subsequent calls to

1161

xMutexInit() must be no-ops.</p>

1162

1163

<p>xMutexInit() must not use SQLite memory allocation (<a href="#sqlite3_free">sqlite3_malloc()</a>

1164

and its associates). Similarly, xMutexAlloc() must not use SQLite memory

1165

allocation for a static mutex. However xMutexAlloc() may use SQLite

1166

memory allocation for a fast or recursive mutex.</p>

1167

1168

<p>SQLite will invoke the xMutexEnd() method when <a href="#sqlite3_initialize">sqlite3_shutdown()</a> is

1169

called, but only if the prior call to xMutexInit returned SQLITE_OK.

1170

If xMutexInit fails in any way, it is expected to clean up after itself

1171

prior to returning.

1172

</p><hr><a name="sqlite3_pcache"></a>

1173

<h2>Custom Page Cache Object</h2><blockquote><pre>typedef struct sqlite3_pcache sqlite3_pcache;

1174

</pre></blockquote><p>

1175

The sqlite3_pcache type is opaque. It is implemented by

1176

the pluggable module. The SQLite core has no knowledge of

1177

its size or internal structure and never deals with the

1178

sqlite3_pcache object except by holding and passing pointers

1179

to the object.</p>

1180

1181

<p>See <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> for additional information.

1182

</p><hr><a name="sqlite3_pcache_page"></a>

1183

<h2>Custom Page Cache Object</h2><blockquote><pre>typedef struct sqlite3_pcache_page sqlite3_pcache_page;

1184

struct sqlite3_pcache_page {

1185

void *pBuf; /* The content of the page */

1186

void *pExtra; /* Extra information associated with the page */

1187

};

1188

</pre></blockquote><p>

1189

The sqlite3_pcache_page object represents a single page in the

1190

page cache. The page cache will allocate instances of this

1191

object. Various methods of the page cache use pointers to instances

1192

of this object as parameters or as their return value.</p>

1193

1194

<p>See <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> for additional information.

1195

</p><hr><a name="sqlite3_temp_directory"></a>

1196

<h2>Name Of The Folder Holding Temporary Files</h2><blockquote><pre>SQLITE_EXTERN char *sqlite3_temp_directory;

1197

</pre></blockquote><p>

1198

If this global variable is made to point to a string which is

1199

the name of a folder (a.k.a. directory), then all temporary files

1200

created by SQLite when using a built-in <a href="#sqlite3_vfs">VFS</a>

1201

will be placed in that directory. If this variable

1202

is a NULL pointer, then SQLite performs a search for an appropriate

1203

temporary file directory.</p>

1204

1205

<p>It is not safe to read or modify this variable in more than one

1206

thread at a time. It is not safe to read or modify this variable

1207

if a <a href="#sqlite3">database connection</a> is being used at the same time in a separate

1208

thread.

1209

It is intended that this variable be set once

1210

as part of process initialization and before any SQLite interface

1211

routines have been called and that this variable remain unchanged

1212

thereafter.</p>

1213

1214

<p>The <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> may modify this variable and cause

1215

it to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>. Furthermore,

1216

the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> always assumes that any string

1217

that this variable points to is held in memory obtained from

1218

<a href="#sqlite3_free">sqlite3_malloc</a> and the pragma may attempt to free that memory

1219

using <a href="#sqlite3_free">sqlite3_free</a>.

1220

Hence, if this variable is modified directly, either it should be

1221

made NULL or made to point to memory obtained from <a href="#sqlite3_free">sqlite3_malloc</a>

1222

or else the use of the <a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a> should be avoided.

1223

</p><hr><a name="sqlite3_vfs"></a>

1224

<h2>OS Interface Object</h2><blockquote><pre>typedef struct sqlite3_vfs sqlite3_vfs;

1225

typedef void (*sqlite3_syscall_ptr)(void);

1226

struct sqlite3_vfs {

1227

int iVersion; /* Structure version number (currently 3) */

1228

int szOsFile; /* Size of subclassed sqlite3_file */

1229

int mxPathname; /* Maximum file pathname length */

1230

sqlite3_vfs *pNext; /* Next registered VFS */

1231

const char *zName; /* Name of this virtual file system */

1232

void *pAppData; /* Pointer to application-specific data */

1233

int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,

1234

int flags, int *pOutFlags);

1235

int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);

1236

int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);

1237

int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);

1238

void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);

1239

void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);

1240

void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);

1241

void (*xDlClose)(sqlite3_vfs*, void*);

1242

int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);

1243

int (*xSleep)(sqlite3_vfs*, int microseconds);

1244

int (*xCurrentTime)(sqlite3_vfs*, double*);

1245

int (*xGetLastError)(sqlite3_vfs*, int, char *);

1246

/*

1247

** The methods above are in version 1 of the sqlite_vfs object

1248

** definition. Those that follow are added in version 2 or later

1249

*/

1250

int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);

1251

/*

1252

** The methods above are in versions 1 and 2 of the sqlite_vfs object.

1253

** Those below are for version 3 and greater.

1254

*/

1255

int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);

1256

sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);

1257

const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);

1258

/*

1259

** The methods above are in versions 1 through 3 of the sqlite_vfs object.

1260

** New fields may be appended in figure versions. The iVersion

1261

** value will increment whenever this happens.

1262

*/

1263

};

1264

</pre></blockquote><p>

1265

An instance of the sqlite3_vfs object defines the interface between

1266

the SQLite core and the underlying operating system. The "vfs"

1267

in the name of the object stands for "virtual file system". See

1268

the <a href="vfs.html">VFS documentation</a> for further information.</p>

1269

1270

<p>The value of the iVersion field is initially 1 but may be larger in

1271

future versions of SQLite. Additional fields may be appended to this

1272

object when the iVersion value is increased. Note that the structure

1273

of the sqlite3_vfs object changes in the transaction between

1274

SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not

1275

modified.</p>

1276

1277

<p>The szOsFile field is the size of the subclassed <a href="#sqlite3_file">sqlite3_file</a>

1278

structure used by this VFS. mxPathname is the maximum length of

1279

a pathname in this VFS.</p>

1280

1281

<p>Registered sqlite3_vfs objects are kept on a linked list formed by

1282

the pNext pointer. The <a href="#sqlite3_vfs_find">sqlite3_vfs_register()</a>

1283

and <a href="#sqlite3_vfs_find">sqlite3_vfs_unregister()</a> interfaces manage this list

1284

in a thread-safe way. The <a href="#sqlite3_vfs_find">sqlite3_vfs_find()</a> interface

1285

searches the list. Neither the application code nor the VFS

1286

implementation should use the pNext pointer.</p>

1287

1288

<p>The pNext field is the only field in the sqlite3_vfs

1289

structure that SQLite will ever modify. SQLite will only access

1290

or modify this field while holding a particular static mutex.

1291

The application should never modify anything within the sqlite3_vfs

1292

object once the object has been registered.</p>

1293

1294

<p>The zName field holds the name of the VFS module. The name must

1295

be unique across all VFS modules.</p>

1296

1297

1298

1299

SQLite guarantees that the zFilename parameter to xOpen

1300

is either a NULL pointer or string obtained

1301

from xFullPathname() with an optional suffix added.

1302

If a suffix is added to the zFilename parameter, it will

1303

consist of a single "-" character followed by no more than

1304

11 alphanumeric and/or "-" characters.

1305

SQLite further guarantees that

1306

the string will be valid and unchanged until xClose() is

1307

called. Because of the previous sentence,

1308

the <a href="#sqlite3_file">sqlite3_file</a> can safely store a pointer to the

1309

filename if it needs to remember the filename for some reason.

1310

If the zFilename parameter to xOpen is a NULL pointer then xOpen

1311

must invent its own temporary name for the file. Whenever the

1312

xFilename parameter is NULL it will also be the case that the

1313

flags parameter will include <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>.</p>

1314

1315

<p>The flags argument to xOpen() includes all bits set in

1316

the flags argument to <a href="#sqlite3_open">sqlite3_open_v2()</a>. Or if <a href="#sqlite3_open">sqlite3_open()</a>

1317

or <a href="#sqlite3_open">sqlite3_open16()</a> is used, then flags includes at least

1318

<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a> | <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a>.

1319

If xOpen() opens a file read-only then it sets *pOutFlags to

1320

include <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be set.</p>

1321

1322

<p>SQLite will also add one of the following flags to the xOpen()

1323

call, depending on the object being opened:</p>

1324

1325

<p><ul>

1326

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_DB</a>

1327

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_JOURNAL</a>

1328

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_DB</a>

1329

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TEMP_JOURNAL</a>

1330

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_TRANSIENT_DB</a>

1331

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SUBJOURNAL</a>

1332

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MASTER_JOURNAL</a>

1333

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_WAL</a>

1334

</ul></p>

1335

1336

<p>The file I/O implementation can use the object type flags to

1337

change the way it deals with files. For example, an application

1338

that does not care about crash recovery or rollback might make

1339

the open of a journal file a no-op. Writes to this journal would

1340

also be no-ops, and any attempt to read the journal would return

1341

SQLITE_IOERR. Or the implementation might recognize that a database

1342

file will be doing page-aligned sector reads and writes in a random

1343

order and set up its I/O subsystem accordingly.</p>

1344

1345

<p>SQLite might also add one of the following flags to the xOpen method:</p>

1346

1347

<p><ul>

1348

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>

1349

<li> <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a>

1350

</ul></p>

1351

1352

<p>The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be

1353

deleted when it is closed. The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_DELETEONCLOSE</a>

1354

will be set for TEMP databases and their journals, transient

1355

databases, and subjournals.</p>

1356

1357

<p>The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_EXCLUSIVE</a> flag is always used in conjunction

1358

with the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a> flag, which are both directly

1359

analogous to the O_EXCL and O_CREAT flags of the POSIX open()

1360

API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the

1361

SQLITE_OPEN_CREATE, is used to indicate that file should always

1362

be created, and that it is an error if it already exists.

1363

It is <i>not</i> used to indicate the file should be opened

1364

for exclusive access.</p>

1365

1366

<p>At least szOsFile bytes of memory are allocated by SQLite

1367

to hold the <a href="#sqlite3_file">sqlite3_file</a> structure passed as the third

1368

argument to xOpen. The xOpen method does not have to

1369

allocate the structure; it should just fill it in. Note that

1370

the xOpen method must set the sqlite3_file.pMethods to either

1371

a valid <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object or to NULL. xOpen must do

1372

this even if the open fails. SQLite expects that the sqlite3_file.pMethods

1373

element will be valid after xOpen returns regardless of the success

1374

or failure of the xOpen call.</p>

1375

1376

1377

1378

The flags argument to xAccess() may be <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_EXISTS</a>

1379

to test for the existence of a file, or <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READWRITE</a> to

1380

test whether a file is readable and writable, or <a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READ</a>

1381

to test whether a file is at least readable. The file can be a

1382

directory.</p>

1383

1384

<p>SQLite will always allocate at least mxPathname+1 bytes for the

1385

output buffer xFullPathname. The exact size of the output buffer

1386

is also passed as a parameter to both methods. If the output buffer

1387

is not large enough, <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a> should be returned. Since this is

1388

handled as a fatal error by SQLite, vfs implementations should endeavor

1389

to prevent this by setting mxPathname to a sufficiently large value.</p>

1390

1391

<p>The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()

1392

interfaces are not strictly a part of the filesystem, but they are

1393

included in the VFS structure for completeness.

1394

The xRandomness() function attempts to return nBytes bytes

1395

of good-quality randomness into zOut. The return value is

1396

the actual number of bytes of randomness obtained.

1397

The xSleep() method causes the calling thread to sleep for at

1398

least the number of microseconds given. The xCurrentTime()

1399

method returns a Julian Day Number for the current date and time as

1400

a floating point value.

1401

The xCurrentTimeInt64() method returns, as an integer, the Julian

1402

Day Number multiplied by 86400000 (the number of milliseconds in

1403

a 24-hour day).

1404

SQLite will use the xCurrentTimeInt64() method to get the current

1405

date and time if that method is available (if iVersion is 2 or

1406

greater and the function pointer is not NULL) and will fall back

1407

to xCurrentTime() if xCurrentTimeInt64() is unavailable.</p>

1408

1409

<p>The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces

1410

are not used by the SQLite core. These optional interfaces are provided

1411

by some VFSes to facilitate testing of the VFS code. By overriding

1412

system calls with functions under its control, a test program can

1413

simulate faults and error conditions that would otherwise be difficult

1414

or impossible to induce. The set of system calls that can be overridden

1415

varies from one VFS to another, and from one version of the same VFS to the

1416

next. Applications that use these interfaces must be prepared for any

1417

or all of these interfaces to be NULL or for their behavior to change

1418

from one release to the next. Applications must not attempt to access

1419

any of these methods if the iVersion of the VFS is less than 3.

1420

</p><hr><a name="sqlite3_vtab"></a>

1421

<h2>Virtual Table Instance Object</h2><blockquote><pre>struct sqlite3_vtab {

1422

const sqlite3_module *pModule; /* The module for this virtual table */

1423

int nRef; /* NO LONGER USED */

1424

char *zErrMsg; /* Error message from sqlite3_mprintf() */

1425

/* Virtual table implementations will typically add additional fields */

1426

};

1427

</pre></blockquote><p>

1428

Every <a href="#sqlite3_module">virtual table module</a> implementation uses a subclass

1429

of this object to describe a particular instance

1430

of the <a href="vtab.html">virtual table</a>. Each subclass will

1431

be tailored to the specific needs of the module implementation.

1432

The purpose of this superclass is to define certain fields that are

1433

common to all module implementations.</p>

1434

1435

<p>Virtual tables methods can set an error message by assigning a

1436

string obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a> to zErrMsg. The method should

1437

take care that any prior string is freed by a call to <a href="#sqlite3_free">sqlite3_free()</a>

1438

prior to assigning a new string to zErrMsg. After the error message

1439

is delivered up to the client application, the string will be automatically

1440

freed by sqlite3_free() and the zErrMsg field will be zeroed.

1441

</p><hr><a name="sqlite3_aggregate_context"></a>

1442

<h2>Obtain Aggregate Function Context</h2><blockquote><pre>void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

1443

</pre></blockquote><p>

1444

Implementations of aggregate SQL functions use this

1445

routine to allocate memory for storing their state.</p>

1446

1447

<p>The first time the sqlite3_aggregate_context(C,N) routine is called

1448

for a particular aggregate function, SQLite

1449

allocates N of memory, zeroes out that memory, and returns a pointer

1450

to the new memory. On second and subsequent calls to

1451

sqlite3_aggregate_context() for the same aggregate function instance,

1452

the same buffer is returned. Sqlite3_aggregate_context() is normally

1453

called once for each invocation of the xStep callback and then one

1454

last time when the xFinal callback is invoked. When no rows match

1455

an aggregate query, the xStep() callback of the aggregate function

1456

implementation is never called and xFinal() is called exactly once.

1457

In those cases, sqlite3_aggregate_context() might be called for the

1458

first time from within xFinal().</p>

1459

1460

<p>The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is

1461

less than or equal to zero or if a memory allocate error occurs.</p>

1462

1463

<p>The amount of space allocated by sqlite3_aggregate_context(C,N) is

1464

determined by the N parameter on first successful call. Changing the

1465

value of N in subsequent call to sqlite3_aggregate_context() within

1466

the same aggregate function instance will not resize the memory

1467

allocation.</p>

1468

1469

<p>SQLite automatically frees the memory allocated by

1470

sqlite3_aggregate_context() when the aggregate query concludes.</p>

1471

1472

<p>The first parameter must be a copy of the

1473

<a href="#sqlite3_context">SQL function context</a> that is the first parameter

1474

to the xStep or xFinal callback routine that implements the aggregate

1475

function.</p>

1476

1477

<p>This routine must be called from the same thread in which

1478

the aggregate SQL function is running.

1479

</p><hr><a name="sqlite3_auto_extension"></a>

1480

<h2>Automatically Load Statically Linked Extensions</h2><blockquote><pre>int sqlite3_auto_extension(void (*xEntryPoint)(void));

1481

</pre></blockquote><p>

1482

This interface causes the xEntryPoint() function to be invoked for

1483

each new <a href="#sqlite3">database connection</a> that is created. The idea here is that

1484

xEntryPoint() is the entry point for a statically linked SQLite extension

1485

that is to be automatically loaded into all new database connections.</p>

1486

1487

<p>Even though the function prototype shows that xEntryPoint() takes

1488

no arguments and returns void, SQLite invokes xEntryPoint() with three

1489

arguments and expects and integer result as if the signature of the

1490

entry point where as follows:</p>

1491

1492

1493

  int xEntryPoint(

1494

  sqlite3 *db,

1495

  const char **pzErrMsg,

1496

  const struct sqlite3_api_routines *pThunk

1497

  );

1498

</pre></blockquote></p>

1499

1500

<p>If the xEntryPoint routine encounters an error, it should make *pzErrMsg

1501

point to an appropriate error message (obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a>)

1502

and return an appropriate <a href="#SQLITE_ABORT">error code</a>. SQLite ensures that *pzErrMsg

1503

is NULL before calling the xEntryPoint(). SQLite will invoke

1504

<a href="#sqlite3_free">sqlite3_free()</a> on *pzErrMsg after xEntryPoint() returns. If any

1505

xEntryPoint() returns an error, the <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>,

1506

or <a href="#sqlite3_open">sqlite3_open_v2()</a> call that provoked the xEntryPoint() will fail.</p>

1507

1508

<p>Calling sqlite3_auto_extension(X) with an entry point X that is already

1509

on the list of automatic extensions is a harmless no-op. No entry point

1510

will be called more than once for each database connection that is opened.</p>

1511

1512

<p>See also: <a href="#sqlite3_reset_auto_extension">sqlite3_reset_auto_extension()</a>.

1513

</p><hr><a name="sqlite3_bind_parameter_count"></a>

1514

<h2>Number Of SQL Parameters</h2><blockquote><pre>int sqlite3_bind_parameter_count(sqlite3_stmt*);

1515

</pre></blockquote><p>

1516

This routine can be used to find the number of <a href="#sqlite3_bind_blob">SQL parameters</a>

1517

in a <a href="#sqlite3_stmt">prepared statement</a>. SQL parameters are tokens of the

1518

form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as

1519

placeholders for values that are <a href="#sqlite3_bind_blob">bound</a>

1520

to the parameters at a later time.</p>

1521

1522

<p>This routine actually returns the index of the largest (rightmost)

1523

parameter. For all forms except ?NNN, this will correspond to the

1524

number of unique parameters. If parameters of the ?NNN form are used,

1525

there may be gaps in the list.</p>

1526

1527

<p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

1528

<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and

1529

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.

1530

</p><hr><a name="sqlite3_bind_parameter_index"></a>

1531

<h2>Index Of A Parameter With A Given Name</h2><blockquote><pre>int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

1532

</pre></blockquote><p>

1533

Return the index of an SQL parameter given its name. The

1534

index value returned is suitable for use as the second

1535

parameter to <a href="#sqlite3_bind_blob">sqlite3_bind()</a>. A zero

1536

is returned if no matching parameter is found. The parameter

1537

name must be given in UTF-8 even if the original statement

1538

was prepared from UTF-16 text using <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.</p>

1539

1540

<p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

1541

<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and

1542

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.

1543

</p><hr><a name="sqlite3_bind_parameter_name"></a>

1544

<h2>Name Of A Host Parameter</h2><blockquote><pre>const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

1545

</pre></blockquote><p>

1546

The sqlite3_bind_parameter_name(P,N) interface returns

1547

the name of the N-th <a href="#sqlite3_bind_blob">SQL parameter</a> in the <a href="#sqlite3_stmt">prepared statement</a> P.

1548

SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"

1549

have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"

1550

respectively.

1551

In other words, the initial ":" or "$" or "@" or "?"

1552

is included as part of the name.

1553

Parameters of the form "?" without a following integer have no name

1554

and are referred to as "nameless" or "anonymous parameters".</p>

1555

1556

<p>The first host parameter has an index of 1, not 0.</p>

1557

1558

<p>If the value N is out of range or if the N-th parameter is

1559

nameless, then NULL is returned. The returned string is

1560

always in UTF-8 encoding even if the named parameter was

1561

originally specified as UTF-16 in <a href="#sqlite3_prepare">sqlite3_prepare16()</a> or

1562

<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.</p>

1563

1564

<p>See also: <a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

1565

<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and

1566

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.

1567

</p><hr><a name="sqlite3_blob_bytes"></a>

1568

<h2>Return The Size Of An Open BLOB</h2><blockquote><pre>int sqlite3_blob_bytes(sqlite3_blob *);

1569

</pre></blockquote><p>

1570

Returns the size in bytes of the BLOB accessible via the

1571

successfully opened <a href="#sqlite3_blob">BLOB handle</a> in its only argument. The

1572

incremental blob I/O routines can only read or overwriting existing

1573

blob content; they cannot change the size of a blob.</p>

1574

1575

<p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created

1576

by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not

1577

been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in

1578

to this routine results in undefined and probably undesirable behavior.

1579

</p><hr><a name="sqlite3_blob_close"></a>

1580

<h2>Close A BLOB Handle</h2><blockquote><pre>int sqlite3_blob_close(sqlite3_blob *);

1581

</pre></blockquote><p>

1582

Closes an open <a href="#sqlite3_blob">BLOB handle</a>.</p>

1583

1584

<p>Closing a BLOB shall cause the current transaction to commit

1585

if there are no other BLOBs, no pending prepared statements, and the

1586

database connection is in <a href="#sqlite3_get_autocommit">autocommit mode</a>.

1587

If any writes were made to the BLOB, they might be held in cache

1588

until the close operation if they will fit.</p>

1589

1590

<p>Closing the BLOB often forces the changes

1591

out to disk and so if any I/O errors occur, they will likely occur

1592

at the time when the BLOB is closed. Any errors that occur during

1593

closing are reported as a non-zero return value.</p>

1594

1595

<p>The BLOB is closed unconditionally. Even if this routine returns

1596

an error code, the BLOB is still closed.</p>

1597

1598

<p>Calling this routine with a null pointer (such as would be returned

1599

by a failed call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a>) is a harmless no-op.

1600

</p><hr><a name="sqlite3_blob_open"></a>

1601

<h2>Open A BLOB For Incremental I/O</h2><blockquote><pre>int sqlite3_blob_open(

1602

sqlite3*,

1603

const char *zDb,

1604

const char *zTable,

1605

const char *zColumn,

1606

sqlite3_int64 iRow,

1607

int flags,

1608

sqlite3_blob **ppBlob

1609

);

1610

</pre></blockquote><p>

1611

This interfaces opens a <a href="#sqlite3_blob">handle</a> to the BLOB located

1612

in row iRow, column zColumn, table zTable in database zDb;

1613

in other words, the same BLOB that would be selected by:</p>

1614

1615

1616

SELECT zColumn FROM zDb.zTable WHERE <a href="lang_createtable.html#rowid">rowid</a> = iRow;

1617

</pre></p>

1618

1619

<p>If the flags parameter is non-zero, then the BLOB is opened for read

1620

and write access. If it is zero, the BLOB is opened for read access.

1621

It is not possible to open a column that is part of an index or primary

1622

key for writing. If <a href="foreignkeys.html">foreign key constraints</a> are enabled, it is

1623

not possible to open a column that is part of a <a href="foreignkeys.html#parentchild">child key</a> for writing.</p>

1624

1625

<p>Note that the database name is not the filename that contains

1626

the database but rather the symbolic name of the database that

1627

appears after the AS keyword when the database is connected using <a href="lang_attach.html">ATTACH</a>.

1628

For the main database file, the database name is "main".

1629

For TEMP tables, the database name is "temp".</p>

1630

1631

<p>On success, <a href="#SQLITE_ABORT">SQLITE_OK</a> is returned and the new <a href="#sqlite3_blob">BLOB handle</a> is written

1632

to *ppBlob. Otherwise an <a href="#SQLITE_ABORT">error code</a> is returned and *ppBlob is set

1633

to be a null pointer.

1634

This function sets the <a href="#sqlite3">database connection</a> error code and message

1635

accessible via <a href="#sqlite3_errcode">sqlite3_errcode()</a> and <a href="#sqlite3_errcode">sqlite3_errmsg()</a> and related

1636

functions. Note that the *ppBlob variable is always initialized in a

1637

way that makes it safe to invoke <a href="#sqlite3_blob_close">sqlite3_blob_close()</a> on *ppBlob

1638

regardless of the success or failure of this routine.</p>

1639

1640

<p>If the row that a BLOB handle points to is modified by an

1641

<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

1642

then the BLOB handle is marked as "expired".

1643

This is true if any column of the row is changed, even a column

1644

other than the one the BLOB handle is open on.

1645

Calls to <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> for

1646

an expired BLOB handle fail with a return code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>.

1647

Changes written into a BLOB prior to the BLOB expiring are not

1648

rolled back by the expiration of the BLOB. Such changes will eventually

1649

commit if the transaction continues to completion.</p>

1650

1651

<p>Use the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface to determine the size of

1652

the opened blob. The size of a blob may not be changed by this

1653

interface. Use the <a href="lang_update.html">UPDATE</a> SQL command to change the size of a

1654

blob.</p>

1655

1656

<p>The <a href="#sqlite3_bind_blob">sqlite3_bind_zeroblob()</a> and <a href="#sqlite3_result_blob">sqlite3_result_zeroblob()</a> interfaces

1657

and the built-in <a href="lang_corefunc.html#zeroblob">zeroblob</a> SQL function can be used, if desired,

1658

to create an empty, zero-filled blob in which to read or write using

1659

this interface.</p>

1660

1661

<p>To avoid a resource leak, every open <a href="#sqlite3_blob">BLOB handle</a> should eventually

1662

be released by a call to <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.

1663

</p><hr><a name="sqlite3_blob_read"></a>

1664

<h2>Read Data From A BLOB Incrementally</h2><blockquote><pre>int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);

1665

</pre></blockquote><p>

1666

This function is used to read data from an open <a href="#sqlite3_blob">BLOB handle</a> into a

1667

caller-supplied buffer. N bytes of data are copied into buffer Z

1668

from the open BLOB, starting at offset iOffset.</p>

1669

1670

<p>If offset iOffset is less than N bytes from the end of the BLOB,

1671

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read. If N or iOffset is

1672

less than zero, <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read.

1673

The size of the blob (and hence the maximum value of N+iOffset)

1674

can be determined using the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface.</p>

1675

1676

<p>An attempt to read from an expired <a href="#sqlite3_blob">BLOB handle</a> fails with an

1677

error code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>.</p>

1678

1679

<p>On success, sqlite3_blob_read() returns SQLITE_OK.

1680

Otherwise, an <a href="#SQLITE_ABORT">error code</a> or an <a href="#SQLITE_ABORT_ROLLBACK">extended error code</a> is returned.</p>

1681

1682

<p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created

1683

by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not

1684

been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in

1685

to this routine results in undefined and probably undesirable behavior.</p>

1686

1687

<p>See also: <a href="#sqlite3_blob_write">sqlite3_blob_write()</a>.

1688

</p><hr><a name="sqlite3_blob_reopen"></a>

1689

<h2>Move a BLOB Handle to a New Row</h2><blockquote><pre>int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);

1690

</pre></blockquote><p>

1691

This function is used to move an existing blob handle so that it points

1692

to a different row of the same database table. The new row is identified

1693

by the rowid value passed as the second argument. Only the row can be

1694

changed. The database, table and column on which the blob handle is open

1695

remain the same. Moving an existing blob handle to a new row can be

1696

faster than closing the existing handle and opening a new one.</p>

1697

1698

<p>The new row must meet the same criteria as for <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> -

1699

it must exist and there must be either a blob or text value stored in

1700

the nominated column. If the new row is not present in the table, or if

1701

it does not contain a blob or text value, or if another error occurs, an

1702

SQLite error code is returned and the blob handle is considered aborted.

1703

All subsequent calls to <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>, <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> or

1704

<a href="#sqlite3_blob_reopen">sqlite3_blob_reopen()</a> on an aborted blob handle immediately return

1705

SQLITE_ABORT. Calling <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> on an aborted blob handle

1706

always returns zero.</p>

1707

1708

<p>This function sets the database handle error code and message.

1709

</p><hr><a name="sqlite3_blob_write"></a>

1710

<h2>Write Data Into A BLOB Incrementally</h2><blockquote><pre>int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

1711

</pre></blockquote><p>

1712

This function is used to write data into an open <a href="#sqlite3_blob">BLOB handle</a> from a

1713

caller-supplied buffer. N bytes of data are copied from the buffer Z

1714

into the open BLOB, starting at offset iOffset.</p>

1715

1716

<p>If the <a href="#sqlite3_blob">BLOB handle</a> passed as the first argument was not opened for

1717

writing (the flags parameter to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> was zero),

1718

this function returns <a href="#SQLITE_ABORT">SQLITE_READONLY</a>.</p>

1719

1720

<p>This function may only modify the contents of the BLOB; it is

1721

not possible to increase the size of a BLOB using this API.

1722

If offset iOffset is less than N bytes from the end of the BLOB,

1723

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written. If N is

1724

less than zero <a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written.

1725

The size of the BLOB (and hence the maximum value of N+iOffset)

1726

can be determined using the <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface.</p>

1727

1728

<p>An attempt to write to an expired <a href="#sqlite3_blob">BLOB handle</a> fails with an

1729

error code of <a href="#SQLITE_ABORT">SQLITE_ABORT</a>. Writes to the BLOB that occurred

1730

before the <a href="#sqlite3_blob">BLOB handle</a> expired are not rolled back by the

1731

expiration of the handle, though of course those changes might

1732

have been overwritten by the statement that expired the BLOB handle

1733

or by other independent statements.</p>

1734

1735

<p>On success, sqlite3_blob_write() returns SQLITE_OK.

1736

Otherwise, an <a href="#SQLITE_ABORT">error code</a> or an <a href="#SQLITE_ABORT_ROLLBACK">extended error code</a> is returned.</p>

1737

1738

<p>This routine only works on a <a href="#sqlite3_blob">BLOB handle</a> which has been created

1739

by a prior successful call to <a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and which has not

1740

been closed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>. Passing any other pointer in

1741

to this routine results in undefined and probably undesirable behavior.</p>

1742

1743

<p>See also: <a href="#sqlite3_blob_read">sqlite3_blob_read()</a>.

1744

</p><hr><a name="sqlite3_busy_handler"></a>

1745

<h2>Register A Callback To Handle SQLITE_BUSY Errors</h2><blockquote><pre>int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

1746

</pre></blockquote><p>

1747

This routine sets a callback function that might be invoked whenever

1748

an attempt is made to open a database table that another thread

1749

or process has locked.</p>

1750

1751

<p>If the busy callback is NULL, then <a href="#SQLITE_ABORT">SQLITE_BUSY</a> or <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a>

1752

is returned immediately upon encountering the lock. If the busy callback

1753

is not NULL, then the callback might be invoked with two arguments.</p>

1754

1755

<p>The first argument to the busy handler is a copy of the void* pointer which

1756

is the third argument to sqlite3_busy_handler(). The second argument to

1757

the busy handler callback is the number of times that the busy handler has

1758

been invoked for this locking event. If the

1759

busy callback returns 0, then no additional attempts are made to

1760

access the database and <a href="#SQLITE_ABORT">SQLITE_BUSY</a> or <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a> is returned.

1761

If the callback returns non-zero, then another attempt

1762

is made to open the database for reading and the cycle repeats.</p>

1763

1764

<p>The presence of a busy handler does not guarantee that it will be invoked

1765

when there is lock contention. If SQLite determines that invoking the busy

1766

handler could result in a deadlock, it will go ahead and return <a href="#SQLITE_ABORT">SQLITE_BUSY</a>

1767

or <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a> instead of invoking the busy handler.

1768

Consider a scenario where one process is holding a read lock that

1769

it is trying to promote to a reserved lock and

1770

a second process is holding a reserved lock that it is trying

1771

to promote to an exclusive lock. The first process cannot proceed

1772

because it is blocked by the second and the second process cannot

1773

proceed because it is blocked by the first. If both processes

1774

invoke the busy handlers, neither will make any progress. Therefore,

1775

SQLite returns <a href="#SQLITE_ABORT">SQLITE_BUSY</a> for the first process, hoping that this

1776

will induce the first process to release its read lock and allow

1777

the second process to proceed.</p>

1778

1779

<p>The default busy callback is NULL.</p>

1780

1781

<p>The <a href="#SQLITE_ABORT">SQLITE_BUSY</a> error is converted to <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a>

1782

when SQLite is in the middle of a large transaction where all the

1783

changes will not fit into the in-memory cache. SQLite will

1784

already hold a RESERVED lock on the database file, but it needs

1785

to promote this lock to EXCLUSIVE so that it can spill cache

1786

pages into the database file without harm to concurrent

1787

readers. If it is unable to promote the lock, then the in-memory

1788

cache will be left in an inconsistent state and so the error

1789

code is promoted from the relatively benign <a href="#SQLITE_ABORT">SQLITE_BUSY</a> to

1790

the more severe <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a>. This error code promotion

1791

forces an automatic rollback of the changes. See the

1792

1793

CorruptionFollowingBusyError</a> wiki page for a discussion of why

1794

this is important.</p>

1795

1796

<p>There can only be a single busy handler defined for each

1797

<a href="#sqlite3">database connection</a>. Setting a new busy handler clears any

1798

previously set handler. Note that calling <a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>

1799

will also set or clear the busy handler.</p>

1800

1801

<p>The busy callback should not take any actions which modify the

1802

database connection that invoked the busy handler. Any such actions

1803

result in undefined behavior.</p>

1804

1805

<p>A busy handler must not close the database connection

1806

or <a href="#sqlite3_stmt">prepared statement</a> that invoked the busy handler.

1807

</p><hr><a name="sqlite3_busy_timeout"></a>

1808

<h2>Set A Busy Timeout</h2><blockquote><pre>int sqlite3_busy_timeout(sqlite3*, int ms);

1809

</pre></blockquote><p>

1810

This routine sets a <a href="#sqlite3_busy_handler">busy handler</a> that sleeps

1811

for a specified amount of time when a table is locked. The handler

1812

will sleep multiple times until at least "ms" milliseconds of sleeping

1813

have accumulated. After at least "ms" milliseconds of sleeping,

1814

the handler returns 0 which causes <a href="#sqlite3_step">sqlite3_step()</a> to return

1815

<a href="#SQLITE_ABORT">SQLITE_BUSY</a> or <a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_BLOCKED</a>.</p>

1816

1817

<p>Calling this routine with an argument less than or equal to zero

1818

turns off all busy handlers.</p>

1819

1820

<p>There can only be a single busy handler for a particular

1821

<a href="#sqlite3">database connection</a> any any given moment. If another busy handler

1822

was defined (using <a href="#sqlite3_busy_handler">sqlite3_busy_handler()</a>) prior to calling

1823

this routine, that other busy handler is cleared.

1824

</p><hr><a name="sqlite3_changes"></a>

1825

<h2>Count The Number Of Rows Modified</h2><blockquote><pre>int sqlite3_changes(sqlite3*);

1826

</pre></blockquote><p>

1827

This function returns the number of database rows that were changed

1828

or inserted or deleted by the most recently completed SQL statement

1829

on the <a href="#sqlite3">database connection</a> specified by the first parameter.

1830

Only changes that are directly specified by the <a href="lang_insert.html">INSERT</a>, <a href="lang_update.html">UPDATE</a>,

1831

or <a href="lang_delete.html">DELETE</a> statement are counted. Auxiliary changes caused by

1832

triggers or <a href="foreignkeys.html#fk_actions">foreign key actions</a> are not counted. Use the

1833

<a href="#sqlite3_total_changes">sqlite3_total_changes()</a> function to find the total number of changes

1834

including changes caused by triggers and foreign key actions.</p>

1835

1836

<p>Changes to a view that are simulated by an <a href="lang_createtrigger.html#instead_of_trigger">INSTEAD OF trigger</a>

1837

are not counted. Only real table changes are counted.</p>

1838

1839

<p>A "row change" is a change to a single row of a single table

1840

caused by an INSERT, DELETE, or UPDATE statement. Rows that

1841

are changed as side effects of <a href="lang_replace.html">REPLACE</a> constraint resolution,

1842

rollback, ABORT processing, <a href="lang_droptable.html">DROP TABLE</a>, or by any other

1843

mechanisms do not count as direct row changes.</p>

1844

1845

<p>A "trigger context" is a scope of execution that begins and

1846

ends with the script of a <a href="lang_createtrigger.html">trigger</a>.

1847

Most SQL statements are

1848

evaluated outside of any trigger. This is the "top level"

1849

trigger context. If a trigger fires from the top level, a

1850

new trigger context is entered for the duration of that one

1851

trigger. Subtriggers create subcontexts for their duration.</p>

1852

1853

<p>Calling <a href="#sqlite3_exec">sqlite3_exec()</a> or <a href="#sqlite3_step">sqlite3_step()</a> recursively does

1854

not create a new trigger context.</p>

1855

1856

<p>This function returns the number of direct row changes in the

1857

most recent INSERT, UPDATE, or DELETE statement within the same

1858

trigger context.</p>

1859

1860

<p>Thus, when called from the top level, this function returns the

1861

number of changes in the most recent INSERT, UPDATE, or DELETE

1862

that also occurred at the top level. Within the body of a trigger,

1863

the sqlite3_changes() interface can be called to find the number of

1864

changes in the most recently completed INSERT, UPDATE, or DELETE

1865

statement within the body of the same trigger.

1866

However, the number returned does not include changes

1867

caused by subtriggers since those have their own context.</p>

1868

1869

<p>See also the <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> interface, the

1870

<a href="pragma.html#pragma_count_changes">count_changes pragma</a>, and the <a href="lang_corefunc.html#changes">changes() SQL function</a>.</p>

1871

1872

<p>If a separate thread makes changes on the same database connection

1873

while <a href="#sqlite3_changes">sqlite3_changes()</a> is running then the value returned

1874

is unpredictable and not meaningful.

1875

</p><hr><a name="sqlite3_clear_bindings"></a>

1876

<h2>Reset All Bindings On A Prepared Statement</h2><blockquote><pre>int sqlite3_clear_bindings(sqlite3_stmt*);

1877

</pre></blockquote><p>

1878

Contrary to the intuition of many, <a href="#sqlite3_reset">sqlite3_reset()</a> does not reset

1879

the <a href="#sqlite3_bind_blob">bindings</a> on a <a href="#sqlite3_stmt">prepared statement</a>.

1880

Use this routine to reset all host parameters to NULL.

1881

</p><hr><a name="sqlite3_close"></a>

1882

<h2>Closing A Database Connection</h2><blockquote><pre>int sqlite3_close(sqlite3 *);

1883

</pre></blockquote><p>

1884

The sqlite3_close() routine is the destructor for the <a href="#sqlite3">sqlite3</a> object.

1885

Calls to sqlite3_close() return SQLITE_OK if the <a href="#sqlite3">sqlite3</a> object is

1886

successfully destroyed and all associated resources are deallocated.</p>

1887

1888

<p>Applications must <a href="#sqlite3_finalize">finalize</a> all <a href="#sqlite3_stmt">prepared statements</a>

1889

and <a href="#sqlite3_blob_close">close</a> all <a href="#sqlite3_blob">BLOB handles</a> associated with

1890

the <a href="#sqlite3">sqlite3</a> object prior to attempting to close the object. If

1891

sqlite3_close() is called on a <a href="#sqlite3">database connection</a> that still has

1892

outstanding <a href="#sqlite3_stmt">prepared statements</a> or <a href="#sqlite3_blob">BLOB handles</a>, then it returns

1893

SQLITE_BUSY.</p>

1894

1895

<p>If <a href="#sqlite3_close">sqlite3_close()</a> is invoked while a transaction is open,

1896

the transaction is automatically rolled back.</p>

1897

1898

<p>The C parameter to <a href="#sqlite3_close">sqlite3_close(C)</a> must be either a NULL

1899

pointer or an <a href="#sqlite3">sqlite3</a> object pointer obtained

1900

from <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, or

1901

<a href="#sqlite3_open">sqlite3_open_v2()</a>, and not previously closed.

1902

Calling sqlite3_close() with a NULL pointer argument is a

1903

harmless no-op.

1904

</p><hr><a name="sqlite3_column_count"></a>

1905

<h2>Number Of Columns In A Result Set</h2><blockquote><pre>int sqlite3_column_count(sqlite3_stmt *pStmt);

1906

</pre></blockquote><p>

1907

Return the number of columns in the result set returned by the

1908

<a href="#sqlite3_stmt">prepared statement</a>. This routine returns 0 if pStmt is an SQL

1909

statement that does not return data (for example an <a href="lang_update.html">UPDATE</a>).</p>

1910

1911

<p>See also: <a href="#sqlite3_data_count">sqlite3_data_count()</a>

1912

</p><hr><a name="sqlite3_config"></a>

1913

<h2>Configuring The SQLite Library</h2><blockquote><pre>int sqlite3_config(int, ...);

1914

</pre></blockquote><p>

1915

The sqlite3_config() interface is used to make global configuration

1916

changes to SQLite in order to tune SQLite to the specific needs of

1917

the application. The default configuration is recommended for most

1918

applications and so this routine is usually not necessary. It is

1919

provided to support rare applications with unusual needs.</p>

1920

1921

<p>The sqlite3_config() interface is not threadsafe. The application

1922

must insure that no other SQLite interfaces are invoked by other

1923

threads while sqlite3_config() is running. Furthermore, sqlite3_config()

1924

may only be invoked prior to library initialization using

1925

<a href="#sqlite3_initialize">sqlite3_initialize()</a> or after shutdown by <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.

1926

If sqlite3_config() is called after <a href="#sqlite3_initialize">sqlite3_initialize()</a> and before

1927

<a href="#sqlite3_initialize">sqlite3_shutdown()</a> then it will return SQLITE_MISUSE.

1928

Note, however, that sqlite3_config() can be called as part of the

1929

implementation of an application-defined <a href="#sqlite3_initialize">sqlite3_os_init()</a>.</p>

1930

1931

<p>The first argument to sqlite3_config() is an integer

1932

<a href="#SQLITE_CONFIG_GETMALLOC">configuration option</a> that determines

1933

what property of SQLite is to be configured. Subsequent arguments

1934

vary depending on the <a href="#SQLITE_CONFIG_GETMALLOC">configuration option</a>

1935

in the first argument.</p>

1936

1937

<p>When a configuration option is set, sqlite3_config() returns <a href="#SQLITE_ABORT">SQLITE_OK</a>.

1938

If the option is unknown or SQLite is unable to set the option

1939

then this routine returns a non-zero <a href="#SQLITE_ABORT">error code</a>.

1940

</p><hr><a name="sqlite3_context_db_handle"></a>

1941

<h2>Database Connection For Functions</h2><blockquote><pre>sqlite3 *sqlite3_context_db_handle(sqlite3_context*);

1942

</pre></blockquote><p>

1943

The sqlite3_context_db_handle() interface returns a copy of

1944

the pointer to the <a href="#sqlite3">database connection</a> (the 1st parameter)

1945

of the <a href="#sqlite3_create_function">sqlite3_create_function()</a>

1946

and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> routines that originally

1947

registered the application defined function.

1948

</p><hr><a name="sqlite3_data_count"></a>

1949

<h2>Number of columns in a result set</h2><blockquote><pre>int sqlite3_data_count(sqlite3_stmt *pStmt);

1950

</pre></blockquote><p>

1951

The sqlite3_data_count(P) interface returns the number of columns in the

1952

current row of the result set of <a href="#sqlite3_stmt">prepared statement</a> P.

1953

If prepared statement P does not have results ready to return

1954

(via calls to the <a href="#sqlite3_column_blob">sqlite3_column_*()</a> of

1955

interfaces) then sqlite3_data_count(P) returns 0.

1956

The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.

1957

The sqlite3_data_count(P) routine returns 0 if the previous call to

1958

<a href="#sqlite3_step">sqlite3_step</a>(P) returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>. The sqlite3_data_count(P)

1959

will return non-zero if previous call to <a href="#sqlite3_step">sqlite3_step</a>(P) returned

1960

<a href="#SQLITE_ABORT">SQLITE_ROW</a>, except in the case of the <a href="pragma.html#pragma_incremental_vacuum">PRAGMA incremental_vacuum</a>

1961

where it always returns zero since each step of that multi-step

1962

pragma returns 0 columns of data.</p>

1963

1964

<p>See also: <a href="#sqlite3_column_count">sqlite3_column_count()</a>

1965

</p><hr><a name="sqlite3_db_config"></a>

1966

<h2>Configure database connections</h2><blockquote><pre>int sqlite3_db_config(sqlite3*, int op, ...);

1967

</pre></blockquote><p>

1968

The sqlite3_db_config() interface is used to make configuration

1969

changes to a <a href="#sqlite3">database connection</a>. The interface is similar to

1970

<a href="#sqlite3_config">sqlite3_config()</a> except that the changes apply to a single

1971

<a href="#sqlite3">database connection</a> (specified in the first argument).</p>

1972

1973

<p>The second argument to sqlite3_db_config(D,V,...) is the

1974

<a href="#SQLITE_DBCONFIG_ENABLE_FKEY">configuration verb</a> - an integer code

1975

that indicates what aspect of the <a href="#sqlite3">database connection</a> is being configured.

1976

Subsequent arguments vary depending on the configuration verb.</p>

1977

1978

<p>Calls to sqlite3_db_config() return SQLITE_OK if and only if

1979

the call is considered successful.

1980

</p><hr><a name="sqlite3_db_filename"></a>

1981

<h2>Return The Filename For A Database Connection</h2><blockquote><pre>const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);

1982

</pre></blockquote><p>

1983

The sqlite3_db_filename(D,N) interface returns a pointer to a filename

1984

associated with database N of connection D. The main database file

1985

has the name "main". If there is no attached database N on the database

1986

connection D, or if database N is a temporary or in-memory database, then

1987

a NULL pointer is returned.</p>

1988

1989

<p>The filename returned by this function is the output of the

1990

xFullPathname method of the <a href="vfs.html">VFS</a>. In other words, the filename

1991

will be an absolute pathname, even if the filename used

1992

to open the database originally was a URI or relative pathname.

1993

</p><hr><a name="sqlite3_db_handle"></a>

1994

<h2>Find The Database Handle Of A Prepared Statement</h2><blockquote><pre>sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

1995

</pre></blockquote><p>

1996

The sqlite3_db_handle interface returns the <a href="#sqlite3">database connection</a> handle

1997

to which a <a href="#sqlite3_stmt">prepared statement</a> belongs. The <a href="#sqlite3">database connection</a>

1998

returned by sqlite3_db_handle is the same <a href="#sqlite3">database connection</a>

1999

that was the first argument

2000

to the <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> call (or its variants) that was used to

2001

create the statement in the first place.

2002

</p><hr><a name="sqlite3_db_mutex"></a>

2003

<h2>Retrieve the mutex for a database connection</h2><blockquote><pre>sqlite3_mutex *sqlite3_db_mutex(sqlite3*);

2004

</pre></blockquote><p>

2005

This interface returns a pointer the <a href="#sqlite3_mutex">sqlite3_mutex</a> object that

2006

serializes access to the <a href="#sqlite3">database connection</a> given in the argument

2007

when the <a href="threadsafe.html">threading mode</a> is Serialized.

2008

If the <a href="threadsafe.html">threading mode</a> is Single-thread or Multi-thread then this

2009

routine returns a NULL pointer.

2010

</p><hr><a name="sqlite3_db_readonly"></a>

2011

<h2>Determine if a database is read-only</h2><blockquote><pre>int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);

2012

</pre></blockquote><p>

2013

The sqlite3_db_readonly(D,N) interface returns 1 if the database N

2014

of connection D is read-only, 0 if it is read/write, or -1 if N is not

2015

the name of a database on connection D.

2016

</p><hr><a name="sqlite3_db_release_memory"></a>

2017

<h2>Free Memory Used By A Database Connection</h2><blockquote><pre>int sqlite3_db_release_memory(sqlite3*);

2018

</pre></blockquote><p>

2019

The sqlite3_db_release_memory(D) interface attempts to free as much heap

2020

memory as possible from database connection D. Unlike the

2021

<a href="#sqlite3_release_memory">sqlite3_release_memory()</a> interface, this interface is effect even

2022

when then <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a> compile-time option is

2023

omitted.</p>

2024

2025

<p>See also: <a href="#sqlite3_release_memory">sqlite3_release_memory()</a>

2026

</p><hr><a name="sqlite3_db_status"></a>

2027

<h2>Database Connection Status</h2><blockquote><pre>int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);

2028

</pre></blockquote><p>

2029

This interface is used to retrieve runtime status information

2030

about a single <a href="#sqlite3">database connection</a>. The first argument is the

2031

database connection object to be interrogated. The second argument

2032

is an integer constant, taken from the set of

2033

<a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS options</a>, that

2034

determines the parameter to interrogate. The set of

2035

<a href="#SQLITE_DBSTATUS options">SQLITE_DBSTATUS options</a> is likely

2036

to grow in future releases of SQLite.</p>

2037

2038

<p>The current value of the requested parameter is written into *pCur

2039

and the highest instantaneous value is written into *pHiwtr. If

2040

the resetFlg is true, then the highest instantaneous value is

2041

reset back down to the current value.</p>

2042

2043

<p>The sqlite3_db_status() routine returns SQLITE_OK on success and a

2044

non-zero <a href="#SQLITE_ABORT">error code</a> on failure.</p>

2045

2046

<p>See also: <a href="#sqlite3_status">sqlite3_status()</a> and <a href="#sqlite3_stmt_status">sqlite3_stmt_status()</a>.

2047

</p><hr><a name="sqlite3_declare_vtab"></a>

2048

<h2>Declare The Schema Of A Virtual Table</h2><blockquote><pre>int sqlite3_declare_vtab(sqlite3*, const char *zSQL);

2049

</pre></blockquote><p>

2050

The <a href="vtab.html#xcreate">xCreate</a> and <a href="vtab.html#xconnect">xConnect</a> methods of a

2051

<a href="#sqlite3_module">virtual table module</a> call this interface

2052

to declare the format (the names and datatypes of the columns) of

2053

the virtual tables they implement.

2054

</p><hr><a name="sqlite3_enable_load_extension"></a>

2055

<h2>Enable Or Disable Extension Loading</h2><blockquote><pre>int sqlite3_enable_load_extension(sqlite3 *db, int onoff);

2056

</pre></blockquote><p>

2057

So as not to open security holes in older applications that are

2058

unprepared to deal with extension loading, and as a means of disabling

2059

extension loading while evaluating user-entered SQL, the following API

2060

is provided to turn the <a href="#sqlite3_load_extension">sqlite3_load_extension()</a> mechanism on and off.</p>

2061

2062

<p>Extension loading is off by default. See ticket #1863.

2063

Call the sqlite3_enable_load_extension() routine with onoff==1

2064

to turn extension loading on and call it with onoff==0 to turn

2065

it back off again.

2066

</p><hr><a name="sqlite3_enable_shared_cache"></a>

2067

<h2>Enable Or Disable Shared Pager Cache</h2><blockquote><pre>int sqlite3_enable_shared_cache(int);

2068

</pre></blockquote><p>

2069

This routine enables or disables the sharing of the database cache

2070

and schema data structures between <a href="#sqlite3">connections</a>

2071

to the same database. Sharing is enabled if the argument is true

2072

and disabled if the argument is false.</p>

2073

2074

<p>Cache sharing is enabled and disabled for an entire process.

2075

This is a change as of SQLite version 3.5.0. In prior versions of SQLite,

2076

sharing was enabled or disabled for each thread separately.</p>

2077

2078

<p>The cache sharing mode set by this interface effects all subsequent

2079

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>.

2080

Existing database connections continue use the sharing mode

2081

that was in effect at the time they were opened.</p>

2082

2083

<p>This routine returns <a href="#SQLITE_ABORT">SQLITE_OK</a> if shared cache was enabled or disabled

2084

successfully. An <a href="#SQLITE_ABORT">error code</a> is returned otherwise.</p>

2085

2086

<p>Shared cache is disabled by default. But this might change in

2087

future releases of SQLite. Applications that care about shared

2088

cache setting should set it explicitly.</p>

2089

2090

<p>See Also: <a href="sharedcache.html">SQLite Shared-Cache Mode</a>

2091

</p><hr><a name="sqlite3_exec"></a>

2092

<h2>One-Step Query Execution Interface</h2><blockquote><pre>int sqlite3_exec(

2093

sqlite3*, /* An open database */

2094

const char *sql, /* SQL to be evaluated */

2095

int (*callback)(void*,int,char**,char**), /* Callback function */

2096

void *, /* 1st argument to callback */

2097

char **errmsg /* Error msg written here */

2098

);

2099

</pre></blockquote><p>

2100

The sqlite3_exec() interface is a convenience wrapper around

2101

<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_step">sqlite3_step()</a>, and <a href="#sqlite3_finalize">sqlite3_finalize()</a>,

2102

that allows an application to run multiple statements of SQL

2103

without having to use a lot of C code.</p>

2104

2105

<p>The sqlite3_exec() interface runs zero or more UTF-8 encoded,

2106

semicolon-separate SQL statements passed into its 2nd argument,

2107

in the context of the <a href="#sqlite3">database connection</a> passed in as its 1st

2108

argument. If the callback function of the 3rd argument to

2109

sqlite3_exec() is not NULL, then it is invoked for each result row

2110

coming out of the evaluated SQL statements. The 4th argument to

2111

sqlite3_exec() is relayed through to the 1st argument of each

2112

callback invocation. If the callback pointer to sqlite3_exec()

2113

is NULL, then no callback is ever invoked and result rows are

2114

ignored.</p>

2115

2116

<p>If an error occurs while evaluating the SQL statements passed into

2117

sqlite3_exec(), then execution of the current statement stops and

2118

subsequent statements are skipped. If the 5th parameter to sqlite3_exec()

2119

is not NULL then any error message is written into memory obtained

2120

from <a href="#sqlite3_free">sqlite3_malloc()</a> and passed back through the 5th parameter.

2121

To avoid memory leaks, the application should invoke <a href="#sqlite3_free">sqlite3_free()</a>

2122

on error message strings returned through the 5th parameter of

2123

of sqlite3_exec() after the error message string is no longer needed.

2124

If the 5th parameter to sqlite3_exec() is not NULL and no errors

2125

occur, then sqlite3_exec() sets the pointer in its 5th parameter to

2126

NULL before returning.</p>

2127

2128

<p>If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()

2129

routine returns SQLITE_ABORT without invoking the callback again and

2130

without running any subsequent SQL statements.</p>

2131

2132

<p>The 2nd argument to the sqlite3_exec() callback function is the

2133

number of columns in the result. The 3rd argument to the sqlite3_exec()

2134

callback is an array of pointers to strings obtained as if from

2135

<a href="#sqlite3_column_blob">sqlite3_column_text()</a>, one for each column. If an element of a

2136

result row is NULL then the corresponding string pointer for the

2137

sqlite3_exec() callback is a NULL pointer. The 4th argument to the

2138

sqlite3_exec() callback is an array of pointers to strings where each

2139

entry represents the name of corresponding result column as obtained

2140

from <a href="#sqlite3_column_name">sqlite3_column_name()</a>.</p>

2141

2142

<p>If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer

2143

to an empty string, or a pointer that contains only whitespace and/or

2144

SQL comments, then no SQL statements are evaluated and the database

2145

is not changed.</p>

2146

2147

<p>Restrictions:</p>

2148

2149

<p><ul>

2150

<li> The application must insure that the 1st parameter to sqlite3_exec()

2151

is a valid and open <a href="#sqlite3">database connection</a>.

2152

<li> The application must not close <a href="#sqlite3">database connection</a> specified by

2153

the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.

2154

<li> The application must not modify the SQL statement text passed into

2155

the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.

2156

</ul>

2157

</p><hr><a name="sqlite3_extended_result_codes"></a>

2158

<h2>Enable Or Disable Extended Result Codes</h2><blockquote><pre>int sqlite3_extended_result_codes(sqlite3*, int onoff);

2159

</pre></blockquote><p>

2160

The sqlite3_extended_result_codes() routine enables or disables the

2161

<a href="#SQLITE_ABORT_ROLLBACK">extended result codes</a> feature of SQLite. The extended result

2162

codes are disabled by default for historical compatibility.

2163

</p><hr><a name="sqlite3_file_control"></a>

2164

<h2>Low-Level Control Of Database Files</h2><blockquote><pre>int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);

2165

</pre></blockquote><p>

2166

The <a href="#sqlite3_file_control">sqlite3_file_control()</a> interface makes a direct call to the

2167

xFileControl method for the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object associated

2168

with a particular database identified by the second argument. The

2169

name of the database is "main" for the main database or "temp" for the

2170

TEMP database, or the name that appears after the AS keyword for

2171

databases that are added using the <a href="lang_attach.html">ATTACH</a> SQL command.

2172

A NULL pointer can be used in place of "main" to refer to the

2173

main database file.

2174

The third and fourth parameters to this routine

2175

are passed directly through to the second and third parameters of

2176

the xFileControl method. The return value of the xFileControl

2177

method becomes the return value of this routine.</p>

2178

2179

<p>The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes

2180

a pointer to the underlying <a href="#sqlite3_file">sqlite3_file</a> object to be written into

2181

the space pointed to by the 4th parameter. The SQLITE_FCNTL_FILE_POINTER

2182

case is a short-circuit path which does not actually invoke the

2183

underlying sqlite3_io_methods.xFileControl method.</p>

2184

2185

<p>If the second parameter (zDbName) does not match the name of any

2186

open database file, then SQLITE_ERROR is returned. This error

2187

code is not remembered and will not be recalled by <a href="#sqlite3_errcode">sqlite3_errcode()</a>

2188

or <a href="#sqlite3_errcode">sqlite3_errmsg()</a>. The underlying xFileControl method might

2189

also return SQLITE_ERROR. There is no way to distinguish between

2190

an incorrect zDbName and an SQLITE_ERROR return from the underlying

2191

xFileControl method.</p>

2192

2193

<p>See also: <a href="#SQLITE_FCNTL_CHUNK_SIZE">SQLITE_FCNTL_LOCKSTATE</a>

2194

</p><hr><a name="sqlite3_finalize"></a>

2195

<h2>Destroy A Prepared Statement Object</h2><blockquote><pre>int sqlite3_finalize(sqlite3_stmt *pStmt);

2196

</pre></blockquote><p>

2197

The sqlite3_finalize() function is called to delete a <a href="#sqlite3_stmt">prepared statement</a>.

2198

If the most recent evaluation of the statement encountered no errors

2199

or if the statement is never been evaluated, then sqlite3_finalize() returns

2200

SQLITE_OK. If the most recent evaluation of statement S failed, then

2201

sqlite3_finalize(S) returns the appropriate <a href="#SQLITE_ABORT">error code</a> or

2202

<a href="#SQLITE_ABORT_ROLLBACK">extended error code</a>.</p>

2203

2204

<p>The sqlite3_finalize(S) routine can be called at any point during

2205

the life cycle of <a href="#sqlite3_stmt">prepared statement</a> S:

2206

before statement S is ever evaluated, after

2207

one or more calls to <a href="#sqlite3_reset">sqlite3_reset()</a>, or after any call

2208

to <a href="#sqlite3_step">sqlite3_step()</a> regardless of whether or not the statement has

2209

completed execution.</p>

2210

2211

<p>Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.</p>

2212

2213

<p>The application must finalize every <a href="#sqlite3_stmt">prepared statement</a> in order to avoid

2214

resource leaks. It is a grievous error for the application to try to use

2215

a prepared statement after it has been finalized. Any use of a prepared

2216

statement after it has been finalized can result in undefined and

2217

undesirable behavior such as segfaults and heap corruption.

2218

</p><hr><a name="sqlite3_interrupt"></a>

2219

<h2>Interrupt A Long-Running Query</h2><blockquote><pre>void sqlite3_interrupt(sqlite3*);

2220

</pre></blockquote><p>

2221

This function causes any pending database operation to abort and

2222

return at its earliest opportunity. This routine is typically

2223

called in response to a user action such as pressing "Cancel"

2224

or Ctrl-C where the user wants a long query operation to halt

2225

immediately.</p>

2226

2227

<p>It is safe to call this routine from a thread different from the

2228

thread that is currently running the database operation. But it

2229

is not safe to call this routine with a <a href="#sqlite3">database connection</a> that

2230

is closed or might close before sqlite3_interrupt() returns.</p>

2231

2232

<p>If an SQL operation is very nearly finished at the time when

2233

sqlite3_interrupt() is called, then it might not have an opportunity

2234

to be interrupted and might continue to completion.</p>

2235

2236

<p>An SQL operation that is interrupted will return <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>.

2237

If the interrupted SQL operation is an INSERT, UPDATE, or DELETE

2238

that is inside an explicit transaction, then the entire transaction

2239

will be rolled back automatically.</p>

2240

2241

<p>The sqlite3_interrupt(D) call is in effect until all currently running

2242

SQL statements on <a href="#sqlite3">database connection</a> D complete. Any new SQL statements

2243

that are started after the sqlite3_interrupt() call and before the

2244

running statements reaches zero are interrupted as if they had been

2245

running prior to the sqlite3_interrupt() call. New SQL statements

2246

that are started after the running statement count reaches zero are

2247

not effected by the sqlite3_interrupt().

2248

A call to sqlite3_interrupt(D) that occurs when there are no running

2249

SQL statements is a no-op and has no effect on SQL statements

2250

that are started after the sqlite3_interrupt() call returns.</p>

2251

2252

<p>If the database connection closes while <a href="#sqlite3_interrupt">sqlite3_interrupt()</a>

2253

is running then bad things will likely happen.

2254

</p><hr><a name="sqlite3_last_insert_rowid"></a>

2255

<h2>Last Insert Rowid</h2><blockquote><pre>sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);

2256

</pre></blockquote><p>

2257

Each entry in an SQLite table has a unique 64-bit signed

2258

integer key called the <a href="lang_createtable.html#rowid">"rowid"</a>. The rowid is always available

2259

as an undeclared column named ROWID, OID, or _ROWID_ as long as those

2260

names are not also used by explicitly declared columns. If

2261

the table has a column of type <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> then that column

2262

is another alias for the rowid.</p>

2263

2264

<p>This routine returns the <a href="lang_createtable.html#rowid">rowid</a> of the most recent

2265

successful <a href="lang_insert.html">INSERT</a> into the database from the <a href="#sqlite3">database connection</a>

2266

in the first argument. As of SQLite version 3.7.7, this routines

2267

records the last insert rowid of both ordinary tables and <a href="vtab.html">virtual tables</a>.

2268

If no successful <a href="lang_insert.html">INSERT</a>s

2269

have ever occurred on that database connection, zero is returned.</p>

2270

2271

<p>If an <a href="lang_insert.html">INSERT</a> occurs within a trigger or within a <a href="vtab.html">virtual table</a>

2272

method, then this routine will return the <a href="lang_createtable.html#rowid">rowid</a> of the inserted

2273

row as long as the trigger or virtual table method is running.

2274

But once the trigger or virtual table method ends, the value returned

2275

by this routine reverts to what it was before the trigger or virtual

2276

table method began.</p>

2277

2278

<p>An <a href="lang_insert.html">INSERT</a> that fails due to a constraint violation is not a

2279

successful <a href="lang_insert.html">INSERT</a> and does not change the value returned by this

2280

routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,

2281

and INSERT OR ABORT make no changes to the return value of this

2282

routine when their insertion fails. When INSERT OR REPLACE

2283

encounters a constraint violation, it does not fail. The

2284

INSERT continues to completion after deleting rows that caused

2285

the constraint problem so INSERT OR REPLACE will always change

2286

the return value of this interface.</p>

2287

2288

<p>For the purposes of this routine, an <a href="lang_insert.html">INSERT</a> is considered to

2289

be successful even if it is subsequently rolled back.</p>

2290

2291

<p>This function is accessible to SQL statements via the

2292

<a href="lang_corefunc.html#last_insert_rowid">last_insert_rowid() SQL function</a>.</p>

2293

2294

<p>If a separate thread performs a new <a href="lang_insert.html">INSERT</a> on the same

2295

database connection while the <a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid()</a>

2296

function is running and thus changes the last insert <a href="lang_createtable.html#rowid">rowid</a>,

2297

then the value returned by <a href="#sqlite3_last_insert_rowid">sqlite3_last_insert_rowid()</a> is

2298

unpredictable and might not equal either the old or the new

2299

last insert <a href="lang_createtable.html#rowid">rowid</a>.

2300

</p><hr><a name="sqlite3_limit"></a>

2301

<h2>Run-time Limits</h2><blockquote><pre>int sqlite3_limit(sqlite3*, int id, int newVal);

2302

</pre></blockquote><p>

2303

This interface allows the size of various constructs to be limited

2304

on a connection by connection basis. The first parameter is the

2305

<a href="#sqlite3">database connection</a> whose limit is to be set or queried. The

2306

second parameter is one of the <a href="#SQLITE_LIMIT_ATTACHED">limit categories</a> that define a

2307

class of constructs to be size limited. The third parameter is the

2308

new limit for that construct.</p>

2309

2310

<p>If the new limit is a negative number, the limit is unchanged.

2311

For each limit category SQLITE_LIMIT_<i>NAME</i> there is a

2312

<a href="limits.html">hard upper bound</a>

2313

set at compile-time by a C preprocessor macro called

2314

<a href="limits.html">SQLITE_MAX_<i>NAME</i></a>.

2315

(The "_LIMIT_" in the name is changed to "_MAX_".)

2316

Attempts to increase a limit above its hard upper bound are

2317

silently truncated to the hard upper bound.</p>

2318

2319

<p>Regardless of whether or not the limit was changed, the

2320

<a href="#sqlite3_limit">sqlite3_limit()</a> interface returns the prior value of the limit.

2321

Hence, to find the current value of a limit without changing it,

2322

simply invoke this interface with the third parameter set to -1.</p>

2323

2324

<p>Run-time limits are intended for use in applications that manage

2325

both their own internal database and also databases that are controlled

2326

by untrusted external sources. An example application might be a

2327

web browser that has its own databases for storing history and

2328

separate databases controlled by JavaScript applications downloaded

2329

off the Internet. The internal databases can be given the

2330

large, default limits. Databases managed by external sources can

2331

be given much smaller limits designed to prevent a denial of service

2332

attack. Developers might also want to use the <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a>

2333

interface to further control untrusted SQL. The size of the database

2334

created by an untrusted script can be contained using the

2335

<a href="pragma.html#pragma_max_page_count">max_page_count</a> <a href="pragma.html#syntax">PRAGMA</a>.</p>

2336

2337

<p>New run-time limit categories may be added in future releases.

2338

</p><hr><a name="sqlite3_load_extension"></a>

2339

<h2>Load An Extension</h2><blockquote><pre>int sqlite3_load_extension(

2340

sqlite3 *db, /* Load the extension into this database connection */

2341

const char *zFile, /* Name of the shared library containing extension */

2342

const char *zProc, /* Entry point. Derived from zFile if 0 */

2343

char **pzErrMsg /* Put error message here if not 0 */

2344

);

2345

</pre></blockquote><p>

2346

This interface loads an SQLite extension library from the named file.</p>

2347

2348

<p>The sqlite3_load_extension() interface attempts to load an

2349

SQLite extension library contained in the file zFile.</p>

2350

2351

<p>The entry point is zProc.

2352

zProc may be 0, in which case the name of the entry point

2353

defaults to "sqlite3_extension_init".

2354

The sqlite3_load_extension() interface returns

2355

<a href="#SQLITE_ABORT">SQLITE_OK</a> on success and <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if something goes wrong.

2356

If an error occurs and pzErrMsg is not 0, then the

2357

<a href="#sqlite3_load_extension">sqlite3_load_extension()</a> interface shall attempt to

2358

fill *pzErrMsg with error message text stored in memory

2359

obtained from <a href="#sqlite3_free">sqlite3_malloc()</a>. The calling function

2360

should free this memory by calling <a href="#sqlite3_free">sqlite3_free()</a>.</p>

2361

2362

<p>Extension loading must be enabled using

2363

<a href="#sqlite3_enable_load_extension">sqlite3_enable_load_extension()</a> prior to calling this API,

2364

otherwise an error will be returned.</p>

2365

2366

<p>See also the <a href="lang_corefunc.html#load_extension">load_extension() SQL function</a>.

2367

</p><hr><a name="sqlite3_log"></a>

2368

<h2>Error Logging Interface</h2><blockquote><pre>void sqlite3_log(int iErrCode, const char *zFormat, ...);

2369

</pre></blockquote><p>

2370

The <a href="#sqlite3_log">sqlite3_log()</a> interface writes a message into the error log

2371

established by the <a href="#sqliteconfiglog">SQLITE_CONFIG_LOG</a> option to <a href="#sqlite3_config">sqlite3_config()</a>.

2372

If logging is enabled, the zFormat string and subsequent arguments are

2373

used with <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to generate the final output string.</p>

2374

2375

<p>The sqlite3_log() interface is intended for use by extensions such as

2376

virtual tables, collating functions, and SQL functions. While there is

2377

nothing to prevent an application from calling sqlite3_log(), doing so

2378

is considered bad form.</p>

2379

2380

<p>The zFormat string must not be NULL.</p>

2381

2382

<p>To avoid deadlocks and other threading problems, the sqlite3_log() routine

2383

will not use dynamically allocated memory. The log message is stored in

2384

a fixed-length buffer on the stack. If the log message is longer than

2385

a few hundred characters, it will be truncated to the length of the

2386

buffer.

2387

</p><hr><a name="sqlite3_next_stmt"></a>

2388

<h2>Find the next prepared statement</h2><blockquote><pre>sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);

2389

</pre></blockquote><p>

2390

This interface returns a pointer to the next <a href="#sqlite3_stmt">prepared statement</a> after

2391

pStmt associated with the <a href="#sqlite3">database connection</a> pDb. If pStmt is NULL

2392

then this interface returns a pointer to the first prepared statement

2393

associated with the database connection pDb. If no prepared statement

2394

satisfies the conditions of this routine, it returns NULL.</p>

2395

2396

<p>The <a href="#sqlite3">database connection</a> pointer D in a call to

2397

<a href="#sqlite3_next_stmt">sqlite3_next_stmt(D,S)</a> must refer to an open database

2398

connection and in particular must not be a NULL pointer.

2399

</p><hr><a name="sqlite3_overload_function"></a>

2400

<h2>Overload A Function For A Virtual Table</h2><blockquote><pre>int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);

2401

</pre></blockquote><p>

2402

Virtual tables can provide alternative implementations of functions

2403

using the <a href="vtab.html#xfindfunction">xFindFunction</a> method of the <a href="#sqlite3_module">virtual table module</a>.

2404

But global versions of those functions

2405

must exist in order to be overloaded.</p>

2406

2407

<p>This API makes sure a global version of a function with a particular

2408

name and number of parameters exists. If no such function exists

2409

before this API is called, a new function is created. The implementation

2410

of the new function always causes an exception to be thrown. So

2411

the new function is not good for anything by itself. Its only

2412

purpose is to be a placeholder function that can be overloaded

2413

by a <a href="vtab.html">virtual table</a>.

2414

</p><hr><a name="sqlite3_progress_handler"></a>

2415

<h2>Query Progress Callbacks</h2><blockquote><pre>void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

2416

</pre></blockquote><p>

2417

The sqlite3_progress_handler(D,N,X,P) interface causes the callback

2418

function X to be invoked periodically during long running calls to

2419

<a href="#sqlite3_exec">sqlite3_exec()</a>, <a href="#sqlite3_step">sqlite3_step()</a> and <a href="#sqlite3_free_table">sqlite3_get_table()</a> for

2420

database connection D. An example use for this

2421

interface is to keep a GUI updated during a large query.</p>

2422

2423

<p>The parameter P is passed through as the only parameter to the

2424

callback function X. The parameter N is the number of

2425

<a href="opcode.html">virtual machine instructions</a> that are evaluated between successive

2426

invocations of the callback X.</p>

2427

2428

<p>Only a single progress handler may be defined at one time per

2429

<a href="#sqlite3">database connection</a>; setting a new progress handler cancels the

2430

old one. Setting parameter X to NULL disables the progress handler.

2431

The progress handler is also disabled by setting N to a value less

2432

than 1.</p>

2433

2434

<p>If the progress callback returns non-zero, the operation is

2435

interrupted. This feature can be used to implement a

2436

"Cancel" button on a GUI progress dialog box.</p>

2437

2438

<p>The progress handler callback must not do anything that will modify

2439

the database connection that invoked the progress handler.

2440

Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their

2441

database connections for the meaning of "modify" in this paragraph.</p>

2442

2443

2444

<h2>Pseudo-Random Number Generator</h2><blockquote><pre>void sqlite3_randomness(int N, void *P);

2445

</pre></blockquote><p>

2446

SQLite contains a high-quality pseudo-random number generator (PRNG) used to

2447

select random <a href="lang_createtable.html#rowid">ROWIDs</a> when inserting new records into a table that

2448

already uses the largest possible <a href="lang_createtable.html#rowid">ROWID</a>. The PRNG is also used for

2449

the build-in random() and randomblob() SQL functions. This interface allows

2450

applications to access the same PRNG for other purposes.</p>

2451

2452

<p>A call to this routine stores N bytes of randomness into buffer P.</p>

2453

2454

<p>The first time this routine is invoked (either internally or by

2455

the application) the PRNG is seeded using randomness obtained

2456

from the xRandomness method of the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object.

2457

On all subsequent invocations, the pseudo-randomness is generated

2458

internally and without recourse to the <a href="#sqlite3_vfs">sqlite3_vfs</a> xRandomness

2459

method.

2460

</p><hr><a name="sqlite3_release_memory"></a>

2461

<h2>Attempt To Free Heap Memory</h2><blockquote><pre>int sqlite3_release_memory(int);

2462

</pre></blockquote><p>

2463

The sqlite3_release_memory() interface attempts to free N bytes

2464

of heap memory by deallocating non-essential memory allocations

2465

held by the database library. Memory used to cache database

2466

pages to improve performance is an example of non-essential memory.

2467

sqlite3_release_memory() returns the number of bytes actually freed,

2468

which might be more or less than the amount requested.

2469

The sqlite3_release_memory() routine is a no-op returning zero

2470

if SQLite is not compiled with <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>.</p>

2471

2472

<p>See also: <a href="#sqlite3_db_release_memory">sqlite3_db_release_memory()</a>

2473

</p><hr><a name="sqlite3_reset"></a>

2474

<h2>Reset A Prepared Statement Object</h2><blockquote><pre>int sqlite3_reset(sqlite3_stmt *pStmt);

2475

</pre></blockquote><p>

2476

The sqlite3_reset() function is called to reset a <a href="#sqlite3_stmt">prepared statement</a>

2477

object back to its initial state, ready to be re-executed.

2478

Any SQL statement variables that had values bound to them using

2479

the <a href="#sqlite3_bind_blob">sqlite3_bind_*() API</a> retain their values.

2480

Use <a href="#sqlite3_clear_bindings">sqlite3_clear_bindings()</a> to reset the bindings.</p>

2481

2482

<p>The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface resets the <a href="#sqlite3_stmt">prepared statement</a> S

2483

back to the beginning of its program.</p>

2484

2485

<p>If the most recent call to <a href="#sqlite3_step">sqlite3_step(S)</a> for the

2486

<a href="#sqlite3_stmt">prepared statement</a> S returned <a href="#SQLITE_ABORT">SQLITE_ROW</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>,

2487

or if <a href="#sqlite3_step">sqlite3_step(S)</a> has never before been called on S,

2488

then <a href="#sqlite3_reset">sqlite3_reset(S)</a> returns <a href="#SQLITE_ABORT">SQLITE_OK</a>.</p>

2489

2490

<p>If the most recent call to <a href="#sqlite3_step">sqlite3_step(S)</a> for the

2491

<a href="#sqlite3_stmt">prepared statement</a> S indicated an error, then

2492

<a href="#sqlite3_reset">sqlite3_reset(S)</a> returns an appropriate <a href="#SQLITE_ABORT">error code</a>.</p>

2493

2494

<p>The <a href="#sqlite3_reset">sqlite3_reset(S)</a> interface does not change the values

2495

of any <a href="#sqlite3_bind_blob">bindings</a> on the <a href="#sqlite3_stmt">prepared statement</a> S.

2496

</p><hr><a name="sqlite3_reset_auto_extension"></a>

2497

<h2>Reset Automatic Extension Loading</h2><blockquote><pre>void sqlite3_reset_auto_extension(void);

2498

</pre></blockquote><p>

2499

This interface disables all automatic extensions previously

2500

registered using <a href="#sqlite3_auto_extension">sqlite3_auto_extension()</a>.

2501

</p><hr><a name="sqlite3_set_authorizer"></a>

2502

<h2>Compile-Time Authorization Callbacks</h2><blockquote><pre>int sqlite3_set_authorizer(

2503

sqlite3*,

2504

int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),

2505

void *pUserData

2506

);

2507

</pre></blockquote><p>

2508

This routine registers an authorizer callback with a particular

2509

<a href="#sqlite3">database connection</a>, supplied in the first argument.

2510

The authorizer callback is invoked as SQL statements are being compiled

2511

by <a href="#sqlite3_prepare">sqlite3_prepare()</a> or its variants <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>,

2512

<a href="#sqlite3_prepare">sqlite3_prepare16()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>. At various

2513

points during the compilation process, as logic is being created

2514

to perform various actions, the authorizer callback is invoked to

2515

see if those actions are allowed. The authorizer callback should

2516

return <a href="#SQLITE_ABORT">SQLITE_OK</a> to allow the action, <a href="#SQLITE_DENY">SQLITE_IGNORE</a> to disallow the

2517

specific action but allow the SQL statement to continue to be

2518

compiled, or <a href="#SQLITE_DENY">SQLITE_DENY</a> to cause the entire SQL statement to be

2519

rejected with an error. If the authorizer callback returns

2520

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>

2521

then the <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or equivalent call that triggered

2522

the authorizer will fail with an error message.</p>

2523

2524

<p>When the callback returns <a href="#SQLITE_ABORT">SQLITE_OK</a>, that means the operation

2525

requested is ok. When the callback returns <a href="#SQLITE_DENY">SQLITE_DENY</a>, the

2526

<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or equivalent call that triggered the

2527

authorizer will fail with an error message explaining that

2528

access is denied.</p>

2529

2530

<p>The first parameter to the authorizer callback is a copy of the third

2531

parameter to the sqlite3_set_authorizer() interface. The second parameter

2532

to the callback is an integer <a href="#SQLITE_ALTER_TABLE">action code</a> that specifies

2533

the particular action to be authorized. The third through sixth parameters

2534

to the callback are zero-terminated strings that contain additional

2535

details about the action to be authorized.</p>

2536

2537

<p>If the action code is <a href="#SQLITE_ALTER_TABLE">SQLITE_READ</a>

2538

and the callback returns <a href="#SQLITE_DENY">SQLITE_IGNORE</a> then the

2539

<a href="#sqlite3_stmt">prepared statement</a> statement is constructed to substitute

2540

a NULL value in place of the table column that would have

2541

been read if <a href="#SQLITE_ABORT">SQLITE_OK</a> had been returned. The <a href="#SQLITE_DENY">SQLITE_IGNORE</a>

2542

return can be used to deny an untrusted user access to individual

2543

columns of a table.

2544

If the action code is <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a> and the callback returns

2545

<a href="#SQLITE_DENY">SQLITE_IGNORE</a> then the <a href="lang_delete.html">DELETE</a> operation proceeds but the

2546

<a href="lang_delete.html#truncateopt">truncate optimization</a> is disabled and all rows are deleted individually.</p>

2547

2548

<p>An authorizer is used when <a href="#sqlite3_prepare">preparing</a>

2549

SQL statements from an untrusted source, to ensure that the SQL statements

2550

do not try to access data they are not allowed to see, or that they do not

2551

try to execute malicious statements that damage the database. For

2552

example, an application may allow a user to enter arbitrary

2553

SQL queries for evaluation by a database. But the application does

2554

not want the user to be able to make arbitrary changes to the

2555

database. An authorizer could then be put in place while the

2556

user-entered SQL is being <a href="#sqlite3_prepare">prepared</a> that

2557

disallows everything except <a href="lang_select.html">SELECT</a> statements.</p>

2558

2559

<p>Applications that need to process SQL from untrusted sources

2560

might also consider lowering resource limits using <a href="#sqlite3_limit">sqlite3_limit()</a>

2561

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>

2562

in addition to using an authorizer.</p>

2563

2564

<p>Only a single authorizer can be in place on a database connection

2565

at a time. Each call to sqlite3_set_authorizer overrides the

2566

previous call. Disable the authorizer by installing a NULL callback.

2567

The authorizer is disabled by default.</p>

2568

2569

<p>The authorizer callback must not do anything that will modify

2570

the database connection that invoked the authorizer callback.

2571

Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their

2572

database connections for the meaning of "modify" in this paragraph.</p>

2573

2574

<p>When <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> is used to prepare a statement, the

2575

statement might be re-prepared during <a href="#sqlite3_step">sqlite3_step()</a> due to a

2576

schema change. Hence, the application should ensure that the

2577

correct authorizer callback remains in place during the <a href="#sqlite3_step">sqlite3_step()</a>.</p>

2578

2579

<p>Note that the authorizer callback is invoked only during

2580

<a href="#sqlite3_prepare">sqlite3_prepare()</a> or its variants. Authorization is not

2581

performed during statement evaluation in <a href="#sqlite3_step">sqlite3_step()</a>, unless

2582

as stated in the previous paragraph, sqlite3_step() invokes

2583

sqlite3_prepare_v2() to reprepare a statement after a schema change.

2584

</p><hr><a name="sqlite3_sleep"></a>

2585

<h2>Suspend Execution For A Short Time</h2><blockquote><pre>int sqlite3_sleep(int);

2586

</pre></blockquote><p>

2587

The sqlite3_sleep() function causes the current thread to suspend execution

2588

for at least a number of milliseconds specified in its parameter.</p>

2589

2590

<p>If the operating system does not support sleep requests with

2591

millisecond time resolution, then the time will be rounded up to

2592

the nearest second. The number of milliseconds of sleep actually

2593

requested from the operating system is returned.</p>

2594

2595

<p>SQLite implements this interface by calling the xSleep()

2596

method of the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object. If the xSleep() method

2597

of the default VFS is not implemented correctly, or not implemented at

2598

all, then the behavior of sqlite3_sleep() may deviate from the description

2599

in the previous paragraphs.

2600

</p><hr><a name="sqlite3_soft_heap_limit"></a>

2601

<h2>Deprecated Soft Heap Limit Interface</h2><blockquote><pre>void sqlite3_soft_heap_limit(int N);

2602

</pre></blockquote><p>

2603

This is a deprecated version of the <a href="#sqlite3_soft_heap_limit64">sqlite3_soft_heap_limit64()</a>

2604

interface. This routine is provided for historical compatibility

2605

only. All new applications should use the

2606

<a href="#sqlite3_soft_heap_limit64">sqlite3_soft_heap_limit64()</a> interface rather than this one.

2607

</p><hr><a name="sqlite3_soft_heap_limit64"></a>

2608

<h2>Impose A Limit On Heap Size</h2><blockquote><pre>sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);

2609

</pre></blockquote><p>

2610

The sqlite3_soft_heap_limit64() interface sets and/or queries the

2611

soft limit on the amount of heap memory that may be allocated by SQLite.

2612

SQLite strives to keep heap memory utilization below the soft heap

2613

limit by reducing the number of pages held in the page cache

2614

as heap memory usages approaches the limit.

2615

The soft heap limit is "soft" because even though SQLite strives to stay

2616

below the limit, it will exceed the limit rather than generate

2617

an <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> error. In other words, the soft heap limit

2618

is advisory only.</p>

2619

2620

<p>The return value from sqlite3_soft_heap_limit64() is the size of

2621

the soft heap limit prior to the call, or negative in the case of an

2622

error. If the argument N is negative

2623

then no change is made to the soft heap limit. Hence, the current

2624

size of the soft heap limit can be determined by invoking

2625

sqlite3_soft_heap_limit64() with a negative argument.</p>

2626

2627

<p>If the argument N is zero then the soft heap limit is disabled.</p>

2628

2629

<p>The soft heap limit is not enforced in the current implementation

2630

if one or more of following conditions are true:</p>

2631

2632

<p><ul>

2633

<li> The soft heap limit is set to zero.

2634

<li> Memory accounting is disabled using a combination of the

2635

<a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a>,...) start-time option and

2636

the <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a> compile-time option.

2637

<li> An alternative page cache implementation is specified using

2638

<a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>,...).

2639

<li> The page cache allocates from its own memory pool supplied

2640

by <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>,...) rather than

2641

from the heap.

2642

</ul></p>

2643

2644

<p>Beginning with SQLite version 3.7.3, the soft heap limit is enforced

2645

regardless of whether or not the <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>

2646

compile-time option is invoked. With <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>,

2647

the soft heap limit is enforced on every memory allocation. Without

2648

<a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>, the soft heap limit is only enforced

2649

when memory is allocated by the page cache. Testing suggests that because

2650

the page cache is the predominate memory user in SQLite, most

2651

applications will achieve adequate soft heap limit enforcement without

2652

the use of <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>.</p>

2653

2654

<p>The circumstances under which SQLite will enforce the soft heap limit may

2655

changes in future releases of SQLite.

2656

</p><hr><a name="sqlite3_sql"></a>

2657

<h2>Retrieving Statement SQL</h2><blockquote><pre>const char *sqlite3_sql(sqlite3_stmt *pStmt);

2658

</pre></blockquote><p>

2659

This interface can be used to retrieve a saved copy of the original

2660

SQL text used to create a <a href="#sqlite3_stmt">prepared statement</a> if that statement was

2661

compiled using either <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.

2662

</p><hr><a name="sqlite3_status"></a>

2663

<h2>SQLite Runtime Status</h2><blockquote><pre>int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);

2664

</pre></blockquote><p>

2665

This interface is used to retrieve runtime status information

2666

about the performance of SQLite, and optionally to reset various

2667

highwater marks. The first argument is an integer code for

2668

the specific parameter to measure. Recognized integer codes

2669

are of the form <a href="#SQLITE_STATUS_MALLOC_COUNT">SQLITE_STATUS_...</a>.

2670

The current value of the parameter is returned into *pCurrent.

2671

The highest recorded value is returned in *pHighwater. If the

2672

resetFlag is true, then the highest record value is reset after

2673

*pHighwater is written. Some parameters do not record the highest

2674

value. For those parameters

2675

nothing is written into *pHighwater and the resetFlag is ignored.

2676

Other parameters record only the highwater mark and not the current

2677

value. For these latter parameters nothing is written into *pCurrent.</p>

2678

2679

<p>The sqlite3_status() routine returns SQLITE_OK on success and a

2680

non-zero <a href="#SQLITE_ABORT">error code</a> on failure.</p>

2681

2682

<p>This routine is threadsafe but is not atomic. This routine can be

2683

called while other threads are running the same or different SQLite

2684

interfaces. However the values returned in *pCurrent and

2685

*pHighwater reflect the status of SQLite at different points in time

2686

and it is possible that another thread might change the parameter

2687

in between the times when *pCurrent and *pHighwater are written.</p>

2688

2689

<p>See also: <a href="#sqlite3_db_status">sqlite3_db_status()</a>

2690

</p><hr><a name="sqlite3_step"></a>

2691

<h2>Evaluate An SQL Statement</h2><blockquote><pre>int sqlite3_step(sqlite3_stmt*);

2692

</pre></blockquote><p>

2693

After a <a href="#sqlite3_stmt">prepared statement</a> has been prepared using either

2694

<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or one of the legacy

2695

interfaces <a href="#sqlite3_prepare">sqlite3_prepare()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16()</a>, this function

2696

must be called one or more times to evaluate the statement.</p>

2697

2698

<p>The details of the behavior of the sqlite3_step() interface depend

2699

on whether the statement was prepared using the newer "v2" interface

2700

<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> or the older legacy

2701

interface <a href="#sqlite3_prepare">sqlite3_prepare()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16()</a>. The use of the

2702

new "v2" interface is recommended for new applications but the legacy

2703

interface will continue to be supported.</p>

2704

2705

<p>In the legacy interface, the return value will be either <a href="#SQLITE_ABORT">SQLITE_BUSY</a>,

2706

<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>.

2707

With the "v2" interface, any of the other <a href="#SQLITE_ABORT">result codes</a> or

2708

<a href="#SQLITE_ABORT_ROLLBACK">extended result codes</a> might be returned as well.</p>

2709

2710

<p><a href="#SQLITE_ABORT">SQLITE_BUSY</a> means that the database engine was unable to acquire the

2711

database locks it needs to do its job. If the statement is a <a href="lang_transaction.html">COMMIT</a>

2712

or occurs outside of an explicit transaction, then you can retry the

2713

statement. If the statement is not a <a href="lang_transaction.html">COMMIT</a> and occurs within an

2714

explicit transaction then you should rollback the transaction before

2715

continuing.</p>

2716

2717

<p><a href="#SQLITE_ABORT">SQLITE_DONE</a> means that the statement has finished executing

2718

successfully. sqlite3_step() should not be called again on this virtual

2719

machine without first calling <a href="#sqlite3_reset">sqlite3_reset()</a> to reset the virtual

2720

machine back to its initial state.</p>

2721

2722

<p>If the SQL statement being executed returns any data, then <a href="#SQLITE_ABORT">SQLITE_ROW</a>

2723

is returned each time a new row of data is ready for processing by the

2724

caller. The values may be accessed using the <a href="#sqlite3_column_blob">column access functions</a>.

2725

sqlite3_step() is called again to retrieve the next row of data.</p>

2726

2727

<p><a href="#SQLITE_ABORT">SQLITE_ERROR</a> means that a run-time error (such as a constraint

2728

violation) has occurred. sqlite3_step() should not be called again on

2729

the VM. More information may be found by calling <a href="#sqlite3_errcode">sqlite3_errmsg()</a>.

2730

With the legacy interface, a more specific error code (for example,

2731

<a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>, <a href="#SQLITE_ABORT">SQLITE_SCHEMA</a>, <a href="#SQLITE_ABORT">SQLITE_CORRUPT</a>, and so forth)

2732

can be obtained by calling <a href="#sqlite3_reset">sqlite3_reset()</a> on the

2733

<a href="#sqlite3_stmt">prepared statement</a>. In the "v2" interface,

2734

the more specific error code is returned directly by sqlite3_step().</p>

2735

2736

<p><a href="#SQLITE_ABORT">SQLITE_MISUSE</a> means that the this routine was called inappropriately.

2737

Perhaps it was called on a <a href="#sqlite3_stmt">prepared statement</a> that has

2738

already been <a href="#sqlite3_finalize">finalized</a> or on one that had

2739

previously returned <a href="#SQLITE_ABORT">SQLITE_ERROR</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>. Or it could

2740

be the case that the same database connection is being used by two or

2741

more threads at the same moment in time.</p>

2742

2743

<p>For all versions of SQLite up to and including 3.6.23.1, a call to

2744

<a href="#sqlite3_reset">sqlite3_reset()</a> was required after sqlite3_step() returned anything

2745

other than <a href="#SQLITE_ABORT">SQLITE_ROW</a> before any subsequent invocation of

2746

sqlite3_step(). Failure to reset the prepared statement using

2747

<a href="#sqlite3_reset">sqlite3_reset()</a> would result in an <a href="#SQLITE_ABORT">SQLITE_MISUSE</a> return from

2748

sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began

2749

calling <a href="#sqlite3_reset">sqlite3_reset()</a> automatically in this circumstance rather

2750

than returning <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. This is not considered a compatibility

2751

break because any application that ever receives an SQLITE_MISUSE error

2752

is broken by definition. The <a href="compile.html#omit_autoreset">SQLITE_OMIT_AUTORESET</a> compile-time option

2753

can be used to restore the legacy behavior.</p>

2754

2755

<p><b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()

2756

API always returns a generic error code, <a href="#SQLITE_ABORT">SQLITE_ERROR</a>, following any

2757

error other than <a href="#SQLITE_ABORT">SQLITE_BUSY</a> and <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. You must call

2758

<a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a> in order to find one of the

2759

specific <a href="#SQLITE_ABORT">error codes</a> that better describes the error.

2760

We admit that this is a goofy design. The problem has been fixed

2761

with the "v2" interface. If you prepare all of your SQL statements

2762

using either <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or <a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a> instead

2763

of the legacy <a href="#sqlite3_prepare">sqlite3_prepare()</a> and <a href="#sqlite3_prepare">sqlite3_prepare16()</a> interfaces,

2764

then the more specific <a href="#SQLITE_ABORT">error codes</a> are returned directly

2765

by sqlite3_step(). The use of the "v2" interface is recommended.

2766

</p><hr><a name="sqlite3_stmt_busy"></a>

2767

<h2>Determine If A Prepared Statement Has Been Reset</h2><blockquote><pre>int sqlite3_stmt_busy(sqlite3_stmt*);

2768

</pre></blockquote><p>

2769

The sqlite3_stmt_busy(S) interface returns true (non-zero) if the

2770

<a href="#sqlite3_stmt">prepared statement</a> S has been stepped at least once using

2771

<a href="#sqlite3_step">sqlite3_step(S)</a> but has not run to completion and/or has not

2772

been reset using <a href="#sqlite3_reset">sqlite3_reset(S)</a>. The sqlite3_stmt_busy(S)

2773

interface returns false if S is a NULL pointer. If S is not a

2774

NULL pointer and is not a pointer to a valid <a href="#sqlite3_stmt">prepared statement</a>

2775

object, then the behavior is undefined and probably undesirable.</p>

2776

2777

<p>This interface can be used in combination <a href="#sqlite3_next_stmt">sqlite3_next_stmt()</a>

2778

to locate all prepared statements associated with a database

2779

connection that are in need of being reset. This can be used,

2780

for example, in diagnostic routines to search for prepared

2781

statements that are holding a transaction open.

2782

</p><hr><a name="sqlite3_stmt_readonly"></a>

2783

<h2>Determine If An SQL Statement Writes The Database</h2><blockquote><pre>int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);

2784

</pre></blockquote><p>

2785

The sqlite3_stmt_readonly(X) interface returns true (non-zero) if

2786

and only if the <a href="#sqlite3_stmt">prepared statement</a> X makes no direct changes to

2787

the content of the database file.</p>

2788

2789

<p>Note that <a href="#sqlite3_create_function">application-defined SQL functions</a> or

2790

<a href="vtab.html">virtual tables</a> might change the database indirectly as a side effect.

2791

For example, if an application defines a function "eval()" that

2792

calls <a href="#sqlite3_exec">sqlite3_exec()</a>, then the following SQL statement would

2793

change the database file through side-effects:</p>

2794

2795

2796

SELECT eval('DELETE FROM t1') FROM t2;

2797

</pre></blockquote></p>

2798

2799

<p>But because the <a href="lang_select.html">SELECT</a> statement does not change the database file

2800

directly, sqlite3_stmt_readonly() would still return true.</p>

2801

2802

<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>,

2803

<a href="lang_savepoint.html">SAVEPOINT</a>, and <a href="lang_savepoint.html">RELEASE</a> cause sqlite3_stmt_readonly() to return true,

2804

since the statements themselves do not actually modify the database but

2805

rather they control the timing of when other statements modify the

2806

database. The <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> statements also cause

2807

sqlite3_stmt_readonly() to return true since, while those statements

2808

change the configuration of a database connection, they do not make

2809

changes to the content of the database files on disk.

2810

</p><hr><a name="sqlite3_stmt_status"></a>

2811

<h2>Prepared Statement Status</h2><blockquote><pre>int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);

2812

</pre></blockquote><p>

2813

Each prepared statement maintains various

2814

<a href="#SQLITE_STMTSTATUS counter">SQLITE_STMTSTATUS counters</a> that measure the number

2815

of times it has performed specific operations. These counters can

2816

be used to monitor the performance characteristics of the prepared

2817

statements. For example, if the number of table steps greatly exceeds

2818

the number of table searches or result rows, that would tend to indicate

2819

that the prepared statement is using a full table scan rather than

2820

an index.</p>

2821

2822

<p>This interface is used to retrieve and reset counter values from

2823

a <a href="#sqlite3_stmt">prepared statement</a>. The first argument is the prepared statement

2824

object to be interrogated. The second argument

2825

is an integer code for a specific <a href="#SQLITE_STMTSTATUS counter">SQLITE_STMTSTATUS counter</a>

2826

to be interrogated.

2827

The current value of the requested counter is returned.

2828

If the resetFlg is true, then the counter is reset to zero after this

2829

interface call returns.</p>

2830

2831

<p>See also: <a href="#sqlite3_status">sqlite3_status()</a> and <a href="#sqlite3_db_status">sqlite3_db_status()</a>.

2832

</p><hr><a name="sqlite3_table_column_metadata"></a>

2833

<h2>Extract Metadata About A Column Of A Table</h2><blockquote><pre>int sqlite3_table_column_metadata(

2834

sqlite3 *db, /* Connection handle */

2835

const char *zDbName, /* Database name or NULL */

2836

const char *zTableName, /* Table name */

2837

const char *zColumnName, /* Column name */

2838

char const **pzDataType, /* OUTPUT: Declared data type */

2839

char const **pzCollSeq, /* OUTPUT: Collation sequence name */

2840

int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */

2841

int *pPrimaryKey, /* OUTPUT: True if column part of PK */

2842

int *pAutoinc /* OUTPUT: True if column is auto-increment */

2843

);

2844

</pre></blockquote><p>

2845

This routine returns metadata about a specific column of a specific

2846

database table accessible using the <a href="#sqlite3">database connection</a> handle

2847

passed as the first function argument.</p>

2848

2849

<p>The column is identified by the second, third and fourth parameters to

2850

this function. The second parameter is either the name of the database

2851

(i.e. "main", "temp", or an attached database) containing the specified

2852

table or NULL. If it is NULL, then all attached databases are searched

2853

for the table using the same algorithm used by the database engine to

2854

resolve unqualified table references.</p>

2855

2856

<p>The third and fourth parameters to this function are the table and column

2857

name of the desired column, respectively. Neither of these parameters

2858

may be NULL.</p>

2859

2860

<p>Metadata is returned by writing to the memory locations passed as the 5th

2861

and subsequent parameters to this function. Any of these arguments may be

2862

NULL, in which case the corresponding element of metadata is omitted.</p>

2863

2864

2865

2866

<tr><th> Parameter <th> Output<br>Type <th> Description</p>

2867

2868

<p><tr><td> 5th <td> const char* <td> Data type

2869

<tr><td> 6th <td> const char* <td> Name of default collation sequence

2870

<tr><td> 7th <td> int <td> True if column has a NOT NULL constraint

2871

<tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY

2872

<tr><td> 9th <td> int <td> True if column is <a href="autoinc.html">AUTOINCREMENT</a>

2873

</table>

2874

</blockquote></p>

2875

2876

<p>The memory pointed to by the character pointers returned for the

2877

declaration type and collation sequence is valid only until the next

2878

call to any SQLite API function.</p>

2879

2880

<p>If the specified table is actually a view, an <a href="#SQLITE_ABORT">error code</a> is returned.</p>

2881

2882

<p>If the specified column is "rowid", "oid" or "_rowid_" and an

2883

<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> column has been explicitly declared, then the output

2884

parameters are set for the explicitly declared column. If there is no

2885

explicitly declared <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> column, then the output

2886

parameters are set as follows:</p>

2887

2888

2889

data type: "INTEGER"

2890

collation sequence: "BINARY"

2891

not null: 0

2892

primary key: 1

2893

auto increment: 0

2894

</pre></p>

2895

2896

<p>This function may load one or more schemas from database files. If an

2897

error occurs during this process, or if the requested table or column

2898

cannot be found, an <a href="#SQLITE_ABORT">error code</a> is returned and an error message left

2899

in the <a href="#sqlite3">database connection</a> (to be retrieved using sqlite3_errmsg()).</p>

2900

2901

<p>This API is only available if the library was compiled with the

2902

<a href="compile.html#enable_column_metadata">SQLITE_ENABLE_COLUMN_METADATA</a> C-preprocessor symbol defined.

2903

</p><hr><a name="sqlite3_test_control"></a>

2904

<h2>Testing Interface</h2><blockquote><pre>int sqlite3_test_control(int op, ...);

2905

</pre></blockquote><p>

2906

The sqlite3_test_control() interface is used to read out internal

2907

state of SQLite and to inject faults into SQLite for testing

2908

purposes. The first parameter is an operation code that determines

2909

the number, meaning, and operation of all subsequent parameters.</p>

2910

2911

<p>This interface is not for use by applications. It exists solely

2912

for verifying the correct operation of the SQLite library. Depending

2913

on how the SQLite library is compiled, this interface might not exist.</p>

2914

2915

<p>The details of the operation codes, their meanings, the parameters

2916

they take, and what they do are all subject to change without notice.

2917

Unlike most of the SQLite API, this function is not guaranteed to

2918

operate consistently from one release to the next.

2919

</p><hr><a name="sqlite3_threadsafe"></a>

2920

<h2>Test To See If The Library Is Threadsafe</h2><blockquote><pre>int sqlite3_threadsafe(void);

2921

</pre></blockquote><p>

2922

The sqlite3_threadsafe() function returns zero if and only if

2923

SQLite was compiled with mutexing code omitted due to the

2924

<a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> compile-time option being set to 0.</p>

2925

2926

<p>SQLite can be compiled with or without mutexes. When

2927

the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> C preprocessor macro is 1 or 2, mutexes

2928

are enabled and SQLite is threadsafe. When the

2929

<a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> macro is 0,

2930

the mutexes are omitted. Without the mutexes, it is not safe

2931

to use SQLite concurrently from more than one thread.</p>

2932

2933

<p>Enabling mutexes incurs a measurable performance penalty.

2934

So if speed is of utmost importance, it makes sense to disable

2935

the mutexes. But for maximum safety, mutexes should be enabled.

2936

The default behavior is for mutexes to be enabled.</p>

2937

2938

<p>This interface can be used by an application to make sure that the

2939

version of SQLite that it is linking against was compiled with

2940

the desired setting of the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> macro.</p>

2941

2942

<p>This interface only reports on the compile-time mutex setting

2943

of the <a href="compile.html#threadsafe">SQLITE_THREADSAFE</a> flag. If SQLite is compiled with

2944

SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but

2945

can be fully or partially disabled using a call to <a href="#sqlite3_config">sqlite3_config()</a>

2946

with the verbs <a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a>, <a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>,

2947

or <a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a>. The return value of the

2948

sqlite3_threadsafe() function shows only the compile-time setting of

2949

thread safety, not any run-time changes to that setting made by

2950

sqlite3_config(). In other words, the return value from sqlite3_threadsafe()

2951

is unchanged by calls to sqlite3_config().</p>

2952

2953

<p>See the <a href="threadsafe.html">threading mode</a> documentation for additional information.

2954

</p><hr><a name="sqlite3_total_changes"></a>

2955

<h2>Total Number Of Rows Modified</h2><blockquote><pre>int sqlite3_total_changes(sqlite3*);

2956

</pre></blockquote><p>

2957

This function returns the number of row changes caused by <a href="lang_insert.html">INSERT</a>,

2958

<a href="lang_update.html">UPDATE</a> or <a href="lang_delete.html">DELETE</a> statements since the <a href="#sqlite3">database connection</a> was opened.

2959

The count returned by sqlite3_total_changes() includes all changes

2960

from all <a href="lang_createtrigger.html">trigger</a> contexts and changes made by

2961

<a href="foreignkeys.html#fk_actions">foreign key actions</a>. However,

2962

the count does not include changes used to implement <a href="lang_replace.html">REPLACE</a> constraints,

2963

do rollbacks or ABORT processing, or <a href="lang_droptable.html">DROP TABLE</a> processing. The

2964

count does not include rows of views that fire an <a href="lang_createtrigger.html#instead_of_trigger">INSTEAD OF trigger</a>,

2965

though if the INSTEAD OF trigger makes changes of its own, those changes

2966

are counted.

2967

The sqlite3_total_changes() function counts the changes as soon as

2968

the statement that makes them is completed (when the statement handle

2969

is passed to <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a>).</p>

2970

2971

<p>See also the <a href="#sqlite3_changes">sqlite3_changes()</a> interface, the

2972

<a href="pragma.html#pragma_count_changes">count_changes pragma</a>, and the <a href="lang_corefunc.html#total_changes">total_changes() SQL function</a>.</p>

2973

2974

<p>If a separate thread makes changes on the same database connection

2975

while <a href="#sqlite3_total_changes">sqlite3_total_changes()</a> is running then the value

2976

returned is unpredictable and not meaningful.

2977

</p><hr><a name="sqlite3_unlock_notify"></a>

2978

<h2>Unlock Notification</h2><blockquote><pre>int sqlite3_unlock_notify(

2979

sqlite3 *pBlocked, /* Waiting connection */

2980

void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */

2981

void *pNotifyArg /* Argument to pass to xNotify */

2982

);

2983

</pre></blockquote><p>

2984

When running in shared-cache mode, a database operation may fail with

2985

an <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> error if the required locks on the shared-cache or

2986

individual tables within the shared-cache cannot be obtained. See

2987

<a href="sharedcache.html">SQLite Shared-Cache Mode</a> for a description of shared-cache locking.

2988

This API may be used to register a callback that SQLite will invoke

2989

when the connection currently holding the required lock relinquishes it.

2990

This API is only available if the library was compiled with the

2991

<a href="compile.html#enable_unlock_notify">SQLITE_ENABLE_UNLOCK_NOTIFY</a> C-preprocessor symbol defined.</p>

2992

2993

<p>See Also: <a href="unlock_notify.html">Using the SQLite Unlock Notification Feature</a>.</p>

2994

2995

<p>Shared-cache locks are released when a database connection concludes

2996

its current transaction, either by committing it or rolling it back.</p>

2997

2998

<p>When a connection (known as the blocked connection) fails to obtain a

2999

shared-cache lock and SQLITE_LOCKED is returned to the caller, the

3000

identity of the database connection (the blocking connection) that

3001

has locked the required resource is stored internally. After an

3002

application receives an SQLITE_LOCKED error, it may call the

3003

sqlite3_unlock_notify() method with the blocked connection handle as

3004

the first argument to register for a callback that will be invoked

3005

when the blocking connections current transaction is concluded. The

3006

callback is invoked from within the <a href="#sqlite3_step">sqlite3_step</a> or <a href="#sqlite3_close">sqlite3_close</a>

3007

call that concludes the blocking connections transaction.</p>

3008

3009

<p>If sqlite3_unlock_notify() is called in a multi-threaded application,

3010

there is a chance that the blocking connection will have already

3011

concluded its transaction by the time sqlite3_unlock_notify() is invoked.

3012

If this happens, then the specified callback is invoked immediately,

3013

from within the call to sqlite3_unlock_notify().</p>

3014

3015

<p>If the blocked connection is attempting to obtain a write-lock on a

3016

shared-cache table, and more than one other connection currently holds

3017

a read-lock on the same table, then SQLite arbitrarily selects one of

3018

the other connections to use as the blocking connection.</p>

3019

3020

<p>There may be at most one unlock-notify callback registered by a

3021

blocked connection. If sqlite3_unlock_notify() is called when the

3022

blocked connection already has a registered unlock-notify callback,

3023

then the new callback replaces the old. If sqlite3_unlock_notify() is

3024

called with a NULL pointer as its second argument, then any existing

3025

unlock-notify callback is canceled. The blocked connections

3026

unlock-notify callback may also be canceled by closing the blocked

3027

connection using <a href="#sqlite3_close">sqlite3_close()</a>.</p>

3028

3029

<p>The unlock-notify callback is not reentrant. If an application invokes

3030

any sqlite3_xxx API functions from within an unlock-notify callback, a

3031

crash or deadlock may be the result.</p>

3032

3033

<p>Unless deadlock is detected (see below), sqlite3_unlock_notify() always

3034

returns SQLITE_OK.</p>

3035

3036

<p><b>Callback Invocation Details</b></p>

3037

3038

<p>When an unlock-notify callback is registered, the application provides a

3039

single void* pointer that is passed to the callback when it is invoked.

3040

However, the signature of the callback function allows SQLite to pass

3041

it an array of void* context pointers. The first argument passed to

3042

an unlock-notify callback is a pointer to an array of void* pointers,

3043

and the second is the number of entries in the array.</p>

3044

3045

<p>When a blocking connections transaction is concluded, there may be

3046

more than one blocked connection that has registered for an unlock-notify

3047

callback. If two or more such blocked connections have specified the

3048

same callback function, then instead of invoking the callback function

3049

multiple times, it is invoked once with the set of void* context pointers

3050

specified by the blocked connections bundled together into an array.

3051

This gives the application an opportunity to prioritize any actions

3052

related to the set of unblocked database connections.</p>

3053

3054

<p><b>Deadlock Detection</b></p>

3055

3056

<p>Assuming that after registering for an unlock-notify callback a

3057

database waits for the callback to be issued before taking any further

3058

action (a reasonable assumption), then using this API may cause the

3059

application to deadlock. For example, if connection X is waiting for

3060

connection Y's transaction to be concluded, and similarly connection

3061

Y is waiting on connection X's transaction, then neither connection

3062

will proceed and the system may remain deadlocked indefinitely.</p>

3063

3064

<p>To avoid this scenario, the sqlite3_unlock_notify() performs deadlock

3065

detection. If a given call to sqlite3_unlock_notify() would put the

3066

system in a deadlocked state, then SQLITE_LOCKED is returned and no

3067

unlock-notify callback is registered. The system is said to be in

3068

a deadlocked state if connection A has registered for an unlock-notify

3069

callback on the conclusion of connection B's transaction, and connection

3070

B has itself registered for an unlock-notify callback when connection

3071

A's transaction is concluded. Indirect deadlock is also detected, so

3072

the system is also considered to be deadlocked if connection B has

3073

registered for an unlock-notify callback on the conclusion of connection

3074

C's transaction, where connection C is waiting on connection A. Any

3075

number of levels of indirection are allowed.</p>

3076

3077

<p><b>The "DROP TABLE" Exception</b></p>

3078

3079

<p>When a call to <a href="#sqlite3_step">sqlite3_step()</a> returns SQLITE_LOCKED, it is almost

3080

always appropriate to call sqlite3_unlock_notify(). There is however,

3081

one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,

3082

SQLite checks if there are any currently executing SELECT statements

3083

that belong to the same connection. If there are, SQLITE_LOCKED is

3084

returned. In this case there is no "blocking connection", so invoking

3085

sqlite3_unlock_notify() results in the unlock-notify callback being

3086

invoked immediately. If the application then re-attempts the "DROP TABLE"

3087

or "DROP INDEX" query, an infinite loop might be the result.</p>

3088

3089

<p>One way around this problem is to check the extended error code returned

3090

by an sqlite3_step() call. If there is a blocking connection, then the

3091

extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in

3092

the special "DROP TABLE/INDEX" case, the extended error code is just

3093

SQLITE_LOCKED.

3094

</p><hr><a name="sqlite3_update_hook"></a>

3095

<h2>Data Change Notification Callbacks</h2><blockquote><pre>void *sqlite3_update_hook(

3096

sqlite3*,

3097

void(*)(void *,int ,char const *,char const *,sqlite3_int64),

3098

void*

3099

);

3100

</pre></blockquote><p>

3101

The sqlite3_update_hook() interface registers a callback function

3102

with the <a href="#sqlite3">database connection</a> identified by the first argument

3103

to be invoked whenever a row is updated, inserted or deleted.

3104

Any callback set by a previous call to this function

3105

for the same database connection is overridden.</p>

3106

3107

<p>The second argument is a pointer to the function to invoke when a

3108

row is updated, inserted or deleted.

3109

The first argument to the callback is a copy of the third argument

3110

to sqlite3_update_hook().

3111

The second callback argument is one of <a href="#SQLITE_ALTER_TABLE">SQLITE_INSERT</a>, <a href="#SQLITE_ALTER_TABLE">SQLITE_DELETE</a>,

3112

or <a href="#SQLITE_ALTER_TABLE">SQLITE_UPDATE</a>, depending on the operation that caused the callback

3113

to be invoked.

3114

The third and fourth arguments to the callback contain pointers to the

3115

database and table name containing the affected row.

3116

The final callback parameter is the <a href="lang_createtable.html#rowid">rowid</a> of the row.

3117

In the case of an update, this is the <a href="lang_createtable.html#rowid">rowid</a> after the update takes place.</p>

3118

3119

<p>The update hook is not invoked when internal system tables are

3120

modified (i.e. sqlite_master and sqlite_sequence).</p>

3121

3122

<p>In the current implementation, the update hook

3123

is not invoked when duplication rows are deleted because of an

3124

<a href="lang_conflict.html">ON CONFLICT REPLACE</a> clause. Nor is the update hook

3125

invoked when rows are deleted using the <a href="lang_delete.html#truncateopt">truncate optimization</a>.

3126

The exceptions defined in this paragraph might change in a future

3127

release of SQLite.</p>

3128

3129

<p>The update hook implementation must not do anything that will modify

3130

the database connection that invoked the update hook. Any actions

3131

to modify the database connection must be deferred until after the

3132

completion of the <a href="#sqlite3_step">sqlite3_step()</a> call that triggered the update hook.

3133

Note that <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> both modify their

3134

database connections for the meaning of "modify" in this paragraph.</p>

3135

3136

<p>The sqlite3_update_hook(D,C,P) function

3137

returns the P argument from the previous call

3138

on the same <a href="#sqlite3">database connection</a> D, or NULL for

3139

the first call on D.</p>

3140

3141

<p>See also the <a href="#sqlite3_commit_hook">sqlite3_commit_hook()</a> and <a href="#sqlite3_commit_hook">sqlite3_rollback_hook()</a>

3142

interfaces.

3143

</p><hr><a name="sqlite3_user_data"></a>

3144

<h2>User Data For Functions</h2><blockquote><pre>void *sqlite3_user_data(sqlite3_context*);

3145

</pre></blockquote><p>

3146

The sqlite3_user_data() interface returns a copy of

3147

the pointer that was the pUserData parameter (the 5th parameter)

3148

of the <a href="#sqlite3_create_function">sqlite3_create_function()</a>

3149

and <a href="#sqlite3_create_function">sqlite3_create_function16()</a> routines that originally

3150

registered the application defined function.</p>

3151

3152

<p>This routine must be called from the same thread in which

3153

the application-defined function is running.

3154

</p><hr><a name="sqlite3_vtab_config"></a>

3155

<h2>Virtual Table Interface Configuration</h2><blockquote><pre>int sqlite3_vtab_config(sqlite3*, int op, ...);

3156

</pre></blockquote><p>

3157

This function may be called by either the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> method

3158

of a <a href="vtab.html">virtual table</a> implementation to configure

3159

various facets of the virtual table interface.</p>

3160

3161

<p>If this interface is invoked outside the context of an xConnect or

3162

xCreate virtual table method then the behavior is undefined.</p>

3163

3164

<p>At present, there is only one option that may be configured using

3165

this function. (See <a href="#SQLITE_VTAB_CONSTRAINT_SUPPORT">SQLITE_VTAB_CONSTRAINT_SUPPORT</a>.) Further options

3166

may be added in the future.

3167

</p><hr><a name="sqlite3_vtab_on_conflict"></a>

3168

<h2>Determine The Virtual Table Conflict Policy</h2><blockquote><pre>int sqlite3_vtab_on_conflict(sqlite3 *);

3169

</pre></blockquote><p>

3170

This function may only be called from within a call to the <a href="vtab.html#xupdate">xUpdate</a> method

3171

of a <a href="vtab.html">virtual table</a> implementation for an INSERT or UPDATE operation. The

3172

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>,

3173

<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

3174

of the SQL statement that triggered the call to the <a href="vtab.html#xupdate">xUpdate</a> method of the

3175

<a href="vtab.html">virtual table</a>.

3176

</p><hr><a name="sqlite3_wal_autocheckpoint"></a>

3177

<h2>Configure an auto-checkpoint</h2><blockquote><pre>int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

3178

</pre></blockquote><p>

3179

The <a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint(D,N)</a> is a wrapper around

3180

<a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> that causes any database on <a href="#sqlite3">database connection</a> D

3181

to automatically <a href="wal.html#ckpt">checkpoint</a>

3182

after committing a transaction if there are N or

3183

more frames in the <a href="wal.html">write-ahead log</a> file. Passing zero or

3184

a negative value as the nFrame parameter disables automatic

3185

checkpoints entirely.</p>

3186

3187

<p>The callback registered by this function replaces any existing callback

3188

registered using <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a>. Likewise, registering a callback

3189

using <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> disables the automatic checkpoint mechanism

3190

configured by this function.</p>

3191

3192

<p>The <a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> can be used to invoke this interface

3193

from SQL.</p>

3194

3195

<p>Every new <a href="#sqlite3">database connection</a> defaults to having the auto-checkpoint

3196

enabled with a threshold of 1000 or <a href="compile.html#default_wal_autocheckpoint">SQLITE_DEFAULT_WAL_AUTOCHECKPOINT</a>

3197

pages. The use of this interface

3198

is only necessary if the default setting is found to be suboptimal

3199

for a particular application.

3200

</p><hr><a name="sqlite3_wal_checkpoint"></a>

3201

<h2>Checkpoint a database</h2><blockquote><pre>int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);

3202

</pre></blockquote><p>

3203

The <a href="#sqlite3_wal_checkpoint">sqlite3_wal_checkpoint(D,X)</a> interface causes database named X

3204

on <a href="#sqlite3">database connection</a> D to be <a href="wal.html#ckpt">checkpointed</a>. If X is NULL or an

3205

empty string, then a checkpoint is run on all databases of

3206

connection D. If the database connection D is not in

3207

<a href="wal.html">write-ahead log mode</a> then this interface is a harmless no-op.</p>

3208

3209

<p>The <a href="pragma.html#pragma_wal_checkpoint">wal_checkpoint pragma</a> can be used to invoke this interface

3210

from SQL. The <a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint()</a> interface and the

3211

<a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> can be used to cause this interface to be

3212

run whenever the WAL reaches a certain size threshold.</p>

3213

3214

<p>See also: <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a>

3215

</p><hr><a name="sqlite3_wal_checkpoint_v2"></a>

3216

<h2>Checkpoint a database</h2><blockquote><pre>int sqlite3_wal_checkpoint_v2(

3217

sqlite3 *db, /* Database handle */

3218

const char *zDb, /* Name of attached database (or NULL) */

3219

int eMode, /* SQLITE_CHECKPOINT_* value */

3220

int *pnLog, /* OUT: Size of WAL log in frames */

3221

int *pnCkpt /* OUT: Total number of frames checkpointed */

3222

);

3223

</pre></blockquote><p>

3224

Run a checkpoint operation on WAL database zDb attached to database

3225

handle db. The specific operation is determined by the value of the

3226

eMode parameter:</p>

3227

3228

<p><dl>

3229

<dt>SQLITE_CHECKPOINT_PASSIVE<dd>

3230

Checkpoint as many frames as possible without waiting for any database

3231

readers or writers to finish. Sync the db file if all frames in the log

3232

are checkpointed. This mode is the same as calling

3233

sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.</p>

3234

3235

<p><dt>SQLITE_CHECKPOINT_FULL<dd>

3236

This mode blocks (calls the busy-handler callback) until there is no

3237

database writer and all readers are reading from the most recent database

3238

snapshot. It then checkpoints all frames in the log file and syncs the

3239

database file. This call blocks database writers while it is running,

3240

but not database readers.</p>

3241

3242

<p><dt>SQLITE_CHECKPOINT_RESTART<dd>

3243

This mode works the same way as SQLITE_CHECKPOINT_FULL, except after

3244

checkpointing the log file it blocks (calls the busy-handler callback)

3245

until all readers are reading from the database file only. This ensures

3246

that the next client to write to the database file restarts the log file

3247

from the beginning. This call blocks database writers while it is running,

3248

but not database readers.

3249

</dl></p>

3250

3251

<p>If pnLog is not NULL, then *pnLog is set to the total number of frames in

3252

the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to

3253

the total number of checkpointed frames (including any that were already

3254

checkpointed when this function is called). *pnLog and *pnCkpt may be

3255

populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.

3256

If no values are available because of an error, they are both set to -1

3257

before returning to communicate this to the caller.</p>

3258

3259

<p>All calls obtain an exclusive "checkpoint" lock on the database file. If

3260

any other process is running a checkpoint operation at the same time, the

3261

lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a

3262

busy-handler configured, it will not be invoked in this case.</p>

3263

3264

<p>The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive

3265

"writer" lock on the database file. If the writer lock cannot be obtained

3266

immediately, and a busy-handler is configured, it is invoked and the writer

3267

lock retried until either the busy-handler returns 0 or the lock is

3268

successfully obtained. The busy-handler is also invoked while waiting for

3269

database readers as described above. If the busy-handler returns 0 before

3270

the writer lock is obtained or while waiting for database readers, the

3271

checkpoint operation proceeds from that point in the same way as

3272

SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible

3273

without blocking any further. SQLITE_BUSY is returned in this case.</p>

3274

3275

<p>If parameter zDb is NULL or points to a zero length string, then the

3276

specified operation is attempted on all WAL databases. In this case the

3277

values written to output parameters *pnLog and *pnCkpt are undefined. If

3278

an SQLITE_BUSY error is encountered when processing one or more of the

3279

attached WAL databases, the operation is still attempted on any remaining

3280

attached databases and SQLITE_BUSY is returned to the caller. If any other

3281

error occurs while processing an attached database, processing is abandoned

3282

and the error code returned to the caller immediately. If no error

3283

(SQLITE_BUSY or otherwise) is encountered while processing the attached

3284

databases, SQLITE_OK is returned.</p>

3285

3286

<p>If database zDb is the name of an attached database that is not in WAL

3287

mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If

3288

zDb is not NULL (or a zero length string) and is not the name of any

3289

attached database, SQLITE_ERROR is returned to the caller.

3290

</p><hr><a name="sqlite3_wal_hook"></a>

3291

<h2>Write-Ahead Log Commit Hook</h2><blockquote><pre>void *sqlite3_wal_hook(

3292

sqlite3*,

3293

int(*)(void *,sqlite3*,const char*,int),

3294

void*

3295

);

3296

</pre></blockquote><p>

3297

The <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> function is used to register a callback that

3298

will be invoked each time a database connection commits data to a

3299

<a href="wal.html">write-ahead log</a> (i.e. whenever a transaction is committed in

3300

<a href="pragma.html#pragma_journal_mode">journal_mode=WAL mode</a>).</p>

3301

3302

<p>The callback is invoked by SQLite after the commit has taken place and

3303

the associated write-lock on the database released, so the implementation

3304

may read, write or <a href="wal.html#ckpt">checkpoint</a> the database as required.</p>

3305

3306

<p>The first parameter passed to the callback function when it is invoked

3307

is a copy of the third parameter passed to sqlite3_wal_hook() when

3308

registering the callback. The second is a copy of the database handle.

3309

The third parameter is the name of the database that was written to -

3310

either "main" or the name of an <a href="lang_attach.html">ATTACH</a>-ed database. The fourth parameter

3311

is the number of pages currently in the write-ahead log file,

3312

including those that were just committed.</p>

3313

3314

<p>The callback function should normally return <a href="#SQLITE_ABORT">SQLITE_OK</a>. If an error

3315

code is returned, that error will propagate back up through the

3316

SQLite code base to cause the statement that provoked the callback

3317

to report an error, though the commit will have still occurred. If the

3318

callback returns <a href="#SQLITE_ABORT">SQLITE_ROW</a> or <a href="#SQLITE_ABORT">SQLITE_DONE</a>, or if it returns a value

3319

that does not correspond to any valid SQLite error code, the results

3320

are undefined.</p>

3321

3322

<p>A single database handle may have at most a single write-ahead log callback

3323

registered at one time. Calling <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> replaces any

3324

previously registered write-ahead log callback. Note that the

3325

<a href="#sqlite3_wal_autocheckpoint">sqlite3_wal_autocheckpoint()</a> interface and the

3326

<a href="pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> both invoke <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> and will

3327

those overwrite any prior <a href="#sqlite3_wal_hook">sqlite3_wal_hook()</a> settings.

3328

</p><hr><a name="SQLITE_ABORT"></a>

3329

<h2>Result Codes</h2><blockquote><pre>#define SQLITE_OK 0 /* Successful result */

3330

/* beginning-of-error-codes */

3331

#define SQLITE_ERROR 1 /* SQL error or missing database */

3332

#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */

3333

#define SQLITE_PERM 3 /* Access permission denied */

3334

#define SQLITE_ABORT 4 /* Callback routine requested an abort */

3335

#define SQLITE_BUSY 5 /* The database file is locked */

3336

#define SQLITE_LOCKED 6 /* A table in the database is locked */

3337

#define SQLITE_NOMEM 7 /* A malloc() failed */

3338

#define SQLITE_READONLY 8 /* Attempt to write a readonly database */

3339

#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/

3340

#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */

3341

#define SQLITE_CORRUPT 11 /* The database disk image is malformed */

3342

#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */

3343

#define SQLITE_FULL 13 /* Insertion failed because database is full */

3344

#define SQLITE_CANTOPEN 14 /* Unable to open the database file */

3345

#define SQLITE_PROTOCOL 15 /* Database lock protocol error */

3346

#define SQLITE_EMPTY 16 /* Database is empty */

3347

#define SQLITE_SCHEMA 17 /* The database schema changed */

3348

#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */

3349

#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */

3350

#define SQLITE_MISMATCH 20 /* Data type mismatch */

3351

#define SQLITE_MISUSE 21 /* Library used incorrectly */

3352

#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */

3353

#define SQLITE_AUTH 23 /* Authorization denied */

3354

#define SQLITE_FORMAT 24 /* Auxiliary database format error */

3355

#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */

3356

#define SQLITE_NOTADB 26 /* File opened that is not a database file */

3357

#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */

3358

#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */

3359

/* end-of-error-codes */

3360

</pre></blockquote><p>

3361

Many SQLite functions return an integer result code from the set shown

3362

here in order to indicate success or failure.</p>

3363

3364

<p>New error codes may be added in future versions of SQLite.</p>

3365

3366

<p>See also: <a href="#SQLITE_ABORT_ROLLBACK">extended result codes</a>,

3367

<a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> <a href="#SQLITE_FAIL">result codes</a>.

3368

</p><hr><a name="SQLITE_ABORT_ROLLBACK"></a>

3369

<h2>Extended Result Codes</h2><blockquote><pre>#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))

3370

#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))

3371

#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))

3372

#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))

3373

#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))

3374

#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))

3375

#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))

3376

#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))

3377

#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))

3378

#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))

3379

#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))

3380

#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))

3381

#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))

3382

#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))

3383

#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))

3384

#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))

3385

#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))

3386

#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))

3387

#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))

3388

#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))

3389

#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))

3390

#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))

3391

#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))

3392

#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))

3393

#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))

3394

#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))

3395

#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))

3396

#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))

3397

#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))

3398

#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))

3399

</pre></blockquote><p>

3400

In its default configuration, SQLite API routines return one of 26 integer

3401

<a href="#SQLITE_ABORT">result codes</a>. However, experience has shown that many of

3402

these result codes are too coarse-grained. They do not provide as

3403

much information about problems as programmers might like. In an effort to

3404

address this, newer versions of SQLite (version 3.3.8 and later) include

3405

support for additional result codes that provide more detailed information

3406

about errors. The extended result codes are enabled or disabled

3407

on a per database connection basis using the

3408

<a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes()</a> API.</p>

3409

3410

<p>Some of the available extended result codes are listed here.

3411

One may expect the number of extended result codes will be expand

3412

over time. Software that uses extended result codes should expect

3413

to see new result codes in future releases of SQLite.</p>

3414

3415

<p>The SQLITE_OK result code will never be extended. It will always

3416

be exactly zero.

3417

</p><hr><a name="SQLITE_ACCESS_EXISTS"></a>

3418

<h2>Flags for the xAccess VFS method</h2><blockquote><pre>#define SQLITE_ACCESS_EXISTS 0

3419

#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */

3420

#define SQLITE_ACCESS_READ 2 /* Unused */

3421

</pre></blockquote><p>

3422

These integer constants can be used as the third parameter to

3423

the xAccess method of an <a href="#sqlite3_vfs">sqlite3_vfs</a> object. They determine

3424

what kind of permissions the xAccess method is looking for.

3425

With SQLITE_ACCESS_EXISTS, the xAccess method

3426

simply checks whether the file exists.

3427

With SQLITE_ACCESS_READWRITE, the xAccess method

3428

checks whether the named directory is both readable and writable

3429

(in other words, if files can be added, removed, and renamed within

3430

the directory).

3431

The SQLITE_ACCESS_READWRITE constant is currently used only by the

3432

<a href="pragma.html#pragma_temp_store_directory">temp_store_directory pragma</a>, though this could change in a future

3433

release of SQLite.

3434

With SQLITE_ACCESS_READ, the xAccess method

3435

checks whether the file is readable. The SQLITE_ACCESS_READ constant is

3436

currently unused, though it might be used in a future release of

3437

SQLite.

3438

</p><hr><a name="SQLITE_ALTER_TABLE"></a>

3439

<h2>Authorizer Action Codes</h2><blockquote><pre>/******************************************* 3rd ************ 4th ***********/

3440

#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */

3441

#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */

3442

#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */

3443

#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */

3444

#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */

3445

#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */

3446

#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */

3447

#define SQLITE_CREATE_VIEW 8 /* View Name NULL */

3448

#define SQLITE_DELETE 9 /* Table Name NULL */

3449

#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */

3450

#define SQLITE_DROP_TABLE 11 /* Table Name NULL */

3451

#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */

3452

#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */

3453

#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */

3454

#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */

3455

#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */

3456

#define SQLITE_DROP_VIEW 17 /* View Name NULL */

3457

#define SQLITE_INSERT 18 /* Table Name NULL */

3458

#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */

3459

#define SQLITE_READ 20 /* Table Name Column Name */

3460

#define SQLITE_SELECT 21 /* NULL NULL */

3461

#define SQLITE_TRANSACTION 22 /* Operation NULL */

3462

#define SQLITE_UPDATE 23 /* Table Name Column Name */

3463

#define SQLITE_ATTACH 24 /* Filename NULL */

3464

#define SQLITE_DETACH 25 /* Database Name NULL */

3465

#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */

3466

#define SQLITE_REINDEX 27 /* Index Name NULL */

3467

#define SQLITE_ANALYZE 28 /* Table Name NULL */

3468

#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */

3469

#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */

3470

#define SQLITE_FUNCTION 31 /* NULL Function Name */

3471

#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */

3472

#define SQLITE_COPY 0 /* No longer used */

3473

</pre></blockquote><p>

3474

The <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> interface registers a callback function

3475

that is invoked to authorize certain SQL statement actions. The

3476

second parameter to the callback is an integer code that specifies

3477

what action is being authorized. These are the integer action codes that

3478

the authorizer callback may be passed.</p>

3479

3480

<p>These action code values signify what kind of operation is to be

3481

authorized. The 3rd and 4th parameters to the authorization

3482

callback function will be parameters or NULL depending on which of these

3483

codes is used as the second parameter. The 5th parameter to the

3484

authorizer callback is the name of the database ("main", "temp",

3485

etc.) if applicable. The 6th parameter to the authorizer callback

3486

is the name of the inner-most trigger or view that is responsible for

3487

the access attempt or NULL if this access attempt is directly from

3488

top-level SQL code.

3489

</p><hr><a name="SQLITE_ANY"></a>

3490

<h2>Text Encodings</h2><blockquote><pre>#define SQLITE_UTF8 1

3491

#define SQLITE_UTF16LE 2

3492

#define SQLITE_UTF16BE 3

3493

#define SQLITE_UTF16 4 /* Use native byte order */

3494

#define SQLITE_ANY 5 /* sqlite3_create_function only */

3495

#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */

3496

</pre></blockquote><p>

3497

These constant define integer codes that represent the various

3498

text encodings supported by SQLite.

3499

</p><hr><a name="SQLITE_BLOB"></a>

3500

<h2>Fundamental Datatypes</h2><blockquote><pre>#define SQLITE_INTEGER 1

3501

#define SQLITE_FLOAT 2

3502

#define SQLITE_BLOB 4

3503

#define SQLITE_NULL 5

3504

#ifdef SQLITE_TEXT

3505

# undef SQLITE_TEXT

3506

#else

3507

# define SQLITE_TEXT 3

3508

#endif

3509

#define SQLITE3_TEXT 3

3510

</pre></blockquote><p>

3511

Every value in SQLite has one of five fundamental datatypes:</p>

3512

3513

<p><ul>

3514

<li> 64-bit signed integer

3515

<li> 64-bit IEEE floating point number

3516

<li> string

3517

<li> BLOB

3518

<li> NULL

3519

</ul></p>

3520

3521

<p>These constants are codes for each of those types.</p>

3522

3523

<p>Note that the SQLITE_TEXT constant was also used in SQLite version 2

3524

for a completely different meaning. Software that links against both

3525

SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not

3526

SQLITE_TEXT.

3527

</p><hr><a name="SQLITE_CHECKPOINT_FULL"></a>

3528

<h2>Checkpoint operation parameters</h2><blockquote><pre>#define SQLITE_CHECKPOINT_PASSIVE 0

3529

#define SQLITE_CHECKPOINT_FULL 1

3530

#define SQLITE_CHECKPOINT_RESTART 2

3531

</pre></blockquote><p>

3532

These constants can be used as the 3rd parameter to

3533

<a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a>. See the <a href="#sqlite3_wal_checkpoint_v2">sqlite3_wal_checkpoint_v2()</a>

3534

documentation for additional information about the meaning and use of

3535

each of these values.

3536

</p><hr><a name="SQLITE_CONFIG_GETMALLOC"></a>

3537

<h2>Configuration Options</h2><blockquote><pre>#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */

3538

#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */

3539

#define SQLITE_CONFIG_SERIALIZED 3 /* nil */

3540

#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */

3541

#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */

3542

#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */

3543

#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */

3544

#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */

3545

#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */

3546

#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */

3547

#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */

3548

/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */

3549

#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */

3550

#define SQLITE_CONFIG_PCACHE 14 /* no-op */

3551

#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */

3552

#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */

3553

#define SQLITE_CONFIG_URI 17 /* int */

3554

#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */

3555

#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */

3556

</pre></blockquote><p>

3557

These constants are the available integer configuration options that

3558

can be passed as the first argument to the <a href="#sqlite3_config">sqlite3_config()</a> interface.</p>

3559

3560

<p>New configuration options may be added in future releases of SQLite.

3561

Existing configuration options might be discontinued. Applications

3562

should check the return code from <a href="#sqlite3_config">sqlite3_config()</a> to make sure that

3563

the call worked. The <a href="#sqlite3_config">sqlite3_config()</a> interface will return a

3564

non-zero <a href="#SQLITE_ABORT">error code</a> if a discontinued or unsupported configuration option

3565

is invoked.</p>

3566

3567

<p><dl>

3568

3569

<dt>SQLITE_CONFIG_SINGLETHREAD</dt>

3570

<dd>There are no arguments to this option. This option sets the

3571

<a href="threadsafe.html">threading mode</a> to Single-thread. In other words, it disables

3572

all mutexing and puts SQLite into a mode where it can only be used

3573

by a single thread. If SQLite is compiled with

3574

the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then

3575

it is not possible to change the <a href="threadsafe.html">threading mode</a> from its default

3576

value of Single-thread and so <a href="#sqlite3_config">sqlite3_config()</a> will return

3577

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the SQLITE_CONFIG_SINGLETHREAD

3578

configuration option.</dd></p>

3579

3580

3581

<dt>SQLITE_CONFIG_MULTITHREAD</dt>

3582

<dd>There are no arguments to this option. This option sets the

3583

<a href="threadsafe.html">threading mode</a> to Multi-thread. In other words, it disables

3584

mutexing on <a href="#sqlite3">database connection</a> and <a href="#sqlite3_stmt">prepared statement</a> objects.

3585

The application is responsible for serializing access to

3586

<a href="#sqlite3">database connections</a> and <a href="#sqlite3_stmt">prepared statements</a>. But other mutexes

3587

are enabled so that SQLite will be safe to use in a multi-threaded

3588

environment as long as no two threads attempt to use the same

3589

<a href="#sqlite3">database connection</a> at the same time. If SQLite is compiled with

3590

the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then

3591

it is not possible to set the Multi-thread <a href="threadsafe.html">threading mode</a> and

3592

<a href="#sqlite3_config">sqlite3_config()</a> will return <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the

3593

SQLITE_CONFIG_MULTITHREAD configuration option.</dd></p>

3594

3595

3596

<dt>SQLITE_CONFIG_SERIALIZED</dt>

3597

<dd>There are no arguments to this option. This option sets the

3598

<a href="threadsafe.html">threading mode</a> to Serialized. In other words, this option enables

3599

all mutexes including the recursive

3600

mutexes on <a href="#sqlite3">database connection</a> and <a href="#sqlite3_stmt">prepared statement</a> objects.

3601

In this mode (which is the default when SQLite is compiled with

3602

<a href="compile.html#threadsafe">SQLITE_THREADSAFE=1</a>) the SQLite library will itself serialize access

3603

to <a href="#sqlite3">database connections</a> and <a href="#sqlite3_stmt">prepared statements</a> so that the

3604

application is free to use the same <a href="#sqlite3">database connection</a> or the

3605

same <a href="#sqlite3_stmt">prepared statement</a> in different threads at the same time.

3606

If SQLite is compiled with

3607

the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then

3608

it is not possible to set the Serialized <a href="threadsafe.html">threading mode</a> and

3609

<a href="#sqlite3_config">sqlite3_config()</a> will return <a href="#SQLITE_ABORT">SQLITE_ERROR</a> if called with the

3610

SQLITE_CONFIG_SERIALIZED configuration option.</dd></p>

3611

3612

3613

<dt>SQLITE_CONFIG_MALLOC</dt>

3614

<dd> This option takes a single argument which is a pointer to an

3615

instance of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure. The argument specifies

3616

alternative low-level memory allocation routines to be used in place of

3617

the memory allocation routines built into SQLite. SQLite makes

3618

its own private copy of the content of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure

3619

before the <a href="#sqlite3_config">sqlite3_config()</a> call returns.</dd></p>

3620

3621

3622

<dt>SQLITE_CONFIG_GETMALLOC</dt>

3623

<dd> This option takes a single argument which is a pointer to an

3624

instance of the <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a> structure. The <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a>

3625

structure is filled with the currently defined memory allocation routines.

3626

This option can be used to overload the default memory allocation

3627

routines with a wrapper that simulations memory allocation failure or

3628

tracks memory usage, for example. </dd></p>

3629

3630

3631

<dt>SQLITE_CONFIG_MEMSTATUS</dt>

3632

<dd> This option takes single argument of type int, interpreted as a

3633

boolean, which enables or disables the collection of memory allocation

3634

statistics. When memory allocation statistics are disabled, the

3635

following SQLite interfaces become non-operational:

3636

<ul>

3637

<li> <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a>

3638

<li> <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a>

3639

<li> <a href="#sqlite3_soft_heap_limit64">sqlite3_soft_heap_limit64()</a>

3640

<li> <a href="#sqlite3_status">sqlite3_status()</a>

3641

</ul>

3642

Memory allocation statistics are enabled by default unless SQLite is

3643

compiled with <a href="compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a>=0 in which case memory

3644

allocation statistics are disabled by default.

3645

</dd></p>

3646

3647

3648

<dt>SQLITE_CONFIG_SCRATCH</dt>

3649

<dd> This option specifies a static memory buffer that SQLite can use for

3650

scratch memory. There are three arguments: A pointer an 8-byte

3651

aligned memory buffer from which the scratch allocations will be

3652

drawn, the size of each scratch allocation (sz),

3653

and the maximum number of scratch allocations (N). The sz

3654

argument must be a multiple of 16.

3655

The first argument must be a pointer to an 8-byte aligned buffer

3656

of at least sz*N bytes of memory.

3657

SQLite will use no more than two scratch buffers per thread. So

3658

N should be set to twice the expected maximum number of threads.

3659

SQLite will never require a scratch buffer that is more than 6

3660

times the database page size. If SQLite needs needs additional

3661

scratch memory beyond what is provided by this configuration option, then

3662

<a href="#sqlite3_free">sqlite3_malloc()</a> will be used to obtain the memory needed.</dd></p>

3663

3664

3665

<dt>SQLITE_CONFIG_PAGECACHE</dt>

3666

<dd> This option specifies a static memory buffer that SQLite can use for

3667

the database page cache with the default page cache implementation.

3668

This configuration should not be used if an application-define page

3669

cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.

3670

There are three arguments to this option: A pointer to 8-byte aligned

3671

memory, the size of each page buffer (sz), and the number of pages (N).

3672

The sz argument should be the size of the largest database page

3673

(a power of two between 512 and 32768) plus a little extra for each

3674

page header. The page header size is 20 to 40 bytes depending on

3675

the host architecture. It is harmless, apart from the wasted memory,

3676

to make sz a little too large. The first

3677

argument should point to an allocation of at least sz*N bytes of memory.

3678

SQLite will use the memory provided by the first argument to satisfy its

3679

memory needs for the first N pages that it adds to cache. If additional

3680

page cache memory is needed beyond what is provided by this option, then

3681

SQLite goes to <a href="#sqlite3_free">sqlite3_malloc()</a> for the additional storage space.

3682

The pointer in the first argument must

3683

be aligned to an 8-byte boundary or subsequent behavior of SQLite

3684

will be undefined.</dd></p>

3685

3686

3687

<dt>SQLITE_CONFIG_HEAP</dt>

3688

<dd> This option specifies a static memory buffer that SQLite will use

3689

for all of its dynamic memory allocation needs beyond those provided

3690

for by <a href="#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a> and <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.

3691

There are three arguments: An 8-byte aligned pointer to the memory,

3692

the number of bytes in the memory buffer, and the minimum allocation size.

3693

If the first pointer (the memory pointer) is NULL, then SQLite reverts

3694

to using its default memory allocator (the system malloc() implementation),

3695

undoing any prior invocation of <a href="#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>. If the

3696

memory pointer is not NULL and either <a href="compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> or

3697

<a href="compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> are defined, then the alternative memory

3698

allocator is engaged to handle all of SQLites memory allocation needs.

3699

The first pointer (the memory pointer) must be aligned to an 8-byte

3700

boundary or subsequent behavior of SQLite will be undefined.

3701

The minimum allocation size is capped at 2**12. Reasonable values

3702

for the minimum allocation size are 2**5 through 2**8.</dd></p>

3703

3704

3705

<dt>SQLITE_CONFIG_MUTEX</dt>

3706

<dd> This option takes a single argument which is a pointer to an

3707

instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure. The argument specifies

3708

alternative low-level mutex routines to be used in place

3709

the mutex routines built into SQLite. SQLite makes a copy of the

3710

content of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure before the call to

3711

<a href="#sqlite3_config">sqlite3_config()</a> returns. If SQLite is compiled with

3712

the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then

3713

the entire mutexing subsystem is omitted from the build and hence calls to

3714

<a href="#sqlite3_config">sqlite3_config()</a> with the SQLITE_CONFIG_MUTEX configuration option will

3715

return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</dd></p>

3716

3717

3718

<dt>SQLITE_CONFIG_GETMUTEX</dt>

3719

<dd> This option takes a single argument which is a pointer to an

3720

instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure. The

3721

<a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a>

3722

structure is filled with the currently defined mutex routines.

3723

This option can be used to overload the default mutex allocation

3724

routines with a wrapper used to track mutex usage for performance

3725

profiling or testing, for example. If SQLite is compiled with

3726

the <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then

3727

the entire mutexing subsystem is omitted from the build and hence calls to

3728

<a href="#sqlite3_config">sqlite3_config()</a> with the SQLITE_CONFIG_GETMUTEX configuration option will

3729

return <a href="#SQLITE_ABORT">SQLITE_ERROR</a>.</dd></p>

3730

3731

3732

<dt>SQLITE_CONFIG_LOOKASIDE</dt>

3733

<dd> This option takes two arguments that determine the default

3734

memory allocation for the lookaside memory allocator on each

3735

<a href="#sqlite3">database connection</a>. The first argument is the

3736

size of each lookaside buffer slot and the second is the number of

3737

slots allocated to each database connection. This option sets the

3738

<i>default</i> lookaside size. The <a href="#SQLITE_DBCONFIG_ENABLE_FKEY">SQLITE_DBCONFIG_LOOKASIDE</a>

3739

verb to <a href="#sqlite3_db_config">sqlite3_db_config()</a> can be used to change the lookaside

3740

configuration on individual connections. </dd></p>

3741

3742

3743

<dt>SQLITE_CONFIG_PCACHE2</dt>

3744

<dd> This option takes a single argument which is a pointer to

3745

an <a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object. This object specifies the interface

3746

to a custom page cache implementation. SQLite makes a copy of the

3747

object and uses it for page cache memory allocations.</dd></p>

3748

3749

3750

<dt>SQLITE_CONFIG_GETPCACHE2</dt>

3751

<dd> This option takes a single argument which is a pointer to an

3752

<a href="#sqlite3_pcache_methods2">sqlite3_pcache_methods2</a> object. SQLite copies of the current

3753

page cache implementation into that object. </dd></p>

3754

3755

3756

<dt>SQLITE_CONFIG_LOG</dt>

3757

<dd> The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a

3758

function with a call signature of void(*)(void*,int,const char*),

3759

and a pointer to void. If the function pointer is not NULL, it is

3760

invoked by <a href="#sqlite3_log">sqlite3_log()</a> to process each logging event. If the

3761

function pointer is NULL, the <a href="#sqlite3_log">sqlite3_log()</a> interface becomes a no-op.

3762

The void pointer that is the second argument to SQLITE_CONFIG_LOG is

3763

passed through as the first parameter to the application-defined logger

3764

function whenever that function is invoked. The second parameter to

3765

the logger function is a copy of the first parameter to the corresponding

3766

<a href="#sqlite3_log">sqlite3_log()</a> call and is intended to be a <a href="#SQLITE_ABORT">result code</a> or an

3767

<a href="#SQLITE_ABORT_ROLLBACK">extended result code</a>. The third parameter passed to the logger is

3768

log message after formatting via <a href="#sqlite3_mprintf">sqlite3_snprintf()</a>.

3769

The SQLite logging interface is not reentrant; the logger function

3770

supplied by the application must not invoke any SQLite interface.

3771

In a multi-threaded application, the application-defined logger

3772

function must be threadsafe. </dd></p>

3773

3774

3775

<dt>SQLITE_CONFIG_URI

3776

<dd> This option takes a single argument of type int. If non-zero, then

3777

URI handling is globally enabled. If the parameter is zero, then URI handling

3778

is globally disabled. If URI handling is globally enabled, all filenames

3779

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

3780

specified as part of <a href="lang_attach.html">ATTACH</a> commands are interpreted as URIs, regardless

3781

of whether or not the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flag is set when the database

3782

connection is opened. If it is globally disabled, filenames are

3783

only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the

3784

database connection is opened. By default, URI handling is globally

3785

disabled. The default value may be changed by compiling with the

3786

<a href="compile.html#use_uri">SQLITE_USE_URI</a> symbol defined.</p>

3787

3788

3789

3790

3791

<dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE

3792

<dd> These options are obsolete and should not be used by new code.

3793

They are retained for backwards compatibility but are now no-ops.

3794

</dl>

3795

</p><hr><a name="SQLITE_DBCONFIG_ENABLE_FKEY"></a>

3796

<h2>Database Connection Configuration Options</h2><blockquote><pre>#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */

3797

#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */

3798

#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */

3799

</pre></blockquote><p>

3800

These constants are the available integer configuration options that

3801

can be passed as the second argument to the <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface.</p>

3802

3803

<p>New configuration options may be added in future releases of SQLite.

3804

Existing configuration options might be discontinued. Applications

3805

should check the return code from <a href="#sqlite3_db_config">sqlite3_db_config()</a> to make sure that

3806

the call worked. The <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface will return a

3807

non-zero <a href="#SQLITE_ABORT">error code</a> if a discontinued or unsupported configuration option

3808

is invoked.</p>

3809

3810

<p><dl>

3811

<dt>SQLITE_DBCONFIG_LOOKASIDE</dt>

3812

<dd> This option takes three additional arguments that determine the

3813

<a href="malloc.html#lookaside">lookaside memory allocator</a> configuration for the <a href="#sqlite3">database connection</a>.

3814

The first argument (the third parameter to <a href="#sqlite3_db_config">sqlite3_db_config()</a> is a

3815

pointer to a memory buffer to use for lookaside memory.

3816

The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb

3817

may be NULL in which case SQLite will allocate the

3818

lookaside buffer itself using <a href="#sqlite3_free">sqlite3_malloc()</a>. The second argument is the

3819

size of each lookaside buffer slot. The third argument is the number of

3820

slots. The size of the buffer in the first argument must be greater than

3821

or equal to the product of the second and third arguments. The buffer

3822

must be aligned to an 8-byte boundary. If the second argument to

3823

SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally

3824

rounded down to the next smaller multiple of 8. The lookaside memory

3825

configuration for a database connection can only be changed when that

3826

connection is not currently using lookaside memory, or in other words

3827

when the "current value" returned by

3828

<a href="#sqlite3_db_status">sqlite3_db_status</a>(D,<a href="#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>,...) is zero.

3829

Any attempt to change the lookaside memory configuration when lookaside

3830

memory is in use leaves the configuration unchanged and returns

3831

<a href="#SQLITE_ABORT">SQLITE_BUSY</a>.</dd></p>

3832

3833

<p><dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>

3834

<dd> This option is used to enable or disable the enforcement of

3835

<a href="foreignkeys.html">foreign key constraints</a>. There should be two additional arguments.

3836

The first argument is an integer which is 0 to disable FK enforcement,

3837

positive to enable FK enforcement or negative to leave FK enforcement

3838

unchanged. The second parameter is a pointer to an integer into which

3839

is written 0 or 1 to indicate whether FK enforcement is off or on

3840

following this call. The second parameter may be a NULL pointer, in

3841

which case the FK enforcement setting is not reported back. </dd></p>

3842

3843

<p><dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>

3844

<dd> This option is used to enable or disable <a href="lang_createtrigger.html">triggers</a>.

3845

There should be two additional arguments.

3846

The first argument is an integer which is 0 to disable triggers,

3847

positive to enable triggers or negative to leave the setting unchanged.

3848

The second parameter is a pointer to an integer into which

3849

is written 0 or 1 to indicate whether triggers are disabled or enabled

3850

following this call. The second parameter may be a NULL pointer, in

3851

which case the trigger setting is not reported back. </dd></p>

3852

3853

3854

</p><hr><a name="SQLITE_DENY"></a>

3855

<h2>Authorizer Return Codes</h2><blockquote><pre>#define SQLITE_DENY 1 /* Abort the SQL statement with an error */

3856

#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */

3857

</pre></blockquote><p>

3858

The <a href="#sqlite3_set_authorizer">authorizer callback function</a> must

3859

return either <a href="#SQLITE_ABORT">SQLITE_OK</a> or one of these two constants in order

3860

to signal SQLite whether or not the action is permitted. See the

3861

<a href="#sqlite3_set_authorizer">authorizer documentation</a> for additional

3862

information.</p>

3863

3864

<p>Note that SQLITE_IGNORE is also used as a <a href="#SQLITE_FAIL">return code</a>

3865

from the <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> interface.

3866

</p><hr><a name="SQLITE_FAIL"></a>

3867

<h2>Conflict resolution modes</h2><blockquote><pre>#define SQLITE_ROLLBACK 1

3868

/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */

3869

#define SQLITE_FAIL 3

3870

/* #define SQLITE_ABORT 4 // Also an error code */

3871

#define SQLITE_REPLACE 5

3872

</pre></blockquote><p>

3873

These constants are returned by <a href="#sqlite3_vtab_on_conflict">sqlite3_vtab_on_conflict()</a> to

3874

inform a <a href="vtab.html">virtual table</a> implementation what the <a href="lang_conflict.html">ON CONFLICT</a> mode

3875

is for the SQL statement being evaluated.</p>

3876

3877

<p>Note that the <a href="#SQLITE_DENY">SQLITE_IGNORE</a> constant is also used as a potential

3878

return value from the <a href="#sqlite3_set_authorizer">sqlite3_set_authorizer()</a> callback and that

3879

<a href="#SQLITE_ABORT">SQLITE_ABORT</a> is also a <a href="#SQLITE_ABORT">result code</a>.

3880

</p><hr><a name="SQLITE_FCNTL_CHUNK_SIZE"></a>

3881

<h2>Standard File Control Opcodes</h2><blockquote><pre>#define SQLITE_FCNTL_LOCKSTATE 1

3882

#define SQLITE_GET_LOCKPROXYFILE 2

3883

#define SQLITE_SET_LOCKPROXYFILE 3

3884

#define SQLITE_LAST_ERRNO 4

3885

#define SQLITE_FCNTL_SIZE_HINT 5

3886

#define SQLITE_FCNTL_CHUNK_SIZE 6

3887

#define SQLITE_FCNTL_FILE_POINTER 7

3888

#define SQLITE_FCNTL_SYNC_OMITTED 8

3889

#define SQLITE_FCNTL_WIN32_AV_RETRY 9

3890

#define SQLITE_FCNTL_PERSIST_WAL 10

3891

#define SQLITE_FCNTL_OVERWRITE 11

3892

#define SQLITE_FCNTL_VFSNAME 12

3893

#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13

3894

#define SQLITE_FCNTL_PRAGMA 14

3895

</pre></blockquote><p>

3896

These integer constants are opcodes for the xFileControl method

3897

of the <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object and for the <a href="#sqlite3_file_control">sqlite3_file_control()</a>

3898

interface.</p>

3899

3900

<p>The <a href="#SQLITE_FCNTL_CHUNK_SIZE">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging. This

3901

opcode causes the xFileControl method to write the current state of

3902

the lock (one of <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>, <a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,

3903

<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>)

3904

into an integer that the pArg argument points to. This capability

3905

is used during testing and only needs to be supported when SQLITE_TEST

3906

is defined.

3907

<ul>

3908

3909

3910

The <a href="#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a> opcode is used by SQLite to give the VFS

3911

layer a hint of how large the database file will grow to be during the

3912

current transaction. This hint is not guaranteed to be accurate but it

3913

is often close. The underlying VFS might choose to preallocate database

3914

file space based on this hint in order to help writes to the database

3915

file run faster.</p>

3916

3917

3918

3919

The <a href="#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a> opcode is used to request that the VFS

3920

extends and truncates the database file in chunks of a size specified

3921

by the user. The fourth argument to <a href="#sqlite3_file_control">sqlite3_file_control()</a> should

3922

point to an integer (type int) containing the new chunk-size to use

3923

for the nominated database. Allocating database file space in large

3924

chunks (say 1MB at a time), may reduce file-system fragmentation and

3925

improve performance on some systems.</p>

3926

3927

3928

3929

The <a href="#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> opcode is used to obtain a pointer

3930

to the <a href="#sqlite3_file">sqlite3_file</a> object associated with a particular database

3931

connection. See the <a href="#sqlite3_file_control">sqlite3_file_control()</a> documentation for

3932

additional information.</p>

3933

3934

3935

3936

The <a href="#sqlitefcntlsyncomitted">SQLITE_FCNTL_SYNC_OMITTED</a> opcode is generated internally by

3937

SQLite and sent to all VFSes in place of a call to the xSync method

3938

when the database connection has <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a> set to OFF.

3939

Some specialized VFSes need this signal in order to operate correctly

3940

when <a href="pragma.html#pragma_synchronous">PRAGMA synchronous=OFF</a> is set, but most

3941

VFSes do not need this signal and should silently ignore this opcode.

3942

Applications should not call <a href="#sqlite3_file_control">sqlite3_file_control()</a> with this

3943

opcode as doing so may disrupt the operation of the specialized VFSes

3944

that do require it.</p>

3945

3946

3947

3948

The <a href="#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a> opcode is used to configure automatic

3949

retry counts and intervals for certain disk I/O operations for the

3950

windows <a href="vfs.html">VFS</a> in order to provide robustness in the presence of

3951

anti-virus programs. By default, the windows VFS will retry file read,

3952

file write, and file delete operations up to 10 times, with a delay

3953

of 25 milliseconds before the first retry and with the delay increasing

3954

by an additional 25 milliseconds with each subsequent retry. This

3955

opcode allows these two values (10 retries and 25 milliseconds of delay)

3956

to be adjusted. The values are changed for all database connections

3957

within the same process. The argument is a pointer to an array of two

3958

integers where the first integer i the new retry count and the second

3959

integer is the delay. If either integer is negative, then the setting

3960

is not changed but instead the prior value of that setting is written

3961

into the array entry, allowing the current retry settings to be

3962

interrogated. The zDbName parameter is ignored.</p>

3963

3964

3965

3966

The <a href="#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> opcode is used to set or query the

3967

persistent <a href="wal.html">Write Ahead Log</a> setting. By default, the auxiliary

3968

write ahead log and shared memory files used for transaction control

3969

are automatically deleted when the latest connection to the database

3970

closes. Setting persistent WAL mode causes those files to persist after

3971

close. Persisting the files is useful when other processes that do not

3972

have write permission on the directory containing the database file want

3973

to read the database file, as the WAL and shared memory files must exist

3974

in order for the database to be readable. The fourth parameter to

3975

<a href="#sqlite3_file_control">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.

3976

That integer is 0 to disable persistent WAL mode or 1 to enable persistent

3977

WAL mode. If the integer is -1, then it is overwritten with the current

3978

WAL persistence setting.</p>

3979

3980

3981

3982

The <a href="#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a> opcode is used to set or query the

3983

persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting

3984

determines the <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> bit of the

3985

xDeviceCharacteristics methods. The fourth parameter to

3986

<a href="#sqlite3_file_control">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.

3987

That integer is 0 to disable zero-damage mode or 1 to enable zero-damage

3988

mode. If the integer is -1, then it is overwritten with the current

3989

zero-damage mode setting.</p>

3990

3991

3992

3993

The <a href="#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a> opcode is invoked by SQLite after opening

3994

a write transaction to indicate that, unless it is rolled back for some

3995

reason, the entire database file will be overwritten by the current

3996

transaction. This is used by VACUUM operations.</p>

3997

3998

3999

4000

The <a href="#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a> opcode can be used to obtain the names of

4001

all <a href="vfs.html">VFSes</a> in the VFS stack. The names are of all VFS shims and the

4002

final bottom-level VFS are written into memory obtained from

4003

<a href="#sqlite3_free">sqlite3_malloc()</a> and the result is stored in the char* variable

4004

that the fourth parameter of <a href="#sqlite3_file_control">sqlite3_file_control()</a> points to.

4005

The caller is responsible for freeing the memory when done. As with

4006

all file-control actions, there is no guarantee that this will actually

4007

do anything. Callers should initialize the char* variable to a NULL

4008

pointer in case this file-control is not implemented. This file-control

4009

is intended for diagnostic use only.</p>

4010

4011

4012

4013

Whenever a <a href="pragma.html#syntax">PRAGMA</a> statement is parsed, an <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>

4014

file control is sent to the open <a href="#sqlite3_file">sqlite3_file</a> object corresponding

4015

to the database file to which the pragma statement refers. The argument

4016

to the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control is an array of

4017

pointers to strings (char**) in which the second element of the array

4018

is the name of the pragma and the third element is the argument to the

4019

pragma or NULL if the pragma has no argument. The handler for an

4020

<a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control can optionally make the first element

4021

of the char** argument point to a string obtained from <a href="#sqlite3_mprintf">sqlite3_mprintf()</a>

4022

or the equivalent and that string will become the result of the pragma or

4023

the error message if the pragma fails. If the

4024

<a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>, then normal

4025

<a href="pragma.html#syntax">PRAGMA</a> processing continues. If the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>

4026

file control returns <a href="#SQLITE_ABORT">SQLITE_OK</a>, then the parser assumes that the

4027

VFS has handled the PRAGMA itself and the parser generates a no-op

4028

prepared statement. If the <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns

4029

any result code other than <a href="#SQLITE_ABORT">SQLITE_OK</a> or <a href="#SQLITE_ABORT">SQLITE_NOTFOUND</a>, that means

4030

that the VFS encountered an error while handling the <a href="pragma.html#syntax">PRAGMA</a> and the

4031

compilation of the PRAGMA fails with an error. The <a href="#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>

4032

file control occurs at the beginning of pragma statement analysis and so

4033

it is able to override built-in <a href="pragma.html#syntax">PRAGMA</a> statements.

4034

</ul>

4035

</p><hr><a name="SQLITE_INDEX_CONSTRAINT_EQ"></a>

4036

<h2>Virtual Table Constraint Operator Codes</h2><blockquote><pre>#define SQLITE_INDEX_CONSTRAINT_EQ 2

4037

#define SQLITE_INDEX_CONSTRAINT_GT 4

4038

#define SQLITE_INDEX_CONSTRAINT_LE 8

4039

#define SQLITE_INDEX_CONSTRAINT_LT 16

4040

#define SQLITE_INDEX_CONSTRAINT_GE 32

4041

#define SQLITE_INDEX_CONSTRAINT_MATCH 64

4042

</pre></blockquote><p>

4043

These macros defined the allowed values for the

4044

<a href="#sqlite3_index_info">sqlite3_index_info</a>.aConstraint[].op field. Each value represents

4045

an operator that is part of a constraint term in the wHERE clause of

4046

a query that uses a <a href="vtab.html">virtual table</a>.

4047

</p><hr><a name="SQLITE_IOCAP_ATOMIC"></a>

4048

<h2>Device Characteristics</h2><blockquote><pre>#define SQLITE_IOCAP_ATOMIC 0x00000001

4049

#define SQLITE_IOCAP_ATOMIC512 0x00000002

4050

#define SQLITE_IOCAP_ATOMIC1K 0x00000004

4051

#define SQLITE_IOCAP_ATOMIC2K 0x00000008

4052

#define SQLITE_IOCAP_ATOMIC4K 0x00000010

4053

#define SQLITE_IOCAP_ATOMIC8K 0x00000020

4054

#define SQLITE_IOCAP_ATOMIC16K 0x00000040

4055

#define SQLITE_IOCAP_ATOMIC32K 0x00000080

4056

#define SQLITE_IOCAP_ATOMIC64K 0x00000100

4057

#define SQLITE_IOCAP_SAFE_APPEND 0x00000200

4058

#define SQLITE_IOCAP_SEQUENTIAL 0x00000400

4059

#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800

4060

#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000

4061

</pre></blockquote><p>

4062

The xDeviceCharacteristics method of the <a href="#sqlite3_io_methods">sqlite3_io_methods</a>

4063

object returns an integer which is a vector of the these

4064

bit values expressing I/O characteristics of the mass storage

4065

device that holds the file that the <a href="#sqlite3_io_methods">sqlite3_io_methods</a>

4066

refers to.</p>

4067

4068

<p>The SQLITE_IOCAP_ATOMIC property means that all writes of

4069

any size are atomic. The SQLITE_IOCAP_ATOMICnnn values

4070

mean that writes of blocks that are nnn bytes in size and

4071

are aligned to an address which is an integer multiple of

4072

nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means

4073

that when data is appended to a file, the data is appended

4074

first then the size of the file is extended, never the other

4075

way around. The SQLITE_IOCAP_SEQUENTIAL property means that

4076

information is written to disk in the same order as calls

4077

to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that

4078

after reboot following a crash or power loss, the only bytes in a

4079

file that were written at the application level might have changed

4080

and that adjacent bytes, even bytes within the same sector are

4081

guaranteed to be unchanged.

4082

</p><hr><a name="SQLITE_LOCK_EXCLUSIVE"></a>

4083

<h2>File Locking Levels</h2><blockquote><pre>#define SQLITE_LOCK_NONE 0

4084

#define SQLITE_LOCK_SHARED 1

4085

#define SQLITE_LOCK_RESERVED 2

4086

#define SQLITE_LOCK_PENDING 3

4087

#define SQLITE_LOCK_EXCLUSIVE 4

4088

</pre></blockquote><p>

4089

SQLite uses one of these integer values as the second

4090

argument to calls it makes to the xLock() and xUnlock() methods

4091

of an <a href="#sqlite3_io_methods">sqlite3_io_methods</a> object.

4092

</p><hr><a name="SQLITE_MUTEX_FAST"></a>

4093

<h2>Mutex Types</h2><blockquote><pre>#define SQLITE_MUTEX_FAST 0

4094

#define SQLITE_MUTEX_RECURSIVE 1

4095

#define SQLITE_MUTEX_STATIC_MASTER 2

4096

#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */

4097

#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */

4098

#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */

4099

#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */

4100

#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */

4101

#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */

4102

#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */

4103

</pre></blockquote><p>

4104

The <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> interface takes a single argument

4105

which is one of these integer constants.</p>

4106

4107

<p>The set of static mutexes may change from one SQLite release to the

4108

next. Applications that override the built-in mutex logic must be

4109

prepared to accommodate additional static mutexes.

4110

</p><hr><a name="SQLITE_OPEN_AUTOPROXY"></a>

4111

<h2>Flags For File Open Operations</h2><blockquote><pre>#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */

4112

#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */

4113

#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */

4114

#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */

4115

#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */

4116

#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */

4117

#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */

4118

#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */

4119

#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */

4120

#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */

4121

#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */

4122

#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */

4123

#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */

4124

#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */

4125

#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */

4126

#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */

4127

#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */

4128

#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */

4129

#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */

4130

#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */

4131

</pre></blockquote><p>

4132

These bit values are intended for use in the

4133

3rd parameter to the <a href="#sqlite3_open">sqlite3_open_v2()</a> interface and

4134

in the 4th parameter to the <a href="#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method.

4135

</p><hr><a name="SQLITE_SHM_EXCLUSIVE"></a>

4136

<h2>Flags for the xShmLock VFS method</h2><blockquote><pre>#define SQLITE_SHM_UNLOCK 1

4137

#define SQLITE_SHM_LOCK 2

4138

#define SQLITE_SHM_SHARED 4

4139

#define SQLITE_SHM_EXCLUSIVE 8

4140

</pre></blockquote><p>

4141

These integer constants define the various locking operations

4142

allowed by the xShmLock method of <a href="#sqlite3_io_methods">sqlite3_io_methods</a>. The

4143

following are the only legal combinations of flags to the

4144

xShmLock method:</p>

4145

4146

<p><ul>

4147

<li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED

4148

<li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE

4149

<li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED

4150

<li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE

4151

</ul></p>

4152

4153

<p>When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as

4154

was given no the corresponding lock.</p>

4155

4156

<p>The xShmLock method can transition between unlocked and SHARED or

4157

between unlocked and EXCLUSIVE. It cannot transition between SHARED

4158

and EXCLUSIVE.

4159

</p><hr><a name="SQLITE_SOURCE_ID"></a>

4160

<h2>Compile-Time Library Version Numbers</h2><blockquote><pre>#define SQLITE_VERSION "3.7.13"

4161

#define SQLITE_VERSION_NUMBER 3007013

4162

#define SQLITE_SOURCE_ID "2012-06-11 02:05:22 f5b5a13f7394dc143aa136f1d4faba6839eaa6dc"

4163

</pre></blockquote><p>

4164

The <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a> C preprocessor macro in the sqlite3.h header

4165

evaluates to a string literal that is the SQLite version in the

4166

format "X.Y.Z" where X is the major version number (always 3 for

4167

SQLite3) and Y is the minor version number and Z is the release number.

4168

The <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a> C preprocessor macro resolves to an integer

4169

with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same

4170

numbers used in <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a>.

4171

The SQLITE_VERSION_NUMBER for any given release of SQLite will also

4172

be larger than the release from which it is derived. Either Y will

4173

be held constant and Z will be incremented or else Y will be incremented

4174

and Z will be reset to zero.</p>

4175

4176

<p>Since version 3.6.18, SQLite source code has been stored in the

4177

<a href="http://www.fossil-scm.org/">Fossil configuration management

4178

system</a>. The SQLITE_SOURCE_ID macro evaluates to

4179

a string which identifies a particular check-in of SQLite

4180

within its configuration management system. The SQLITE_SOURCE_ID

4181

string contains the date and time of the check-in (UTC) and an SHA1

4182

hash of the entire source tree.</p>

4183

4184

<p>See also: <a href="#sqlite3_libversion">sqlite3_libversion()</a>,

4185

<a href="#sqlite3_libversion">sqlite3_libversion_number()</a>, <a href="#sqlite3_libversion">sqlite3_sourceid()</a>,

4186

<a href="lang_corefunc.html#sqlite_version">sqlite_version()</a> and <a href="lang_corefunc.html#sqlite_source_id">sqlite_source_id()</a>.

4187

</p><hr><a name="SQLITE_STATIC"></a>

4188

<h2>Constants Defining Special Destructor Behavior</h2><blockquote><pre>typedef void (*sqlite3_destructor_type)(void*);

4189

#define SQLITE_STATIC ((sqlite3_destructor_type)0)

4190

#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)

4191

</pre></blockquote><p>

4192

These are special values for the destructor that is passed in as the

4193

final argument to routines like <a href="#sqlite3_result_blob">sqlite3_result_blob()</a>. If the destructor

4194

argument is SQLITE_STATIC, it means that the content pointer is constant

4195

and will never change. It does not need to be destroyed. The

4196

SQLITE_TRANSIENT value means that the content will likely change in

4197

the near future and that SQLite should make its own private copy of

4198

the content before returning.</p>

4199

4200

<p>The typedef is necessary to work around problems in certain

4201

C++ compilers. See ticket #2191.

4202

</p><hr><a name="SQLITE_STATUS_MALLOC_COUNT"></a>

4203

<h2>Status Parameters</h2><blockquote><pre>#define SQLITE_STATUS_MEMORY_USED 0

4204

#define SQLITE_STATUS_PAGECACHE_USED 1

4205

#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2

4206

#define SQLITE_STATUS_SCRATCH_USED 3

4207

#define SQLITE_STATUS_SCRATCH_OVERFLOW 4

4208

#define SQLITE_STATUS_MALLOC_SIZE 5

4209

#define SQLITE_STATUS_PARSER_STACK 6

4210

#define SQLITE_STATUS_PAGECACHE_SIZE 7

4211

#define SQLITE_STATUS_SCRATCH_SIZE 8

4212

#define SQLITE_STATUS_MALLOC_COUNT 9

4213

</pre></blockquote><p>

4214

These integer constants designate various run-time status parameters

4215

that can be returned by <a href="#sqlite3_status">sqlite3_status()</a>.</p>

4216

4217

<p><dl>

4218

4219

<dt>SQLITE_STATUS_MEMORY_USED</dt>

4220

<dd>This parameter is the current amount of memory checked out

4221

using <a href="#sqlite3_free">sqlite3_malloc()</a>, either directly or indirectly. The

4222

figure includes calls made to <a href="#sqlite3_free">sqlite3_malloc()</a> by the application

4223

and internal memory usage by the SQLite library. Scratch memory

4224

controlled by <a href="#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a> and auxiliary page-cache

4225

memory controlled by <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a> is not included in

4226

this parameter. The amount returned is the sum of the allocation

4227

sizes as reported by the xSize method in <a href="#sqlite3_mem_methods">sqlite3_mem_methods</a>.</dd></p>

4228

4229

4230

<dt>SQLITE_STATUS_MALLOC_SIZE</dt>

4231

<dd>This parameter records the largest memory allocation request

4232

handed to <a href="#sqlite3_free">sqlite3_malloc()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a> (or their

4233

internal equivalents). Only the value returned in the

4234

*pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest.

4235

The value written into the *pCurrent parameter is undefined.</dd></p>

4236

4237

4238

<dt>SQLITE_STATUS_MALLOC_COUNT</dt>

4239

<dd>This parameter records the number of separate memory allocations

4240

currently checked out.</dd></p>

4241

4242

4243

<dt>SQLITE_STATUS_PAGECACHE_USED</dt>

4244

<dd>This parameter returns the number of pages used out of the

4245

<a href="malloc.html#pagecache">pagecache memory allocator</a> that was configured using

4246

<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>. The

4247

value returned is in pages, not in bytes.</dd></p>

4248

4249

4250

4251

<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>

4252

<dd>This parameter returns the number of bytes of page cache

4253

allocation which could not be satisfied by the <a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>

4254

buffer and where forced to overflow to <a href="#sqlite3_free">sqlite3_malloc()</a>. The

4255

returned value includes allocations that overflowed because they

4256

where too large (they were larger than the "sz" parameter to

4257

<a href="#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>) and allocations that overflowed because

4258

no space was left in the page cache.</dd></p>

4259

4260

4261

<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>

4262

<dd>This parameter records the largest memory allocation request

4263

handed to <a href="malloc.html#pagecache">pagecache memory allocator</a>. Only the value returned in the

4264

*pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest.

4265

The value written into the *pCurrent parameter is undefined.</dd></p>

4266

4267

4268

<dt>SQLITE_STATUS_SCRATCH_USED</dt>

4269

<dd>This parameter returns the number of allocations used out of the

4270

<a href="malloc.html#scratch">scratch memory allocator</a> configured using

4271

<a href="#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a>. The value returned is in allocations, not

4272

in bytes. Since a single thread may only have one scratch allocation

4273

outstanding at time, this parameter also reports the number of threads

4274

using scratch memory at the same time.</dd></p>

4275

4276

4277

<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>

4278

<dd>This parameter returns the number of bytes of scratch memory

4279

allocation which could not be satisfied by the <a href="#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a>

4280

buffer and where forced to overflow to <a href="#sqlite3_free">sqlite3_malloc()</a>. The values

4281

returned include overflows because the requested allocation was too

4282

larger (that is, because the requested allocation was larger than the

4283

"sz" parameter to <a href="#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a>) and because no scratch buffer

4284

slots were available.

4285

</dd></p>

4286

4287

4288

<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>

4289

<dd>This parameter records the largest memory allocation request

4290

handed to <a href="malloc.html#scratch">scratch memory allocator</a>. Only the value returned in the

4291

*pHighwater parameter to <a href="#sqlite3_status">sqlite3_status()</a> is of interest.

4292

The value written into the *pCurrent parameter is undefined.</dd></p>

4293

4294

4295

<dt>SQLITE_STATUS_PARSER_STACK</dt>

4296

<dd>This parameter records the deepest parser stack. It is only

4297

meaningful if SQLite is compiled with <a href="compile.html#yytrackmaxstackdepth">YYTRACKMAXSTACKDEPTH</a>.</dd>

4298

</dl></p>

4299

4300

<p>New status parameters may be added from time to time.

4301

</p><hr><a name="SQLITE_SYNC_DATAONLY"></a>

4302

<h2>Synchronization Type Flags</h2><blockquote><pre>#define SQLITE_SYNC_NORMAL 0x00002

4303

#define SQLITE_SYNC_FULL 0x00003

4304

#define SQLITE_SYNC_DATAONLY 0x00010

4305

</pre></blockquote><p>

4306

When SQLite invokes the xSync() method of an

4307

<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object it uses a combination of

4308

these integer values as the second argument.</p>

4309

4310

<p>When the SQLITE_SYNC_DATAONLY flag is used, it means that the

4311

sync operation only needs to flush data to mass storage. Inode

4312

information need not be flushed. If the lower four bits of the flag

4313

equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.

4314

If the lower four bits equal SQLITE_SYNC_FULL, that means

4315

to use Mac OS X style fullsync instead of fsync().</p>

4316

4317

<p>Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags

4318

with the <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a>=NORMAL and <a href="pragma.html#pragma_synchronous">PRAGMA synchronous</a>=FULL

4319

settings. The <a href="pragma.html#pragma_synchronous">synchronous pragma</a> determines when calls to the

4320

xSync VFS method occur and applies uniformly across all platforms.

4321

The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how

4322

energetic or rigorous or forceful the sync operations are and

4323

only make a difference on Mac OSX for the default SQLite code.

4324

(Third-party VFS implementations might also make the distinction

4325

between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the

4326

operating systems natively supported by SQLite, only Mac OSX

4327

cares about the difference.)

4328

</p><hr><a name="SQLITE_TESTCTRL_ALWAYS"></a>

4329

<h2>Testing Interface Operation Codes</h2><blockquote><pre>#define SQLITE_TESTCTRL_FIRST 5

4330

#define SQLITE_TESTCTRL_PRNG_SAVE 5

4331

#define SQLITE_TESTCTRL_PRNG_RESTORE 6

4332

#define SQLITE_TESTCTRL_PRNG_RESET 7

4333

#define SQLITE_TESTCTRL_BITVEC_TEST 8

4334

#define SQLITE_TESTCTRL_FAULT_INSTALL 9

4335

#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10

4336

#define SQLITE_TESTCTRL_PENDING_BYTE 11

4337

#define SQLITE_TESTCTRL_ASSERT 12

4338

#define SQLITE_TESTCTRL_ALWAYS 13

4339

#define SQLITE_TESTCTRL_RESERVE 14

4340

#define SQLITE_TESTCTRL_OPTIMIZATIONS 15

4341

#define SQLITE_TESTCTRL_ISKEYWORD 16

4342

#define SQLITE_TESTCTRL_SCRATCHMALLOC 17

4343

#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18

4344

#define SQLITE_TESTCTRL_EXPLAIN_STMT 19

4345

#define SQLITE_TESTCTRL_LAST 19

4346

</pre></blockquote><p>

4347

These constants are the valid operation code parameters used

4348

as the first argument to <a href="#sqlite3_test_control">sqlite3_test_control()</a>.</p>

4349

4350

<p>These parameters and their meanings are subject to change

4351

without notice. These values are for testing purposes only.

4352

Applications should not use any of these parameters or the

4353

<a href="#sqlite3_test_control">sqlite3_test_control()</a> interface.

4354

</p><hr><a name="SQLITE_LIMIT_ATTACHED"></a>

4355

<h2>Run-Time Limit Categories</h2><blockquote><pre>#define SQLITE_LIMIT_LENGTH 0

4356

#define SQLITE_LIMIT_SQL_LENGTH 1

4357

#define SQLITE_LIMIT_COLUMN 2

4358

#define SQLITE_LIMIT_EXPR_DEPTH 3

4359

#define SQLITE_LIMIT_COMPOUND_SELECT 4

4360

#define SQLITE_LIMIT_VDBE_OP 5

4361

#define SQLITE_LIMIT_FUNCTION_ARG 6

4362

#define SQLITE_LIMIT_ATTACHED 7

4363

#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8

4364

#define SQLITE_LIMIT_VARIABLE_NUMBER 9

4365

#define SQLITE_LIMIT_TRIGGER_DEPTH 10

4366

</pre></blockquote><p>

4367

These constants define various performance limits

4368

that can be lowered at run-time using <a href="#sqlite3_limit">sqlite3_limit()</a>.

4369

The synopsis of the meanings of the various limits is shown below.

4370

Additional information is available at <a href="limits.html">Limits in SQLite</a>.</p>

4371

4372

<p><dl>

4373

4374

<dt>SQLITE_LIMIT_LENGTH</dt>

4375

<dd>The maximum size of any string or BLOB or table row, in bytes.<dd></p>

4376

4377

4378

<dt>SQLITE_LIMIT_SQL_LENGTH</dt>

4379

<dd>The maximum length of an SQL statement, in bytes.</dd></p>

4380

4381

4382

<dt>SQLITE_LIMIT_COLUMN</dt>

4383

<dd>The maximum number of columns in a table definition or in the

4384

result set of a <a href="lang_select.html">SELECT</a> or the maximum number of columns in an index

4385

or in an ORDER BY or GROUP BY clause.</dd></p>

4386

4387

4388

<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>

4389

<dd>The maximum depth of the parse tree on any expression.</dd></p>

4390

4391

4392

<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>

4393

<dd>The maximum number of terms in a compound SELECT statement.</dd></p>

4394

4395

4396

<dt>SQLITE_LIMIT_VDBE_OP</dt>

4397

<dd>The maximum number of instructions in a virtual machine program

4398

used to implement an SQL statement. This limit is not currently

4399

enforced, though that might be added in some future release of

4400

SQLite.</dd></p>

4401

4402

4403

<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>

4404

<dd>The maximum number of arguments on a function.</dd></p>

4405

4406

4407

<dt>SQLITE_LIMIT_ATTACHED</dt>

4408

<dd>The maximum number of <a href="lang_attach.html">attached databases</a>.</dd></p>

4409

4410

4411

4412

<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>

4413

<dd>The maximum length of the pattern argument to the <a href="lang_expr.html#like">LIKE</a> or

4414

<a href="lang_expr.html#glob">GLOB</a> operators.</dd></p>

4415

4416

4417

4418

<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>

4419

<dd>The maximum index number of any <a href="lang_expr.html#varparam">parameter</a> in an SQL statement.</p>

4420

4421

4422

<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>

4423

<dd>The maximum depth of recursion for triggers.</dd>

4424

</dl>

4425

</p><hr><a name="SQLITE_DBSTATUS options"></a>

4426

<h2>Status Parameters for database connections</h2><blockquote><pre>#define SQLITE_DBSTATUS_LOOKASIDE_USED 0

4427

#define SQLITE_DBSTATUS_CACHE_USED 1

4428

#define SQLITE_DBSTATUS_SCHEMA_USED 2

4429

#define SQLITE_DBSTATUS_STMT_USED 3

4430

#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4

4431

#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5

4432

#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6

4433

#define SQLITE_DBSTATUS_CACHE_HIT 7

4434

#define SQLITE_DBSTATUS_CACHE_MISS 8

4435

#define SQLITE_DBSTATUS_CACHE_WRITE 9

4436

#define SQLITE_DBSTATUS_MAX 9 /* Largest defined DBSTATUS */

4437

</pre></blockquote><p>

4438

These constants are the available integer "verbs" that can be passed as

4439

the second argument to the <a href="#sqlite3_db_status">sqlite3_db_status()</a> interface.</p>

4440

4441

<p>New verbs may be added in future releases of SQLite. Existing verbs

4442

might be discontinued. Applications should check the return code from

4443

<a href="#sqlite3_db_status">sqlite3_db_status()</a> to make sure that the call worked.

4444

The <a href="#sqlite3_db_status">sqlite3_db_status()</a> interface will return a non-zero error code

4445

if a discontinued or unsupported verb is invoked.</p>

4446

4447

<p><dl>

4448

4449

<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>

4450

<dd>This parameter returns the number of lookaside memory slots currently

4451

checked out.</dd></p>

4452

4453

4454

<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>

4455

<dd>This parameter returns the number malloc attempts that were

4456

satisfied using lookaside memory. Only the high-water value is meaningful;

4457

the current value is always zero.</p>

4458

4459

4460

4461

<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>

4462

<dd>This parameter returns the number malloc attempts that might have

4463

been satisfied using lookaside memory but failed due to the amount of

4464

memory requested being larger than the lookaside slot size.

4465

Only the high-water value is meaningful;

4466

the current value is always zero.</p>

4467

4468

4469

4470

<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>

4471

<dd>This parameter returns the number malloc attempts that might have

4472

been satisfied using lookaside memory but failed due to all lookaside

4473

memory already being in use.

4474

Only the high-water value is meaningful;

4475

the current value is always zero.</p>

4476

4477

4478

<dt>SQLITE_DBSTATUS_CACHE_USED</dt>

4479

<dd>This parameter returns the approximate number of of bytes of heap

4480

memory used by all pager caches associated with the database connection.

4481

The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.</p>

4482

4483

4484

<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>

4485

<dd>This parameter returns the approximate number of of bytes of heap

4486

memory used to store the schema for all databases associated

4487

with the connection - main, temp, and any <a href="lang_attach.html">ATTACH</a>-ed databases.

4488

The full amount of memory used by the schemas is reported, even if the

4489

schema memory is shared with other database connections due to

4490

<a href="sharedcache.html">shared cache mode</a> being enabled.

4491

The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.</p>

4492

4493

4494

<dt>SQLITE_DBSTATUS_STMT_USED</dt>

4495

<dd>This parameter returns the approximate number of of bytes of heap

4496

and lookaside memory used by all prepared statements associated with

4497

the database connection.

4498

The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.

4499

</dd></p>

4500

4501

4502

<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>

4503

<dd>This parameter returns the number of pager cache hits that have

4504

occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT

4505

is always 0.

4506

</dd></p>

4507

4508

4509

<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>

4510

<dd>This parameter returns the number of pager cache misses that have

4511

occurred. The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS

4512

is always 0.

4513

</dd></p>

4514

4515

4516

<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>

4517

<dd>This parameter returns the number of dirty cache entries that have

4518

been written to disk. Specifically, the number of pages written to the

4519

wal file in wal mode databases, or the number of pages written to the

4520

database file in rollback mode databases. Any pages written as part of

4521

transaction rollback or database recovery operations are not included.

4522

If an IO or other error occurs while writing a page to disk, the effect

4523

on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined. The

4524

highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.

4525

</dd>

4526

</dl>

4527

</p><hr><a name="SQLITE_STMTSTATUS counter"></a>

4528

<h2>Status Parameters for prepared statements</h2><blockquote><pre>#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1

4529

#define SQLITE_STMTSTATUS_SORT 2

4530

#define SQLITE_STMTSTATUS_AUTOINDEX 3

4531

</pre></blockquote><p>

4532

These preprocessor macros define integer codes that name counter

4533

values associated with the <a href="#sqlite3_stmt_status">sqlite3_stmt_status()</a> interface.

4534

The meanings of the various counters are as follows:</p>

4535

4536

<p><dl>

4537

4538

<dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>

4539

<dd>This is the number of times that SQLite has stepped forward in

4540

a table as part of a full table scan. Large numbers for this counter

4541

may indicate opportunities for performance improvement through

4542

careful use of indices.</dd></p>

4543

4544

4545

<dt>SQLITE_STMTSTATUS_SORT</dt>

4546

<dd>This is the number of sort operations that have occurred.

4547

A non-zero value in this counter may indicate an opportunity to

4548

improvement performance through careful use of indices.</dd></p>

4549

4550

4551

<dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>

4552

<dd>This is the number of rows inserted into transient indices that

4553

were created automatically in order to help joins run faster.

4554

A non-zero value in this counter may indicate an opportunity to

4555

improvement performance by adding permanent indices that do not

4556

need to be reinitialized each time the statement is run.</dd>

4557

</dl>

4558

</p><hr><a name="sqlite3_int64"></a>

4559

<h2>64-Bit Integer Types</h2><blockquote><pre>#ifdef SQLITE_INT64_TYPE

4560

typedef SQLITE_INT64_TYPE sqlite_int64;

4561

typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

4562

#elif defined(_MSC_VER) || defined(__BORLANDC__)

4563

typedef __int64 sqlite_int64;

4564

typedef unsigned __int64 sqlite_uint64;

4565

#else

4566

typedef long long int sqlite_int64;

4567

typedef unsigned long long int sqlite_uint64;

4568

#endif

4569

typedef sqlite_int64 sqlite3_int64;

4570

typedef sqlite_uint64 sqlite3_uint64;

4571

</pre></blockquote><p>

4572

Because there is no cross-platform way to specify 64-bit integer types

4573

SQLite includes typedefs for 64-bit signed and unsigned integers.</p>

4574

4575

<p>The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.

4576

The sqlite_int64 and sqlite_uint64 types are supported for backwards

4577

compatibility only.</p>

4578

4579

<p>The sqlite3_int64 and sqlite_int64 types can store integer values

4580

between -9223372036854775808 and +9223372036854775807 inclusive. The

4581

sqlite3_uint64 and sqlite_uint64 types can store integer values

4582

between 0 and +18446744073709551615 inclusive.

4583

</p><hr><a name="sqlite3_module"></a>

4584

<h2>Virtual Table Object</h2><blockquote><pre>struct sqlite3_module {

4585

int iVersion;

4586

int (*xCreate)(sqlite3*, void *pAux,

4587

int argc, const char *const*argv,

4588

sqlite3_vtab **ppVTab, char**);

4589

int (*xConnect)(sqlite3*, void *pAux,

4590

int argc, const char *const*argv,

4591

sqlite3_vtab **ppVTab, char**);

4592

int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);

4593

int (*xDisconnect)(sqlite3_vtab *pVTab);

4594

int (*xDestroy)(sqlite3_vtab *pVTab);

4595

int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);

4596

int (*xClose)(sqlite3_vtab_cursor*);

4597

int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,

4598

int argc, sqlite3_value **argv);

4599

int (*xNext)(sqlite3_vtab_cursor*);

4600

int (*xEof)(sqlite3_vtab_cursor*);

4601

int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);

4602

int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);

4603

int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);

4604

int (*xBegin)(sqlite3_vtab *pVTab);

4605

int (*xSync)(sqlite3_vtab *pVTab);

4606

int (*xCommit)(sqlite3_vtab *pVTab);

4607

int (*xRollback)(sqlite3_vtab *pVTab);

4608

int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,

4609

void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),

4610

void **ppArg);

4611

int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);

4612

/* The methods above are in version 1 of the sqlite_module object. Those

4613

** below are for version 2 and greater. */

4614

int (*xSavepoint)(sqlite3_vtab *pVTab, int);

4615

int (*xRelease)(sqlite3_vtab *pVTab, int);

4616

int (*xRollbackTo)(sqlite3_vtab *pVTab, int);

4617

};

4618

</pre></blockquote><p>

4619

This structure, sometimes called a "virtual table module",

4620

defines the implementation of a <a href="vtab.html">virtual tables</a>.

4621

This structure consists mostly of methods for the module.</p>

4622

4623

<p>A virtual table module is created by filling in a persistent

4624

instance of this structure and passing a pointer to that instance

4625

to <a href="#sqlite3_create_module">sqlite3_create_module()</a> or <a href="#sqlite3_create_module">sqlite3_create_module_v2()</a>.

4626

The registration remains valid until it is replaced by a different

4627

module or until the <a href="#sqlite3">database connection</a> closes. The content

4628

of this structure must not change while it is registered with

4629

any database connection.

4630

</p><hr><a name="sqlite3_vtab_cursor"></a>

4631

<h2>Virtual Table Cursor Object</h2><blockquote><pre>struct sqlite3_vtab_cursor {

4632

sqlite3_vtab *pVtab; /* Virtual table of this cursor */

4633

/* Virtual table implementations will typically add additional fields */

4634

};

4635

</pre></blockquote><p>

4636

Every <a href="#sqlite3_module">virtual table module</a> implementation uses a subclass of the

4637

following structure to describe cursors that point into the

4638

<a href="vtab.html">virtual table</a> and are used

4639

to loop through the virtual table. Cursors are created using the

4640

<a href="vtab.html#xopen">xOpen</a> method of the module and are destroyed

4641

by the <a href="vtab.html#xclose">xClose</a> method. Cursors are used

4642

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

4643

of the module. Each module implementation will define

4644

the content of a cursor structure to suit its own needs.</p>

4645

4646

<p>This superclass exists in order to define fields of the cursor that

4647

are common to all implementations.

4648

</p><hr><a name="sqlite3_blob"></a>

4649

<h2>A Handle To An Open BLOB</h2><blockquote><pre>typedef struct sqlite3_blob sqlite3_blob;

4650

</pre></blockquote><p>

4651

An instance of this object represents an open BLOB on which

4652

<a href="#sqlite3_blob_open">incremental BLOB I/O</a> can be performed.

4653

Objects of this type are created by <a href="#sqlite3_blob_open">sqlite3_blob_open()</a>

4654

and destroyed by <a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.

4655

The <a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and <a href="#sqlite3_blob_write">sqlite3_blob_write()</a> interfaces

4656

can be used to read or write small subsections of the BLOB.

4657

The <a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface returns the size of the BLOB in bytes.

4658

</p><hr><a name="sqlite3"></a>

4659

<h2>Database Connection Handle</h2><blockquote><pre>typedef struct sqlite3 sqlite3;

4660

</pre></blockquote><p>

4661

Each open SQLite database is represented by a pointer to an instance of

4662

the opaque structure named "sqlite3". It is useful to think of an sqlite3

4663

pointer as an object. The <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open16()</a>, and

4664

<a href="#sqlite3_open">sqlite3_open_v2()</a> interfaces are its constructors, and <a href="#sqlite3_close">sqlite3_close()</a>

4665

is its destructor. There are many other interfaces (such as

4666

<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a>, <a href="#sqlite3_create_function">sqlite3_create_function()</a>, and

4667

<a href="#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> to name but three) that are methods on an

4668

sqlite3 object.

4669

</p><hr><a name="sqlite3_pcache_methods2"></a>

4670

<h2>Application Defined Page Cache.</h2><blockquote><pre>typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;

4671

struct sqlite3_pcache_methods2 {

4672

int iVersion;

4673

void *pArg;

4674

int (*xInit)(void*);

4675

void (*xShutdown)(void*);

4676

sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);

4677

void (*xCachesize)(sqlite3_pcache*, int nCachesize);

4678

int (*xPagecount)(sqlite3_pcache*);

4679

sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);

4680

void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);

4681

void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,

4682

unsigned oldKey, unsigned newKey);

4683

void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);

4684

void (*xDestroy)(sqlite3_pcache*);

4685

void (*xShrink)(sqlite3_pcache*);

4686

};

4687

</pre></blockquote><p>

4688

The <a href="#sqlite3_config">sqlite3_config</a>(<a href="#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>, ...) interface can

4689

register an alternative page cache implementation by passing in an

4690

instance of the sqlite3_pcache_methods2 structure.

4691

In many applications, most of the heap memory allocated by

4692

SQLite is used for the page cache.

4693

By implementing a

4694

custom page cache using this API, an application can better control

4695

the amount of memory consumed by SQLite, the way in which

4696

that memory is allocated and released, and the policies used to

4697

determine exactly which parts of a database file are cached and for

4698

how long.</p>

4699

4700

<p>The alternative page cache mechanism is an

4701

extreme measure that is only needed by the most demanding applications.

4702

The built-in page cache is recommended for most uses.</p>

4703

4704

<p>The contents of the sqlite3_pcache_methods2 structure are copied to an

4705

internal buffer by SQLite within the call to <a href="#sqlite3_config">sqlite3_config</a>. Hence

4706

the application may discard the parameter after the call to

4707

<a href="#sqlite3_config">sqlite3_config()</a> returns.</p>

4708

4709

4710

4711

The xInit() method is called once for each effective

4712

call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>

4713

(usually only once during the lifetime of the process). The xInit()

4714

method is passed a copy of the sqlite3_pcache_methods2.pArg value.

4715

The intent of the xInit() method is to set up global data structures

4716

required by the custom page cache implementation.

4717

If the xInit() method is NULL, then the

4718

built-in default page cache is used instead of the application defined

4719

page cache.</p>

4720

4721

4722

4723

The xShutdown() method is called by <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.

4724

It can be used to clean up

4725

any outstanding resources before process shutdown, if required.

4726

The xShutdown() method may be NULL.</p>

4727

4728

<p>SQLite automatically serializes calls to the xInit method,

4729

so the xInit method need not be threadsafe. The

4730

xShutdown method is only called from <a href="#sqlite3_initialize">sqlite3_shutdown()</a> so it does

4731

not need to be threadsafe either. All other methods must be threadsafe

4732

in multithreaded applications.</p>

4733

4734

<p>SQLite will never invoke xInit() more than once without an intervening

4735

call to xShutdown().</p>

4736

4737

4738

4739

SQLite invokes the xCreate() method to construct a new cache instance.

4740

SQLite will typically create one cache instance for each open database file,

4741

though this is not guaranteed. The

4742

first parameter, szPage, is the size in bytes of the pages that must

4743

be allocated by the cache. szPage will always a power of two. The

4744

second parameter szExtra is a number of bytes of extra storage

4745

associated with each page cache entry. The szExtra parameter will

4746

a number less than 250. SQLite will use the

4747

extra szExtra bytes on each page to store metadata about the underlying

4748

database page on disk. The value passed into szExtra depends

4749

on the SQLite version, the target platform, and how SQLite was compiled.

4750

The third argument to xCreate(), bPurgeable, is true if the cache being

4751

created will be used to cache database pages of a file stored on disk, or

4752

false if it is used for an in-memory database. The cache implementation

4753

does not have to do anything special based with the value of bPurgeable;

4754

it is purely advisory. On a cache where bPurgeable is false, SQLite will

4755

never invoke xUnpin() except to deliberately delete a page.

4756

In other words, calls to xUnpin() on a cache with bPurgeable set to

4757

false will always have the "discard" flag set to true.

4758

Hence, a cache created with bPurgeable false will

4759

never contain any unpinned pages.</p>

4760

4761

4762

4763

The xCachesize() method may be called at any time by SQLite to set the

4764

suggested maximum cache-size (number of pages stored by) the cache

4765

instance passed as the first argument. This is the value configured using

4766

the SQLite "<a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a>" command. As with the bPurgeable

4767

parameter, the implementation is not required to do anything with this

4768

value; it is advisory only.</p>

4769

4770

4771

4772

The xPagecount() method must return the number of pages currently

4773

stored in the cache, both pinned and unpinned.</p>

4774

4775

4776

4777

The xFetch() method locates a page in the cache and returns a pointer to

4778

an sqlite3_pcache_page object associated with that page, or a NULL pointer.

4779

The pBuf element of the returned sqlite3_pcache_page object will be a

4780

pointer to a buffer of szPage bytes used to store the content of a

4781

single database page. The pExtra element of sqlite3_pcache_page will be

4782

a pointer to the szExtra bytes of extra storage that SQLite has requested

4783

for each entry in the page cache.</p>

4784

4785

<p>The page to be fetched is determined by the key. The minimum key value

4786

is 1. After it has been retrieved using xFetch, the page is considered

4787

to be "pinned".</p>

4788

4789

<p>If the requested page is already in the page cache, then the page cache

4790

implementation must return a pointer to the page buffer with its content

4791

intact. If the requested page is not already in the cache, then the

4792

cache implementation should use the value of the createFlag

4793

parameter to help it determined what action to take:</p>

4794

4795

4796

<tr><th> createFlag <th> Behaviour when page is not already in cache

4797

<tr><td> 0 <td> Do not allocate a new page. Return NULL.

4798

<tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.

4799

Otherwise return NULL.

4800

<tr><td> 2 <td> Make every effort to allocate a new page. Only return

4801

NULL if allocating a new page is effectively impossible.

4802

</table></p>

4803

4804

<p>SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite

4805

will only use a createFlag of 2 after a prior call with a createFlag of 1

4806

failed. In between the to xFetch() calls, SQLite may

4807

attempt to unpin one or more cache pages by spilling the content of

4808

pinned pages to disk and synching the operating system disk cache.</p>

4809

4810

4811

4812

xUnpin() is called by SQLite with a pointer to a currently pinned page

4813

as its second argument. If the third parameter, discard, is non-zero,

4814

then the page must be evicted from the cache.

4815

If the discard parameter is

4816

zero, then the page may be discarded or retained at the discretion of

4817

page cache implementation. The page cache implementation

4818

may choose to evict unpinned pages at any time.</p>

4819

4820

<p>The cache must not perform any reference counting. A single

4821

call to xUnpin() unpins the page regardless of the number of prior calls

4822

to xFetch().</p>

4823

4824

4825

4826

The xRekey() method is used to change the key value associated with the

4827

page passed as the second argument. If the cache

4828

previously contains an entry associated with newKey, it must be

4829

discarded. Any prior cache entry associated with newKey is guaranteed not

4830

to be pinned.</p>

4831

4832

<p>When SQLite calls the xTruncate() method, the cache must discard all

4833

existing cache entries with page numbers (keys) greater than or equal

4834

to the value of the iLimit parameter passed to xTruncate(). If any

4835

of these pages are pinned, they are implicitly unpinned, meaning that

4836

they can be safely discarded.</p>

4837

4838

4839

4840

The xDestroy() method is used to delete a cache allocated by xCreate().

4841

All resources associated with the specified cache should be freed. After

4842

calling the xDestroy() method, SQLite considers the <a href="#sqlite3_pcache">sqlite3_pcache*</a>

4843

handle invalid, and will not use it with any other sqlite3_pcache_methods2

4844

functions.</p>

4845

4846

4847

4848

SQLite invokes the xShrink() method when it wants the page cache to

4849

free up as much of heap memory as possible. The page cache implementation

4850

is not obligated to free any memory, but well-behaved implementations should

4851

do their best.

4852

</p><hr><a name="sqlite3_stmt"></a>

4853

<h2>SQL Statement Object</h2><blockquote><pre>typedef struct sqlite3_stmt sqlite3_stmt;

4854

</pre></blockquote><p>

4855

An instance of this object represents a single SQL statement.

4856

This object is variously known as a "prepared statement" or a

4857

"compiled SQL statement" or simply as a "statement".</p>

4858

4859

<p>The life of a statement object goes something like this:</p>

4860

4861

<p><ol>

4862

<li> Create the object using <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or a related

4863

function.

4864

<li> Bind values to <a href="#sqlite3_bind_blob">host parameters</a> using the sqlite3_bind_*()

4865

interfaces.

4866

<li> Run the SQL by calling <a href="#sqlite3_step">sqlite3_step()</a> one or more times.

4867

<li> Reset the statement using <a href="#sqlite3_reset">sqlite3_reset()</a> then go back

4868

to step 2. Do this zero or more times.

4869

<li> Destroy the object using <a href="#sqlite3_finalize">sqlite3_finalize()</a>.

4870

</ol></p>

4871

4872

<p>Refer to documentation on individual methods above for additional

4873

information.

4874

</p><hr><a name="sqlite3_value"></a>

4875

<h2>Dynamically Typed Value Object</h2><blockquote><pre>typedef struct Mem sqlite3_value;

4876

</pre></blockquote><p>

4877

SQLite uses the sqlite3_value object to represent all values

4878

that can be stored in a database table. SQLite uses dynamic typing

4879

for the values it stores. Values stored in sqlite3_value objects

4880

can be integers, floating point values, strings, BLOBs, or NULL.</p>

4881

4882

<p>An sqlite3_value object may be either "protected" or "unprotected".

4883

Some interfaces require a protected sqlite3_value. Other interfaces

4884

will accept either a protected or an unprotected sqlite3_value.

4885

Every interface that accepts sqlite3_value arguments specifies

4886

whether or not it requires a protected sqlite3_value.</p>

4887

4888

<p>The terms "protected" and "unprotected" refer to whether or not

4889

a mutex is held. An internal mutex is held for a protected

4890

sqlite3_value object but no mutex is held for an unprotected

4891

sqlite3_value object. If SQLite is compiled to be single-threaded

4892

(with <a href="compile.html#threadsafe">SQLITE_THREADSAFE=0</a> and with <a href="#sqlite3_threadsafe">sqlite3_threadsafe()</a> returning 0)

4893

or if SQLite is run in one of reduced mutex modes

4894

<a href="#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a> or <a href="#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>

4895

then there is no distinction between protected and unprotected

4896

sqlite3_value objects and they can be used interchangeably. However,

4897

for maximum code portability it is recommended that applications

4898

still make the distinction between protected and unprotected

4899

sqlite3_value objects even when not strictly required.</p>

4900

4901

<p>The sqlite3_value objects that are passed as parameters into the

4902

implementation of <a href="#sqlite3_create_function">application-defined SQL functions</a> are protected.

4903

The sqlite3_value object returned by

4904

<a href="#sqlite3_column_blob">sqlite3_column_value()</a> is unprotected.

4905

Unprotected sqlite3_value objects may only be used with

4906

<a href="#sqlite3_result_blob">sqlite3_result_value()</a> and <a href="#sqlite3_bind_blob">sqlite3_bind_value()</a>.

4907

The <a href="#sqlite3_value_blob">sqlite3_value_type()</a> family of

4908

interfaces require protected sqlite3_value objects.

4909

</p><hr><a name="sqlite3_aggregate_count"></a>

4910

<h2>Deprecated Functions</h2><blockquote><pre>#ifndef SQLITE_OMIT_DEPRECATED

4911

int sqlite3_aggregate_count(sqlite3_context*);

4912

int sqlite3_expired(sqlite3_stmt*);

4913

int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);

4914

int sqlite3_global_recover(void);

4915

void sqlite3_thread_cleanup(void);

4916

int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);

4917

#endif

4918

</pre></blockquote><p>

4919

These functions are <a href="capi3ref.html">deprecated</a>. In order to maintain

4920

backwards compatibility with older code, these functions continue

4921

to be supported. However, new applications should avoid

4922

the use of these functions. To help encourage people to avoid

4923

using these functions, we are not going to tell you what they do.

4924

</p><hr><a name="sqlite3_backup_finish"></a>

4925

<h2>Online Backup API.</h2><blockquote><pre>sqlite3_backup *sqlite3_backup_init(

4926

sqlite3 *pDest, /* Destination database handle */

4927

const char *zDestName, /* Destination database name */

4928

sqlite3 *pSource, /* Source database handle */

4929

const char *zSourceName /* Source database name */

4930

);

4931

int sqlite3_backup_step(sqlite3_backup *p, int nPage);

4932

int sqlite3_backup_finish(sqlite3_backup *p);

4933

int sqlite3_backup_remaining(sqlite3_backup *p);

4934

int sqlite3_backup_pagecount(sqlite3_backup *p);

4935

</pre></blockquote><p>

4936

The backup API copies the content of one database into another.

4937

It is useful either for creating backups of databases or

4938

for copying in-memory databases to or from persistent files.</p>

4939

4940

<p>See Also: <a href="backup.html">Using the SQLite Online Backup API</a></p>

4941

4942

<p>SQLite holds a write transaction open on the destination database file

4943

for the duration of the backup operation.

4944

The source database is read-locked only while it is being read;

4945

it is not locked continuously for the entire backup operation.

4946

Thus, the backup may be performed on a live source database without

4947

preventing other database connections from

4948

reading or writing to the source database while the backup is underway.</p>

4949

4950

<p>To perform a backup operation:

4951

<ol>

4952

<li><b>sqlite3_backup_init()</b> is called once to initialize the

4953

backup,

4954

<li><b>sqlite3_backup_step()</b> is called one or more times to transfer

4955

the data between the two databases, and finally

4956

<li><b>sqlite3_backup_finish()</b> is called to release all resources

4957

associated with the backup operation.

4958

</ol>

4959

There should be exactly one call to sqlite3_backup_finish() for each

4960

successful call to sqlite3_backup_init().</p>

4961

4962

4963

<b>sqlite3_backup_init()</b></p>

4964

4965

<p>The D and N arguments to sqlite3_backup_init(D,N,S,M) are the

4966

<a href="#sqlite3">database connection</a> associated with the destination database

4967

and the database name, respectively.

4968

The database name is "main" for the main database, "temp" for the

4969

temporary database, or the name specified after the AS keyword in

4970

an <a href="lang_attach.html">ATTACH</a> statement for an attached database.

4971

The S and M arguments passed to

4972

sqlite3_backup_init(D,N,S,M) identify the <a href="#sqlite3">database connection</a>

4973

and database name of the source database, respectively.

4974

The source and destination <a href="#sqlite3">database connections</a> (parameters S and D)

4975

must be different or else sqlite3_backup_init(D,N,S,M) will fail with

4976

an error.</p>

4977

4978

<p>If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is

4979

returned and an error code and error message are stored in the

4980

destination <a href="#sqlite3">database connection</a> D.

4981

The error code and message for the failed call to sqlite3_backup_init()

4982

can be retrieved using the <a href="#sqlite3_errcode">sqlite3_errcode()</a>, <a href="#sqlite3_errcode">sqlite3_errmsg()</a>, and/or

4983

<a href="#sqlite3_errcode">sqlite3_errmsg16()</a> functions.

4984

A successful call to sqlite3_backup_init() returns a pointer to an

4985

<a href="#sqlite3_backup">sqlite3_backup</a> object.

4986

The <a href="#sqlite3_backup">sqlite3_backup</a> object may be used with the sqlite3_backup_step() and

4987

sqlite3_backup_finish() functions to perform the specified backup

4988

operation.</p>

4989

4990

4991

<b>sqlite3_backup_step()</b></p>

4992

4993

<p>Function sqlite3_backup_step(B,N) will copy up to N pages between

4994

the source and destination databases specified by <a href="#sqlite3_backup">sqlite3_backup</a> object B.

4995

If N is negative, all remaining source pages are copied.

4996

If sqlite3_backup_step(B,N) successfully copies N pages and there

4997

are still more pages to be copied, then the function returns <a href="#SQLITE_ABORT">SQLITE_OK</a>.

4998

If sqlite3_backup_step(B,N) successfully finishes copying all pages

4999

from source to destination, then it returns <a href="#SQLITE_ABORT">SQLITE_DONE</a>.

5000

If an error occurs while running sqlite3_backup_step(B,N),

5001

then an <a href="#SQLITE_ABORT">error code</a> is returned. As well as <a href="#SQLITE_ABORT">SQLITE_OK</a> and

5002

<a href="#SQLITE_ABORT">SQLITE_DONE</a>, a call to sqlite3_backup_step() may return <a href="#SQLITE_ABORT">SQLITE_READONLY</a>,

5003

<a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, <a href="#SQLITE_ABORT">SQLITE_LOCKED</a>, or an

5004

<a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_XXX</a> extended error code.</p>

5005

5006

<p>The sqlite3_backup_step() might return <a href="#SQLITE_ABORT">SQLITE_READONLY</a> if

5007

<ol>

5008

<li> the destination database was opened read-only, or

5009

<li> the destination database is using write-ahead-log journaling

5010

and the destination and source page sizes differ, or

5011

<li> the destination database is an in-memory database and the

5012

destination and source page sizes differ.

5013

</ol></p>

5014

5015

<p>If sqlite3_backup_step() cannot obtain a required file-system lock, then

5016

the <a href="#sqlite3_busy_handler">busy-handler function</a>

5017

is invoked (if one is specified). If the

5018

busy-handler returns non-zero before the lock is available, then

5019

<a href="#SQLITE_ABORT">SQLITE_BUSY</a> is returned to the caller. In this case the call to

5020

sqlite3_backup_step() can be retried later. If the source

5021

<a href="#sqlite3">database connection</a>

5022

is being used to write to the source database when sqlite3_backup_step()

5023

is called, then <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> is returned immediately. Again, in this

5024

case the call to sqlite3_backup_step() can be retried later on. If

5025

<a href="#SQLITE_ABORT_ROLLBACK">SQLITE_IOERR_XXX</a>, <a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, or

5026

<a href="#SQLITE_ABORT">SQLITE_READONLY</a> is returned, then

5027

there is no point in retrying the call to sqlite3_backup_step(). These

5028

errors are considered fatal. The application must accept

5029

that the backup operation has failed and pass the backup operation handle

5030

to the sqlite3_backup_finish() to release associated resources.</p>

5031

5032

<p>The first call to sqlite3_backup_step() obtains an exclusive lock

5033

on the destination file. The exclusive lock is not released until either

5034

sqlite3_backup_finish() is called or the backup operation is complete

5035

and sqlite3_backup_step() returns <a href="#SQLITE_ABORT">SQLITE_DONE</a>. Every call to

5036

sqlite3_backup_step() obtains a <a href="lockingv3.html#shared_lock">shared lock</a> on the source database that

5037

lasts for the duration of the sqlite3_backup_step() call.

5038

Because the source database is not locked between calls to

5039

sqlite3_backup_step(), the source database may be modified mid-way

5040

through the backup process. If the source database is modified by an

5041

external process or via a database connection other than the one being

5042

used by the backup operation, then the backup will be automatically

5043

restarted by the next call to sqlite3_backup_step(). If the source

5044

database is modified by the using the same database connection as is used

5045

by the backup operation, then the backup database is automatically

5046

updated at the same time.</p>

5047

5048

5049

<b>sqlite3_backup_finish()</b></p>

5050

5051

<p>When sqlite3_backup_step() has returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>, or when the

5052

application wishes to abandon the backup operation, the application

5053

should destroy the <a href="#sqlite3_backup">sqlite3_backup</a> by passing it to sqlite3_backup_finish().

5054

The sqlite3_backup_finish() interfaces releases all

5055

resources associated with the <a href="#sqlite3_backup">sqlite3_backup</a> object.

5056

If sqlite3_backup_step() has not yet returned <a href="#SQLITE_ABORT">SQLITE_DONE</a>, then any

5057

active write-transaction on the destination database is rolled back.

5058

The <a href="#sqlite3_backup">sqlite3_backup</a> object is invalid

5059

and may not be used following a call to sqlite3_backup_finish().</p>

5060

5061

<p>The value returned by sqlite3_backup_finish is <a href="#SQLITE_ABORT">SQLITE_OK</a> if no

5062

sqlite3_backup_step() errors occurred, regardless or whether or not

5063

sqlite3_backup_step() completed.

5064

If an out-of-memory condition or IO error occurred during any prior

5065

sqlite3_backup_step() call on the same <a href="#sqlite3_backup">sqlite3_backup</a> object, then

5066

sqlite3_backup_finish() returns the corresponding <a href="#SQLITE_ABORT">error code</a>.</p>

5067

5068

<p>A return of <a href="#SQLITE_ABORT">SQLITE_BUSY</a> or <a href="#SQLITE_ABORT">SQLITE_LOCKED</a> from sqlite3_backup_step()

5069

is not a permanent error and does not affect the return value of

5070

sqlite3_backup_finish().</p>

5071

5072

5073

5074

5075

<b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b></p>

5076

5077

<p>Each call to sqlite3_backup_step() sets two values inside

5078

the <a href="#sqlite3_backup">sqlite3_backup</a> object: the number of pages still to be backed

5079

up and the total number of pages in the source database file.

5080

The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces

5081

retrieve these two values, respectively.</p>

5082

5083

<p>The values returned by these functions are only updated by

5084

sqlite3_backup_step(). If the source database is modified during a backup

5085

operation, then the values are not updated to account for any extra

5086

pages that need to be updated or the size of the source database file

5087

changing.</p>

5088

5089

<p><b>Concurrent Usage of Database Handles</b></p>

5090

5091

<p>The source <a href="#sqlite3">database connection</a> may be used by the application for other

5092

purposes while a backup operation is underway or being initialized.

5093

If SQLite is compiled and configured to support threadsafe database

5094

connections, then the source database connection may be used concurrently

5095

from within other threads.</p>

5096

5097

<p>However, the application must guarantee that the destination

5098

<a href="#sqlite3">database connection</a> is not passed to any other API (by any thread) after

5099

sqlite3_backup_init() is called and before the corresponding call to

5100

sqlite3_backup_finish(). SQLite does not currently check to see

5101

if the application incorrectly accesses the destination <a href="#sqlite3">database connection</a>

5102

and so no error code is reported, but the operations may malfunction

5103

nevertheless. Use of the destination database connection while a

5104

backup is in progress might also also cause a mutex deadlock.</p>

5105

5106

<p>If running in <a href="sharedcache.html">shared cache mode</a>, the application must

5107

guarantee that the shared cache used by the destination database

5108

is not accessed while the backup is running. In practice this means

5109

that the application must guarantee that the disk file being

5110

backed up to is not accessed by any connection within the process,

5111

not just the specific connection that was passed to sqlite3_backup_init().</p>

5112

5113

<p>The <a href="#sqlite3_backup">sqlite3_backup</a> object itself is partially threadsafe. Multiple

5114

threads may safely make multiple concurrent calls to sqlite3_backup_step().

5115

However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()

5116

APIs are not strictly speaking threadsafe. If they are invoked at the

5117

same time as another thread is invoking sqlite3_backup_step() it is

5118

possible that they return invalid values.

5119

</p><hr><a name="sqlite3_collation_needed"></a>

5120

<h2>Collation Needed Callbacks</h2><blockquote><pre>int sqlite3_collation_needed(

5121

sqlite3*,

5122

void*,

5123

void(*)(void*,sqlite3*,int eTextRep,const char*)

5124

);

5125

int sqlite3_collation_needed16(

5126

sqlite3*,

5127

void*,

5128

void(*)(void*,sqlite3*,int eTextRep,const void*)

5129

);

5130

</pre></blockquote><p>

5131

To avoid having to register all collation sequences before a database

5132

can be used, a single callback function may be registered with the

5133

<a href="#sqlite3">database connection</a> to be invoked whenever an undefined collation

5134

sequence is required.</p>

5135

5136

<p>If the function is registered using the sqlite3_collation_needed() API,

5137

then it is passed the names of undefined collation sequences as strings

5138

encoded in UTF-8. If sqlite3_collation_needed16() is used,

5139

the names are passed as UTF-16 in machine native byte order.

5140

A call to either function replaces the existing collation-needed callback.</p>

5141

5142

<p>When the callback is invoked, the first argument passed is a copy

5143

of the second argument to sqlite3_collation_needed() or

5144

sqlite3_collation_needed16(). The second argument is the database

5145

connection. The third argument is one of <a href="#SQLITE_ANY">SQLITE_UTF8</a>, <a href="#SQLITE_ANY">SQLITE_UTF16BE</a>,

5146

or <a href="#SQLITE_ANY">SQLITE_UTF16LE</a>, indicating the most desirable form of the collation

5147

sequence function required. The fourth parameter is the name of the

5148

required collation sequence.</p>

5149

5150

<p>The callback function should register the desired collation using

5151

<a href="#sqlite3_create_collation">sqlite3_create_collation()</a>, <a href="#sqlite3_create_collation">sqlite3_create_collation16()</a>, or

5152

<a href="#sqlite3_create_collation">sqlite3_create_collation_v2()</a>.

5153

</p><hr><a name="sqlite3_column_database_name"></a>

5154

<h2>Source Of Data In A Query Result</h2><blockquote><pre>const char *sqlite3_column_database_name(sqlite3_stmt*,int);

5155

const void *sqlite3_column_database_name16(sqlite3_stmt*,int);

5156

const char *sqlite3_column_table_name(sqlite3_stmt*,int);

5157

const void *sqlite3_column_table_name16(sqlite3_stmt*,int);

5158

const char *sqlite3_column_origin_name(sqlite3_stmt*,int);

5159

const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);

5160

</pre></blockquote><p>

5161

These routines provide a means to determine the database, table, and

5162

table column that is the origin of a particular result column in

5163

<a href="lang_select.html">SELECT</a> statement.

5164

The name of the database or table or column can be returned as

5165

either a UTF-8 or UTF-16 string. The _database_ routines return

5166

the database name, the _table_ routines return the table name, and

5167

the origin_ routines return the column name.

5168

The returned string is valid until the <a href="#sqlite3_stmt">prepared statement</a> is destroyed

5169

using <a href="#sqlite3_finalize">sqlite3_finalize()</a> or until the statement is automatically

5170

reprepared by the first call to <a href="#sqlite3_step">sqlite3_step()</a> for a particular run

5171

or until the same information is requested

5172

again in a different encoding.</p>

5173

5174

<p>The names returned are the original un-aliased names of the

5175

database, table, and column.</p>

5176

5177

<p>The first argument to these interfaces is a <a href="#sqlite3_stmt">prepared statement</a>.

5178

These functions return information about the Nth result column returned by

5179

the statement, where N is the second function argument.

5180

The left-most column is column 0 for these routines.</p>

5181

5182

<p>If the Nth column returned by the statement is an expression or

5183

subquery and is not a column value, then all of these functions return

5184

NULL. These routine might also return NULL if a memory allocation error

5185

occurs. Otherwise, they return the name of the attached database, table,

5186

or column that query result column was extracted from.</p>

5187

5188

<p>As with all other SQLite APIs, those whose names end with "16" return

5189

UTF-16 encoded strings and the other functions return UTF-8.</p>

5190

5191

<p>These APIs are only available if the library was compiled with the

5192

<a href="compile.html#enable_column_metadata">SQLITE_ENABLE_COLUMN_METADATA</a> C-preprocessor symbol.</p>

5193

5194

<p>If two or more threads call one or more of these routines against the same

5195

prepared statement and column at the same time then the results are

5196

undefined.</p>

5197

5198

<p>If two or more threads call one or more

5199

<a href="#sqlite3_column_database_name">column metadata interfaces</a>

5200

for the same <a href="#sqlite3_stmt">prepared statement</a> and result column

5201

at the same time then the results are undefined.

5202

</p><hr><a name="sqlite3_column_decltype"></a>

5203

<h2>Declared Datatype Of A Query Result</h2><blockquote><pre>const char *sqlite3_column_decltype(sqlite3_stmt*,int);

5204

const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

5205

</pre></blockquote><p>

5206

The first parameter is a <a href="#sqlite3_stmt">prepared statement</a>.

5207

If this statement is a <a href="lang_select.html">SELECT</a> statement and the Nth column of the

5208

returned result set of that <a href="lang_select.html">SELECT</a> is a table column (not an

5209

expression or subquery) then the declared type of the table

5210

column is returned. If the Nth column of the result set is an

5211

expression or subquery, then a NULL pointer is returned.

5212

The returned string is always UTF-8 encoded.</p>

5213

5214

<p>For example, given the database schema:</p>

5215

5216

<p>CREATE TABLE t1(c1 VARIANT);</p>

5217

5218

<p>and the following statement to be compiled:</p>

5219

5220

<p>SELECT c1 + 1, c1 FROM t1;</p>

5221

5222

<p>this routine would return the string "VARIANT" for the second result

5223

column (i==1), and a NULL pointer for the first result column (i==0).</p>

5224

5225

<p>SQLite uses dynamic run-time typing. So just because a column

5226

is declared to contain a particular type does not mean that the

5227

data stored in that column is of the declared type. SQLite is

5228

strongly typed, but the typing is dynamic not static. Type

5229

is associated with individual values, not with the containers

5230

used to hold those values.

5231

</p><hr><a name="sqlite3_column_name"></a>

5232

<h2>Column Names In A Result Set</h2><blockquote><pre>const char *sqlite3_column_name(sqlite3_stmt*, int N);

5233

const void *sqlite3_column_name16(sqlite3_stmt*, int N);

5234

</pre></blockquote><p>

5235

These routines return the name assigned to a particular column

5236

in the result set of a <a href="lang_select.html">SELECT</a> statement. The sqlite3_column_name()

5237

interface returns a pointer to a zero-terminated UTF-8 string

5238

and sqlite3_column_name16() returns a pointer to a zero-terminated

5239

UTF-16 string. The first parameter is the <a href="#sqlite3_stmt">prepared statement</a>

5240

that implements the <a href="lang_select.html">SELECT</a> statement. The second parameter is the

5241

column number. The leftmost column is number 0.</p>

5242

5243

<p>The returned string pointer is valid until either the <a href="#sqlite3_stmt">prepared statement</a>

5244

is destroyed by <a href="#sqlite3_finalize">sqlite3_finalize()</a> or until the statement is automatically

5245

reprepared by the first call to <a href="#sqlite3_step">sqlite3_step()</a> for a particular run

5246

or until the next call to

5247

sqlite3_column_name() or sqlite3_column_name16() on the same column.</p>

5248

5249

<p>If sqlite3_malloc() fails during the processing of either routine

5250

(for example during a conversion from UTF-8 to UTF-16) then a

5251

NULL pointer is returned.</p>

5252

5253

<p>The name of a result column is the value of the "AS" clause for

5254

that column, if there is an AS clause. If there is no AS clause

5255

then the name of the column is unspecified and may change from

5256

one release of SQLite to the next.

5257

</p><hr><a name="sqlite3_commit_hook"></a>

5258

<h2>Commit And Rollback Notification Callbacks</h2><blockquote><pre>void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);

5259

void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);

5260

</pre></blockquote><p>

5261

The sqlite3_commit_hook() interface registers a callback

5262

function to be invoked whenever a transaction is <a href="lang_transaction.html">committed</a>.

5263

Any callback set by a previous call to sqlite3_commit_hook()

5264

for the same database connection is overridden.

5265

The sqlite3_rollback_hook() interface registers a callback

5266

function to be invoked whenever a transaction is <a href="lang_transaction.html">rolled back</a>.

5267

Any callback set by a previous call to sqlite3_rollback_hook()

5268

for the same database connection is overridden.

5269

The pArg argument is passed through to the callback.

5270

If the callback on a commit hook function returns non-zero,

5271

then the commit is converted into a rollback.</p>

5272

5273

<p>The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions

5274

return the P argument from the previous call of the same function

5275

on the same <a href="#sqlite3">database connection</a> D, or NULL for

5276

the first call for each function on D.</p>

5277

5278

<p>The commit and rollback hook callbacks are not reentrant.

5279

The callback implementation must not do anything that will modify

5280

the database connection that invoked the callback. Any actions

5281

to modify the database connection must be deferred until after the

5282

completion of the <a href="#sqlite3_step">sqlite3_step()</a> call that triggered the commit

5283

or rollback hook in the first place.

5284

Note that running any other SQL statements, including SELECT statements,

5285

or merely calling <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and <a href="#sqlite3_step">sqlite3_step()</a> will modify

5286

the database connections for the meaning of "modify" in this paragraph.</p>

5287

5288

<p>Registering a NULL function disables the callback.</p>

5289

5290

<p>When the commit hook callback routine returns zero, the <a href="lang_transaction.html">COMMIT</a>

5291

operation is allowed to continue normally. If the commit hook

5292

returns non-zero, then the <a href="lang_transaction.html">COMMIT</a> is converted into a <a href="lang_transaction.html">ROLLBACK</a>.

5293

The rollback hook is invoked on a rollback that results from a commit

5294

hook returning non-zero, just as it would be with any other rollback.</p>

5295

5296

<p>For the purposes of this API, a transaction is said to have been

5297

rolled back if an explicit "ROLLBACK" statement is executed, or

5298

an error or constraint causes an implicit rollback to occur.

5299

The rollback callback is not invoked if a transaction is

5300

automatically rolled back because the database connection is closed.</p>

5301

5302

<p>See also the <a href="#sqlite3_update_hook">sqlite3_update_hook()</a> interface.

5303

</p><hr><a name="sqlite3_compileoption_get"></a>

5304

<h2>Run-Time Library Compilation Options Diagnostics</h2><blockquote><pre>#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS

5305

int sqlite3_compileoption_used(const char *zOptName);

5306

const char *sqlite3_compileoption_get(int N);

5307

#endif

5308

</pre></blockquote><p>

5309

The sqlite3_compileoption_used() function returns 0 or 1

5310

indicating whether the specified option was defined at

5311

compile time. The SQLITE_ prefix may be omitted from the

5312

option name passed to sqlite3_compileoption_used().</p>

5313

5314

<p>The sqlite3_compileoption_get() function allows iterating

5315

over the list of options that were defined at compile time by

5316

returning the N-th compile time option string. If N is out of range,

5317

sqlite3_compileoption_get() returns a NULL pointer. The SQLITE_

5318

prefix is omitted from any strings returned by

5319

sqlite3_compileoption_get().</p>

5320

5321

<p>Support for the diagnostic functions sqlite3_compileoption_used()

5322

and sqlite3_compileoption_get() may be omitted by specifying the

5323

<a href="compile.html#omit_compileoption_diags">SQLITE_OMIT_COMPILEOPTION_DIAGS</a> option at compile time.</p>

5324

5325

<p>See also: SQL functions <a href="lang_corefunc.html#sqlite_compileoption_used">sqlite_compileoption_used()</a> and

5326

<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>.

5327

</p><hr><a name="sqlite3_complete"></a>

5328

<h2>Determine If An SQL Statement Is Complete</h2><blockquote><pre>int sqlite3_complete(const char *sql);

5329

int sqlite3_complete16(const void *sql);

5330

</pre></blockquote><p>

5331

These routines are useful during command-line input to determine if the

5332

currently entered text seems to form a complete SQL statement or

5333

if additional input is needed before sending the text into

5334

SQLite for parsing. These routines return 1 if the input string

5335

appears to be a complete SQL statement. A statement is judged to be

5336

complete if it ends with a semicolon token and is not a prefix of a

5337

well-formed CREATE TRIGGER statement. Semicolons that are embedded within

5338

string literals or quoted identifier names or comments are not

5339

independent tokens (they are part of the token in which they are

5340

embedded) and thus do not count as a statement terminator. Whitespace

5341

and comments that follow the final semicolon are ignored.</p>

5342

5343

<p>These routines return 0 if the statement is incomplete. If a

5344

memory allocation fails, then SQLITE_NOMEM is returned.</p>

5345

5346

<p>These routines do not parse the SQL statements thus

5347

will not detect syntactically incorrect SQL.</p>

5348

5349

<p>If SQLite has not been initialized using <a href="#sqlite3_initialize">sqlite3_initialize()</a> prior

5350

to invoking sqlite3_complete16() then sqlite3_initialize() is invoked

5351

automatically by sqlite3_complete16(). If that initialization fails,

5352

then the return value from sqlite3_complete16() will be non-zero

5353

regardless of whether or not the input SQL is complete.</p>

5354

5355

<p>The input to <a href="#sqlite3_complete">sqlite3_complete()</a> must be a zero-terminated

5356

UTF-8 string.</p>

5357

5358

<p>The input to <a href="#sqlite3_complete">sqlite3_complete16()</a> must be a zero-terminated

5359

UTF-16 string in native byte order.

5360

</p><hr><a name="sqlite3_create_collation"></a>

5361

<h2>Define New Collating Sequences</h2><blockquote><pre>int sqlite3_create_collation(

5362

sqlite3*,

5363

const char *zName,

5364

int eTextRep,

5365

void *pArg,

5366

int(*xCompare)(void*,int,const void*,int,const void*)

5367

);

5368

int sqlite3_create_collation_v2(

5369

sqlite3*,

5370

const char *zName,

5371

int eTextRep,

5372

void *pArg,

5373

int(*xCompare)(void*,int,const void*,int,const void*),

5374

void(*xDestroy)(void*)

5375

);

5376

int sqlite3_create_collation16(

5377

sqlite3*,

5378

const void *zName,

5379

int eTextRep,

5380

void *pArg,

5381

int(*xCompare)(void*,int,const void*,int,const void*)

5382

);

5383

</pre></blockquote><p>

5384

These functions add, remove, or modify a <a href="datatype3.html#collation">collation</a> associated

5385

with the <a href="#sqlite3">database connection</a> specified as the first argument.</p>

5386

5387

<p>The name of the collation is a UTF-8 string

5388

for sqlite3_create_collation() and sqlite3_create_collation_v2()

5389

and a UTF-16 string in native byte order for sqlite3_create_collation16().

5390

Collation names that compare equal according to <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a> are

5391

considered to be the same name.</p>

5392

5393

<p>The third argument (eTextRep) must be one of the constants:

5394

<ul>

5395

<li> <a href="#SQLITE_ANY">SQLITE_UTF8</a>,

5396

<li> <a href="#SQLITE_ANY">SQLITE_UTF16LE</a>,

5397

<li> <a href="#SQLITE_ANY">SQLITE_UTF16BE</a>,

5398

<li> <a href="#SQLITE_ANY">SQLITE_UTF16</a>, or

5399

<li> <a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a>.

5400

</ul>

5401

The eTextRep argument determines the encoding of strings passed

5402

to the collating function callback, xCallback.

5403

The <a href="#SQLITE_ANY">SQLITE_UTF16</a> and <a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a> values for eTextRep

5404

force strings to be UTF16 with native byte order.

5405

The <a href="#SQLITE_ANY">SQLITE_UTF16_ALIGNED</a> value for eTextRep forces strings to begin

5406

on an even byte address.</p>

5407

5408

<p>The fourth argument, pArg, is an application data pointer that is passed

5409

through as the first argument to the collating function callback.</p>

5410

5411

<p>The fifth argument, xCallback, is a pointer to the collating function.

5412

Multiple collating functions can be registered using the same name but

5413

with different eTextRep parameters and SQLite will use whichever

5414

function requires the least amount of data transformation.

5415

If the xCallback argument is NULL then the collating function is

5416

deleted. When all collating functions having the same name are deleted,

5417

that collation is no longer usable.</p>

5418

5419

<p>The collating function callback is invoked with a copy of the pArg

5420

application data pointer and with two strings in the encoding specified

5421

by the eTextRep argument. The collating function must return an

5422

integer that is negative, zero, or positive

5423

if the first string is less than, equal to, or greater than the second,

5424

respectively. A collating function must always return the same answer

5425

given the same inputs. If two or more collating functions are registered

5426

to the same collation name (using different eTextRep values) then all

5427

must give an equivalent answer when invoked with equivalent strings.

5428

The collating function must obey the following properties for all

5429

strings A, B, and C:</p>

5430

5431

<p><ol>

5432

<li> If A==B then B==A.

5433

<li> If A==B and B==C then A==C.

5434

<li> If A<B THEN B>A.

5435

<li> If A<B and B<C then A<C.

5436

</ol></p>

5437

5438

<p>If a collating function fails any of the above constraints and that

5439

collating function is registered and used, then the behavior of SQLite

5440

is undefined.</p>

5441

5442

<p>The sqlite3_create_collation_v2() works like sqlite3_create_collation()

5443

with the addition that the xDestroy callback is invoked on pArg when

5444

the collating function is deleted.

5445

Collating functions are deleted when they are overridden by later

5446

calls to the collation creation functions or when the

5447

<a href="#sqlite3">database connection</a> is closed using <a href="#sqlite3_close">sqlite3_close()</a>.</p>

5448

5449

<p>The xDestroy callback is <u>not</u> called if the

5450

sqlite3_create_collation_v2() function fails. Applications that invoke

5451

sqlite3_create_collation_v2() with a non-NULL xDestroy argument should

5452

check the return code and dispose of the application data pointer

5453

themselves rather than expecting SQLite to deal with it for them.

5454

This is different from every other SQLite interface. The inconsistency

5455

is unfortunate but cannot be changed without breaking backwards

5456

compatibility.</p>

5457

5458

<p>See also: <a href="#sqlite3_collation_needed">sqlite3_collation_needed()</a> and <a href="#sqlite3_collation_needed">sqlite3_collation_needed16()</a>.

5459

</p><hr><a name="sqlite3_create_module"></a>

5460

<h2>Register A Virtual Table Implementation</h2><blockquote><pre>int sqlite3_create_module(

5461

sqlite3 *db, /* SQLite connection to register module with */

5462

const char *zName, /* Name of the module */

5463

const sqlite3_module *p, /* Methods for the module */

5464

void *pClientData /* Client data for xCreate/xConnect */

5465

);

5466

int sqlite3_create_module_v2(

5467

sqlite3 *db, /* SQLite connection to register module with */

5468

const char *zName, /* Name of the module */

5469

const sqlite3_module *p, /* Methods for the module */

5470

void *pClientData, /* Client data for xCreate/xConnect */

5471

void(*xDestroy)(void*) /* Module destructor function */

5472

);

5473

</pre></blockquote><p>

5474

These routines are used to register a new <a href="#sqlite3_module">virtual table module</a> name.

5475

Module names must be registered before

5476

creating a new <a href="vtab.html">virtual table</a> using the module and before using a

5477

preexisting <a href="vtab.html">virtual table</a> for the module.</p>

5478

5479

<p>The module name is registered on the <a href="#sqlite3">database connection</a> specified

5480

by the first parameter. The name of the module is given by the

5481

second parameter. The third parameter is a pointer to

5482

the implementation of the <a href="#sqlite3_module">virtual table module</a>. The fourth

5483

parameter is an arbitrary client data pointer that is passed through

5484

into the <a href="vtab.html#xcreate">xCreate</a> and <a href="vtab.html#xconnect">xConnect</a> methods of the virtual table module

5485

when a new virtual table is be being created or reinitialized.</p>

5486

5487

<p>The sqlite3_create_module_v2() interface has a fifth parameter which

5488

is a pointer to a destructor for the pClientData. SQLite will

5489

invoke the destructor function (if it is not NULL) when SQLite

5490

no longer needs the pClientData pointer. The destructor will also

5491

be invoked if the call to sqlite3_create_module_v2() fails.

5492

The sqlite3_create_module()

5493

interface is equivalent to sqlite3_create_module_v2() with a NULL

5494

destructor.

5495

</p><hr><a name="sqlite3_errcode"></a>

5496

<h2>Error Codes And Messages</h2><blockquote><pre>int sqlite3_errcode(sqlite3 *db);

5497

int sqlite3_extended_errcode(sqlite3 *db);

5498

const char *sqlite3_errmsg(sqlite3*);

5499

const void *sqlite3_errmsg16(sqlite3*);

5500

</pre></blockquote><p>

5501

The sqlite3_errcode() interface returns the numeric <a href="#SQLITE_ABORT">result code</a> or

5502

<a href="#SQLITE_ABORT_ROLLBACK">extended result code</a> for the most recent failed sqlite3_* API call

5503

associated with a <a href="#sqlite3">database connection</a>. If a prior API call failed

5504

but the most recent API call succeeded, the return value from

5505

sqlite3_errcode() is undefined. The sqlite3_extended_errcode()

5506

interface is the same except that it always returns the

5507

<a href="#SQLITE_ABORT_ROLLBACK">extended result code</a> even when extended result codes are

5508

disabled.</p>

5509

5510

<p>The sqlite3_errmsg() and sqlite3_errmsg16() return English-language

5511

text that describes the error, as either UTF-8 or UTF-16 respectively.

5512

Memory to hold the error message string is managed internally.

5513

The application does not need to worry about freeing the result.

5514

However, the error string might be overwritten or deallocated by

5515

subsequent calls to other SQLite interface functions.</p>

5516

5517

<p>When the serialized <a href="threadsafe.html">threading mode</a> is in use, it might be the

5518

case that a second error occurs on a separate thread in between

5519

the time of the first error and the call to these interfaces.

5520

When that happens, the second error will be reported since these

5521

interfaces always report the most recent result. To avoid

5522

this, each thread can obtain exclusive use of the <a href="#sqlite3">database connection</a> D

5523

by invoking <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter</a>(<a href="#sqlite3_db_mutex">sqlite3_db_mutex</a>(D)) before beginning

5524

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

5525

all calls to the interfaces listed here are completed.</p>

5526

5527

<p>If an interface fails with SQLITE_MISUSE, that means the interface

5528

was invoked incorrectly by the application. In that case, the

5529

error code and message may or may not be set.

5530

</p><hr><a name="sqlite3_free"></a>

5531

<h2>Memory Allocation Subsystem</h2><blockquote><pre>void *sqlite3_malloc(int);

5532

void *sqlite3_realloc(void*, int);

5533

void sqlite3_free(void*);

5534

</pre></blockquote><p>

5535

The SQLite core uses these three routines for all of its own

5536

internal memory allocation needs. "Core" in the previous sentence

5537

does not include operating-system specific VFS implementation. The

5538

Windows VFS uses native malloc() and free() for some operations.</p>

5539

5540

<p>The sqlite3_malloc() routine returns a pointer to a block

5541

of memory at least N bytes in length, where N is the parameter.

5542

If sqlite3_malloc() is unable to obtain sufficient free

5543

memory, it returns a NULL pointer. If the parameter N to

5544

sqlite3_malloc() is zero or negative then sqlite3_malloc() returns

5545

a NULL pointer.</p>

5546

5547

<p>Calling sqlite3_free() with a pointer previously returned

5548

by sqlite3_malloc() or sqlite3_realloc() releases that memory so

5549

that it might be reused. The sqlite3_free() routine is

5550

a no-op if is called with a NULL pointer. Passing a NULL pointer

5551

to sqlite3_free() is harmless. After being freed, memory

5552

should neither be read nor written. Even reading previously freed

5553

memory might result in a segmentation fault or other severe error.

5554

Memory corruption, a segmentation fault, or other severe error

5555

might result if sqlite3_free() is called with a non-NULL pointer that

5556

was not obtained from sqlite3_malloc() or sqlite3_realloc().</p>

5557

5558

<p>The sqlite3_realloc() interface attempts to resize a

5559

prior memory allocation to be at least N bytes, where N is the

5560

second parameter. The memory allocation to be resized is the first

5561

parameter. If the first parameter to sqlite3_realloc()

5562

is a NULL pointer then its behavior is identical to calling

5563

sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().

5564

If the second parameter to sqlite3_realloc() is zero or

5565

negative then the behavior is exactly the same as calling

5566

sqlite3_free(P) where P is the first parameter to sqlite3_realloc().

5567

sqlite3_realloc() returns a pointer to a memory allocation

5568

of at least N bytes in size or NULL if sufficient memory is unavailable.

5569

If M is the size of the prior allocation, then min(N,M) bytes

5570

of the prior allocation are copied into the beginning of buffer returned

5571

by sqlite3_realloc() and the prior allocation is freed.

5572

If sqlite3_realloc() returns NULL, then the prior allocation

5573

is not freed.</p>

5574

5575

<p>The memory returned by sqlite3_malloc() and sqlite3_realloc()

5576

is always aligned to at least an 8 byte boundary, or to a

5577

4 byte boundary if the <a href="compile.html#4_byte_aligned_malloc">SQLITE_4_BYTE_ALIGNED_MALLOC</a> compile-time

5578

option is used.</p>

5579

5580

<p>In SQLite version 3.5.0 and 3.5.1, it was possible to define

5581

the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in

5582

implementation of these routines to be omitted. That capability

5583

is no longer provided. Only built-in memory allocators can be used.</p>

5584

5585

<p>Prior to SQLite version 3.7.10, the Windows OS interface layer called

5586

the system malloc() and free() directly when converting

5587

filenames between the UTF-8 encoding used by SQLite

5588

and whatever filename encoding is used by the particular Windows

5589

installation. Memory allocation errors were detected, but

5590

they were reported back as <a href="#SQLITE_ABORT">SQLITE_CANTOPEN</a> or

5591

<a href="#SQLITE_ABORT">SQLITE_IOERR</a> rather than <a href="#SQLITE_ABORT">SQLITE_NOMEM</a>.</p>

5592

5593

<p>The pointer arguments to <a href="#sqlite3_free">sqlite3_free()</a> and <a href="#sqlite3_free">sqlite3_realloc()</a>

5594

must be either NULL or else pointers obtained from a prior

5595

invocation of <a href="#sqlite3_free">sqlite3_malloc()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a> that have

5596

not yet been released.</p>

5597

5598

<p>The application must not read or write any part of

5599

a block of memory after it has been released using

5600

<a href="#sqlite3_free">sqlite3_free()</a> or <a href="#sqlite3_free">sqlite3_realloc()</a>.

5601

</p><hr><a name="sqlite3_free_table"></a>

5602

<h2>Convenience Routines For Running Queries</h2><blockquote><pre>int sqlite3_get_table(

5603

sqlite3 *db, /* An open database */

5604

const char *zSql, /* SQL to be evaluated */

5605

char ***pazResult, /* Results of the query */

5606

int *pnRow, /* Number of result rows written here */

5607

int *pnColumn, /* Number of result columns written here */

5608

char **pzErrmsg /* Error msg written here */

5609

);

5610

void sqlite3_free_table(char **result);

5611

</pre></blockquote><p>

5612

This is a legacy interface that is preserved for backwards compatibility.

5613

Use of this interface is not recommended.</p>

5614

5615

<p>Definition: A <b>result table</b> is memory data structure created by the

5616

<a href="#sqlite3_free_table">sqlite3_get_table()</a> interface. A result table records the

5617

complete query results from one or more queries.</p>

5618

5619

<p>The table conceptually has a number of rows and columns. But

5620

these numbers are not part of the result table itself. These

5621

numbers are obtained separately. Let N be the number of rows

5622

and M be the number of columns.</p>

5623

5624

<p>A result table is an array of pointers to zero-terminated UTF-8 strings.

5625

There are (N+1)*M elements in the array. The first M pointers point

5626

to zero-terminated strings that contain the names of the columns.

5627

The remaining entries all point to query results. NULL values result

5628

in NULL pointers. All other values are in their UTF-8 zero-terminated

5629

string representation as returned by <a href="#sqlite3_column_blob">sqlite3_column_text()</a>.</p>

5630

5631

<p>A result table might consist of one or more memory allocations.

5632

It is not safe to pass a result table directly to <a href="#sqlite3_free">sqlite3_free()</a>.

5633

A result table should be deallocated using <a href="#sqlite3_free_table">sqlite3_free_table()</a>.</p>

5634

5635

<p>As an example of the result table format, suppose a query result

5636

is as follows:</p>

5637

5638

5639

Name | Age

5640

-----------------------

5641

Alice | 43

5642

Bob | 28

5643

Cindy | 21

5644

</pre></blockquote></p>

5645

5646

<p>There are two column (M==2) and three rows (N==3). Thus the

5647

result table has 8 entries. Suppose the result table is stored

5648

in an array names azResult. Then azResult holds this content:</p>

5649

5650

5651

azResult[0] = "Name";

5652

azResult[1] = "Age";

5653

azResult[2] = "Alice";

5654

azResult[3] = "43";

5655

azResult[4] = "Bob";

5656

azResult[5] = "28";

5657

azResult[6] = "Cindy";

5658

azResult[7] = "21";

5659

</pre></blockquote></p>

5660

5661

<p>The sqlite3_get_table() function evaluates one or more

5662

semicolon-separated SQL statements in the zero-terminated UTF-8

5663

string of its 2nd parameter and returns a result table to the

5664

pointer given in its 3rd parameter.</p>

5665

5666

<p>After the application has finished with the result from sqlite3_get_table(),

5667

it must pass the result table pointer to sqlite3_free_table() in order to

5668

release the memory that was malloced. Because of the way the

5669

<a href="#sqlite3_free">sqlite3_malloc()</a> happens within sqlite3_get_table(), the calling

5670

function must not try to call <a href="#sqlite3_free">sqlite3_free()</a> directly. Only

5671

<a href="#sqlite3_free_table">sqlite3_free_table()</a> is able to release the memory properly and safely.</p>

5672

5673

<p>The sqlite3_get_table() interface is implemented as a wrapper around

5674

<a href="#sqlite3_exec">sqlite3_exec()</a>. The sqlite3_get_table() routine does not have access

5675

to any internal data structures of SQLite. It uses only the public

5676

interface defined here. As a consequence, errors that occur in the

5677

wrapper layer outside of the internal <a href="#sqlite3_exec">sqlite3_exec()</a> call are not

5678

reflected in subsequent calls to <a href="#sqlite3_errcode">sqlite3_errcode()</a> or

5679

<a href="#sqlite3_errcode">sqlite3_errmsg()</a>.

5680

</p><hr><a name="sqlite3_get_auxdata"></a>

5681

<h2>Function Auxiliary Data</h2><blockquote><pre>void *sqlite3_get_auxdata(sqlite3_context*, int N);

5682

void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

5683

</pre></blockquote><p>

5684

The following two functions may be used by scalar SQL functions to

5685

associate metadata with argument values. If the same value is passed to

5686

multiple invocations of the same SQL function during query execution, under

5687

some circumstances the associated metadata may be preserved. This may

5688

be used, for example, to add a regular-expression matching scalar

5689

function. The compiled version of the regular expression is stored as

5690

metadata associated with the SQL value passed as the regular expression

5691

pattern. The compiled regular expression can be reused on multiple

5692

invocations of the same function so that the original pattern string

5693

does not need to be recompiled on each invocation.</p>

5694

5695

<p>The sqlite3_get_auxdata() interface returns a pointer to the metadata

5696

associated by the sqlite3_set_auxdata() function with the Nth argument

5697

value to the application-defined function. If no metadata has been ever

5698

been set for the Nth argument of the function, or if the corresponding

5699

function parameter has changed since the meta-data was set,

5700

then sqlite3_get_auxdata() returns a NULL pointer.</p>

5701

5702

<p>The sqlite3_set_auxdata() interface saves the metadata

5703

pointed to by its 3rd parameter as the metadata for the N-th

5704

argument of the application-defined function. Subsequent

5705

calls to sqlite3_get_auxdata() might return this data, if it has

5706

not been destroyed.

5707

If it is not NULL, SQLite will invoke the destructor

5708

function given by the 4th parameter to sqlite3_set_auxdata() on

5709

the metadata when the corresponding function parameter changes

5710

or when the SQL statement completes, whichever comes first.</p>

5711

5712

<p>SQLite is free to call the destructor and drop metadata on any

5713

parameter of any function at any time. The only guarantee is that

5714

the destructor will be called before the metadata is dropped.</p>

5715

5716

<p>In practice, metadata is preserved between function calls for

5717

expressions that are constant at compile time. This includes literal

5718

values and <a href="lang_expr.html#varparam">parameters</a>.</p>

5719

5720

<p>These routines must be called from the same thread in which

5721

the SQL function is running.

5722

</p><hr><a name="sqlite3_initialize"></a>

5723

<h2>Initialize The SQLite Library</h2><blockquote><pre>int sqlite3_initialize(void);

5724

int sqlite3_shutdown(void);

5725

int sqlite3_os_init(void);

5726

int sqlite3_os_end(void);

5727

</pre></blockquote><p>

5728

The sqlite3_initialize() routine initializes the

5729

SQLite library. The sqlite3_shutdown() routine

5730

deallocates any resources that were allocated by sqlite3_initialize().

5731

These routines are designed to aid in process initialization and

5732

shutdown on embedded systems. Workstation applications using

5733

SQLite normally do not need to invoke either of these routines.</p>

5734

5735

<p>A call to sqlite3_initialize() is an "effective" call if it is

5736

the first time sqlite3_initialize() is invoked during the lifetime of

5737

the process, or if it is the first time sqlite3_initialize() is invoked

5738

following a call to sqlite3_shutdown(). Only an effective call

5739

of sqlite3_initialize() does any initialization. All other calls

5740

are harmless no-ops.</p>

5741

5742

<p>A call to sqlite3_shutdown() is an "effective" call if it is the first

5743

call to sqlite3_shutdown() since the last sqlite3_initialize(). Only

5744

an effective call to sqlite3_shutdown() does any deinitialization.

5745

All other valid calls to sqlite3_shutdown() are harmless no-ops.</p>

5746

5747

<p>The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()

5748

is not. The sqlite3_shutdown() interface must only be called from a

5749

single thread. All open <a href="#sqlite3">database connections</a> must be closed and all

5750

other SQLite resources must be deallocated prior to invoking

5751

sqlite3_shutdown().</p>

5752

5753

<p>Among other things, sqlite3_initialize() will invoke

5754

sqlite3_os_init(). Similarly, sqlite3_shutdown()

5755

will invoke sqlite3_os_end().</p>

5756

5757

<p>The sqlite3_initialize() routine returns <a href="#SQLITE_ABORT">SQLITE_OK</a> on success.

5758

If for some reason, sqlite3_initialize() is unable to initialize

5759

the library (perhaps it is unable to allocate a needed resource such

5760

as a mutex) it returns an <a href="#SQLITE_ABORT">error code</a> other than <a href="#SQLITE_ABORT">SQLITE_OK</a>.</p>

5761

5762

<p>The sqlite3_initialize() routine is called internally by many other

5763

SQLite interfaces so that an application usually does not need to

5764

invoke sqlite3_initialize() directly. For example, <a href="#sqlite3_open">sqlite3_open()</a>

5765

calls sqlite3_initialize() so the SQLite library will be automatically

5766

initialized when <a href="#sqlite3_open">sqlite3_open()</a> is called if it has not be initialized

5767

already. However, if SQLite is compiled with the <a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a>

5768

compile-time option, then the automatic calls to sqlite3_initialize()

5769

are omitted and the application must call sqlite3_initialize() directly

5770

prior to using any other SQLite interface. For maximum portability,

5771

it is recommended that applications always invoke sqlite3_initialize()

5772

directly prior to using any other SQLite interface. Future releases

5773

of SQLite may require this. In other words, the behavior exhibited

5774

when SQLite is compiled with <a href="compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a> might become the

5775

default behavior in some future release of SQLite.</p>

5776

5777

<p>The sqlite3_os_init() routine does operating-system specific

5778

initialization of the SQLite library. The sqlite3_os_end()

5779

routine undoes the effect of sqlite3_os_init(). Typical tasks

5780

performed by these routines include allocation or deallocation

5781

of static resources, initialization of global variables,

5782

setting up a default <a href="#sqlite3_vfs">sqlite3_vfs</a> module, or setting up

5783

a default configuration using <a href="#sqlite3_config">sqlite3_config()</a>.</p>

5784

5785

<p>The application should never invoke either sqlite3_os_init()

5786

or sqlite3_os_end() directly. The application should only invoke

5787

sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()

5788

interface is called automatically by sqlite3_initialize() and

5789

sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate

5790

implementations for sqlite3_os_init() and sqlite3_os_end()

5791

are built into SQLite when it is compiled for Unix, Windows, or OS/2.

5792

When <a href="custombuild.html">built for other platforms</a>

5793

(using the <a href="compile.html#os_other">SQLITE_OS_OTHER=1</a> compile-time

5794

option) the application must supply a suitable implementation for

5795

sqlite3_os_init() and sqlite3_os_end(). An application-supplied

5796

implementation of sqlite3_os_init() or sqlite3_os_end()

5797

must return <a href="#SQLITE_ABORT">SQLITE_OK</a> on success and some other <a href="#SQLITE_ABORT">error code</a> upon

5798

failure.

5799

</p><hr><a name="sqlite3_libversion"></a>

5800

<h2>Run-Time Library Version Numbers</h2><blockquote><pre>SQLITE_EXTERN const char sqlite3_version[];

5801

const char *sqlite3_libversion(void);

5802

const char *sqlite3_sourceid(void);

5803

int sqlite3_libversion_number(void);

5804

</pre></blockquote><p>

5805

These interfaces provide the same information as the <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a>,

5806

<a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a>, and <a href="#SQLITE_SOURCE_ID">SQLITE_SOURCE_ID</a> C preprocessor macros

5807

but are associated with the library instead of the header file. Cautious

5808

programmers might include assert() statements in their application to

5809

verify that values returned by these interfaces match the macros in

5810

the header, and thus insure that the application is

5811

compiled with matching library and header files.</p>

5812

5813

5814

assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );

5815

assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );

5816

assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

5817

</pre></blockquote></p>

5818

5819

<p>The sqlite3_version[] string constant contains the text of <a href="#SQLITE_SOURCE_ID">SQLITE_VERSION</a>

5820

macro. The sqlite3_libversion() function returns a pointer to the

5821

to the sqlite3_version[] string constant. The sqlite3_libversion()

5822

function is provided for use in DLLs since DLL users usually do not have

5823

direct access to string constants within the DLL. The

5824

sqlite3_libversion_number() function returns an integer equal to

5825

<a href="#SQLITE_SOURCE_ID">SQLITE_VERSION_NUMBER</a>. The sqlite3_sourceid() function returns

5826

a pointer to a string constant whose value is the same as the

5827

<a href="#SQLITE_SOURCE_ID">SQLITE_SOURCE_ID</a> C preprocessor macro.</p>

5828

5829

<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>.

5830

</p><hr><a name="sqlite3_memory_highwater"></a>

5831

<h2>Memory Allocator Statistics</h2><blockquote><pre>sqlite3_int64 sqlite3_memory_used(void);

5832

sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

5833

</pre></blockquote><p>

5834

SQLite provides these two interfaces for reporting on the status

5835

of the <a href="#sqlite3_free">sqlite3_malloc()</a>, <a href="#sqlite3_free">sqlite3_free()</a>, and <a href="#sqlite3_free">sqlite3_realloc()</a>

5836

routines, which form the built-in memory allocation subsystem.</p>

5837

5838

<p>The <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> routine returns the number of bytes

5839

of memory currently outstanding (malloced but not freed).

5840

The <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> routine returns the maximum

5841

value of <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> since the high-water mark

5842

was last reset. The values returned by <a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> and

5843

<a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> include any overhead

5844

added by SQLite in its implementation of <a href="#sqlite3_free">sqlite3_malloc()</a>,

5845

but not overhead added by the any underlying system library

5846

routines that <a href="#sqlite3_free">sqlite3_malloc()</a> may call.</p>

5847

5848

<p>The memory high-water mark is reset to the current value of

5849

<a href="#sqlite3_memory_highwater">sqlite3_memory_used()</a> if and only if the parameter to

5850

<a href="#sqlite3_memory_highwater">sqlite3_memory_highwater()</a> is true. The value returned

5851

by <a href="#sqlite3_memory_highwater">sqlite3_memory_highwater(1)</a> is the high-water mark

5852

prior to the reset.

5853

</p><hr><a name="sqlite3_mprintf"></a>

5854

<h2>Formatted String Printing Functions</h2><blockquote><pre>char *sqlite3_mprintf(const char*,...);

5855

char *sqlite3_vmprintf(const char*, va_list);

5856

char *sqlite3_snprintf(int,char*,const char*, ...);

5857

char *sqlite3_vsnprintf(int,char*,const char*, va_list);

5858

</pre></blockquote><p>

5859

These routines are work-alikes of the "printf()" family of functions

5860

from the standard C library.</p>

5861

5862

<p>The sqlite3_mprintf() and sqlite3_vmprintf() routines write their

5863

results into memory obtained from <a href="#sqlite3_free">sqlite3_malloc()</a>.

5864

The strings returned by these two routines should be

5865

released by <a href="#sqlite3_free">sqlite3_free()</a>. Both routines return a

5866

NULL pointer if <a href="#sqlite3_free">sqlite3_malloc()</a> is unable to allocate enough

5867

memory to hold the resulting string.</p>

5868

5869

<p>The sqlite3_snprintf() routine is similar to "snprintf()" from

5870

the standard C library. The result is written into the

5871

buffer supplied as the second parameter whose size is given by

5872

the first parameter. Note that the order of the

5873

first two parameters is reversed from snprintf(). This is an

5874

historical accident that cannot be fixed without breaking

5875

backwards compatibility. Note also that sqlite3_snprintf()

5876

returns a pointer to its buffer instead of the number of

5877

characters actually written into the buffer. We admit that

5878

the number of characters written would be a more useful return

5879

value but we cannot change the implementation of sqlite3_snprintf()

5880

now without breaking compatibility.</p>

5881

5882

<p>As long as the buffer size is greater than zero, sqlite3_snprintf()

5883

guarantees that the buffer is always zero-terminated. The first

5884

parameter "n" is the total size of the buffer, including space for

5885

the zero terminator. So the longest string that can be completely

5886

written will be n-1 characters.</p>

5887

5888

<p>The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().</p>

5889

5890

<p>These routines all implement some additional formatting

5891

options that are useful for constructing SQL statements.

5892

All of the usual printf() formatting options apply. In addition, there

5893

is are "%q", "%Q", and "%z" options.</p>

5894

5895

<p>The %q option works like %s in that it substitutes a nul-terminated

5896

string from the argument list. But %q also doubles every '\'' character.

5897

%q is designed for use inside a string literal. By doubling each '\''

5898

character it escapes that character and allows it to be inserted into

5899

the string.</p>

5900

5901

<p>For example, assume the string variable zText contains text as follows:</p>

5902

5903

5904

char *zText = "It's a happy day!";

5905

</pre></blockquote></p>

5906

5907

<p>One can use this text in an SQL statement as follows:</p>

5908

5909

5910

char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);

5911

sqlite3_exec(db, zSQL, 0, 0, 0);

5912

sqlite3_free(zSQL);

5913

</pre></blockquote></p>

5914

5915

<p>Because the %q format string is used, the '\'' character in zText

5916

is escaped and the SQL generated is as follows:</p>

5917

5918

5919

INSERT INTO table1 VALUES('It''s a happy day!')

5920

</pre></blockquote></p>

5921

5922

<p>This is correct. Had we used %s instead of %q, the generated SQL

5923

would have looked like this:</p>

5924

5925

5926

INSERT INTO table1 VALUES('It's a happy day!');

5927

</pre></blockquote></p>

5928

5929

<p>This second example is an SQL syntax error. As a general rule you should

5930

always use %q instead of %s when inserting text into a string literal.</p>

5931

5932

<p>The %Q option works like %q except it also adds single quotes around

5933

the outside of the total string. Additionally, if the parameter in the

5934

argument list is a NULL pointer, %Q substitutes the text "NULL" (without

5935

single quotes). So, for example, one could say:</p>

5936

5937

5938

char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);

5939

sqlite3_exec(db, zSQL, 0, 0, 0);

5940

sqlite3_free(zSQL);

5941

</pre></blockquote></p>

5942

5943

<p>The code above will render a correct SQL statement in the zSQL

5944

variable even if the zText variable is a NULL pointer.</p>

5945

5946

<p>The "%z" formatting option works like "%s" but with the

5947

addition that after the string has been read and copied into

5948

the result, <a href="#sqlite3_free">sqlite3_free()</a> is called on the input string.

5949

</p><hr><a name="sqlite3_mutex_alloc"></a>

5950

<h2>Mutexes</h2><blockquote><pre>sqlite3_mutex *sqlite3_mutex_alloc(int);

5951

void sqlite3_mutex_free(sqlite3_mutex*);

5952

void sqlite3_mutex_enter(sqlite3_mutex*);

5953

int sqlite3_mutex_try(sqlite3_mutex*);

5954

void sqlite3_mutex_leave(sqlite3_mutex*);

5955

</pre></blockquote><p>

5956

The SQLite core uses these routines for thread

5957

synchronization. Though they are intended for internal

5958

use by SQLite, code that links against SQLite is

5959

permitted to use any of these routines.</p>

5960

5961

<p>The SQLite source code contains multiple implementations

5962

of these mutex routines. An appropriate implementation

5963

is selected automatically at compile-time. The following

5964

implementations are available in the SQLite core:</p>

5965

5966

<p><ul>

5967

<li> SQLITE_MUTEX_OS2

5968

<li> SQLITE_MUTEX_PTHREADS

5969

<li> SQLITE_MUTEX_W32

5970

<li> SQLITE_MUTEX_NOOP

5971

</ul></p>

5972

5973

<p>The SQLITE_MUTEX_NOOP implementation is a set of routines

5974

that does no real locking and is appropriate for use in

5975

a single-threaded application. The SQLITE_MUTEX_OS2,

5976

SQLITE_MUTEX_PTHREADS, and SQLITE_MUTEX_W32 implementations

5977

are appropriate for use on OS/2, Unix, and Windows.</p>

5978

5979

<p>If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor

5980

macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex

5981

implementation is included with the library. In this case the

5982

application must supply a custom mutex implementation using the

5983

<a href="#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option of the sqlite3_config() function

5984

before calling sqlite3_initialize() or any other public sqlite3_

5985

function that calls sqlite3_initialize().</p>

5986

5987

<p>The sqlite3_mutex_alloc() routine allocates a new

5988

mutex and returns a pointer to it. If it returns NULL

5989

that means that a mutex could not be allocated. SQLite

5990

will unwind its stack and return an error. The argument

5991

to sqlite3_mutex_alloc() is one of these integer constants:</p>

5992

5993

<p><ul>

5994

<li> SQLITE_MUTEX_FAST

5995

<li> SQLITE_MUTEX_RECURSIVE

5996

<li> SQLITE_MUTEX_STATIC_MASTER

5997

<li> SQLITE_MUTEX_STATIC_MEM

5998

<li> SQLITE_MUTEX_STATIC_MEM2

5999

<li> SQLITE_MUTEX_STATIC_PRNG

6000

<li> SQLITE_MUTEX_STATIC_LRU

6001

<li> SQLITE_MUTEX_STATIC_LRU2

6002

</ul></p>

6003

6004

<p>The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)

6005

cause sqlite3_mutex_alloc() to create

6006

a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE

6007

is used but not necessarily so when SQLITE_MUTEX_FAST is used.

6008

The mutex implementation does not need to make a distinction

6009

between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does

6010

not want to. SQLite will only request a recursive mutex in

6011

cases where it really needs one. If a faster non-recursive mutex

6012

implementation is available on the host platform, the mutex subsystem

6013

might return such a mutex in response to SQLITE_MUTEX_FAST.</p>

6014

6015

<p>The other allowed parameters to sqlite3_mutex_alloc() (anything other

6016

than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return

6017

a pointer to a static preexisting mutex. Six static mutexes are

6018

used by the current version of SQLite. Future versions of SQLite

6019

may add additional static mutexes. Static mutexes are for internal

6020

use by SQLite only. Applications that use SQLite mutexes should

6021

use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or

6022

SQLITE_MUTEX_RECURSIVE.</p>

6023

6024

<p>Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST

6025

or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()

6026

returns a different mutex on every call. But for the static

6027

mutex types, the same mutex is returned on every call that has

6028

the same type number.</p>

6029

6030

<p>The sqlite3_mutex_free() routine deallocates a previously

6031

allocated dynamic mutex. SQLite is careful to deallocate every

6032

dynamic mutex that it allocates. The dynamic mutexes must not be in

6033

use when they are deallocated. Attempting to deallocate a static

6034

mutex results in undefined behavior. SQLite never deallocates

6035

a static mutex.</p>

6036

6037

<p>The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt

6038

to enter a mutex. If another thread is already within the mutex,

6039

sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return

6040

SQLITE_BUSY. The sqlite3_mutex_try() interface returns <a href="#SQLITE_ABORT">SQLITE_OK</a>

6041

upon successful entry. Mutexes created using

6042

SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.

6043

In such cases the,

6044

mutex must be exited an equal number of times before another thread

6045

can enter. If the same thread tries to enter any other

6046

kind of mutex more than once, the behavior is undefined.

6047

SQLite will never exhibit

6048

such behavior in its own use of mutexes.</p>

6049

6050

<p>Some systems (for example, Windows 95) do not support the operation

6051

implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()

6052

will always return SQLITE_BUSY. The SQLite core only ever uses

6053

sqlite3_mutex_try() as an optimization so this is acceptable behavior.</p>

6054

6055

<p>The sqlite3_mutex_leave() routine exits a mutex that was

6056

previously entered by the same thread. The behavior

6057

is undefined if the mutex is not currently entered by the

6058

calling thread or is not currently allocated. SQLite will

6059

never do either.</p>

6060

6061

<p>If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or

6062

sqlite3_mutex_leave() is a NULL pointer, then all three routines

6063

behave as no-ops.</p>

6064

6065

<p>See also: <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> and <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a>.

6066

</p><hr><a name="sqlite3_mutex_held"></a>

6067

<h2>Mutex Verification Routines</h2><blockquote><pre>#ifndef NDEBUG

6068

int sqlite3_mutex_held(sqlite3_mutex*);

6069

int sqlite3_mutex_notheld(sqlite3_mutex*);

6070

#endif

6071

</pre></blockquote><p>

6072

The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines

6073

are intended for use inside assert() statements. The SQLite core

6074

never uses these routines except inside an assert() and applications

6075

are advised to follow the lead of the core. The SQLite core only

6076

provides implementations for these routines when it is compiled

6077

with the SQLITE_DEBUG flag. External mutex implementations

6078

are only required to provide these routines if SQLITE_DEBUG is

6079

defined and if NDEBUG is not defined.</p>

6080

6081

<p>These routines should return true if the mutex in their argument

6082

is held or not held, respectively, by the calling thread.</p>

6083

6084

<p>The implementation is not required to provide versions of these

6085

routines that actually work. If the implementation does not provide working

6086

versions of these routines, it should at least provide stubs that always

6087

return true so that one does not get spurious assertion failures.</p>

6088

6089

<p>If the argument to sqlite3_mutex_held() is a NULL pointer then

6090

the routine should return 1. This seems counter-intuitive since

6091

clearly the mutex cannot be held if it does not exist. But

6092

the reason the mutex does not exist is because the build is not

6093

using mutexes. And we do not want the assert() containing the

6094

call to sqlite3_mutex_held() to fail, so a non-zero return is

6095

the appropriate thing to do. The sqlite3_mutex_notheld()

6096

interface should also return 1 when given a NULL pointer.

6097

</p><hr><a name="sqlite3_open"></a>

6098

<h2>Opening A New Database Connection</h2><blockquote><pre>int sqlite3_open(

6099

const char *filename, /* Database filename (UTF-8) */

6100

sqlite3 **ppDb /* OUT: SQLite db handle */

6101

);

6102

int sqlite3_open16(

6103

const void *filename, /* Database filename (UTF-16) */

6104

sqlite3 **ppDb /* OUT: SQLite db handle */

6105

);

6106

int sqlite3_open_v2(

6107

const char *filename, /* Database filename (UTF-8) */

6108

sqlite3 **ppDb, /* OUT: SQLite db handle */

6109

int flags, /* Flags */

6110

const char *zVfs /* Name of VFS module to use */

6111

);

6112

</pre></blockquote><p>

6113

These routines open an SQLite database file as specified by the

6114

filename argument. The filename argument is interpreted as UTF-8 for

6115

sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte

6116

order for sqlite3_open16(). A <a href="#sqlite3">database connection</a> handle is usually

6117

returned in *ppDb, even if an error occurs. The only exception is that

6118

if SQLite is unable to allocate memory to hold the <a href="#sqlite3">sqlite3</a> object,

6119

a NULL will be written into *ppDb instead of a pointer to the <a href="#sqlite3">sqlite3</a>

6120

object. If the database is opened (and/or created) successfully, then

6121

<a href="#SQLITE_ABORT">SQLITE_OK</a> is returned. Otherwise an <a href="#SQLITE_ABORT">error code</a> is returned. The

6122

<a href="#sqlite3_errcode">sqlite3_errmsg()</a> or <a href="#sqlite3_errcode">sqlite3_errmsg16()</a> routines can be used to obtain

6123

an English language description of the error following a failure of any

6124

of the sqlite3_open() routines.</p>

6125

6126

<p>The default encoding for the database will be UTF-8 if

6127

sqlite3_open() or sqlite3_open_v2() is called and

6128

UTF-16 in the native byte order if sqlite3_open16() is used.</p>

6129

6130

<p>Whether or not an error occurs when it is opened, resources

6131

associated with the <a href="#sqlite3">database connection</a> handle should be released by

6132

passing it to <a href="#sqlite3_close">sqlite3_close()</a> when it is no longer required.</p>

6133

6134

<p>The sqlite3_open_v2() interface works like sqlite3_open()

6135

except that it accepts two additional parameters for additional control

6136

over the new database connection. The flags parameter to

6137

sqlite3_open_v2() can take one of

6138

the following three values, optionally combined with the

6139

<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOMUTEX</a>, <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_FULLMUTEX</a>, <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a>,

6140

<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_PRIVATECACHE</a>, and/or <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flags:</p>

6141

6142

<p><dl>

6143

<dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a></dt>

6144

<dd>The database is opened in read-only mode. If the database does not

6145

already exist, an error is returned.</dd></p>

6146

6147

<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a></dt>

6148

<dd>The database is opened for reading and writing if possible, or reading

6149

only if the file is write protected by the operating system. In either

6150

case the database must already exist, otherwise an error is returned.</dd></p>

6151

6152

<p><dt><a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READWRITE</a> | <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_CREATE</a></dt>

6153

<dd>The database is opened for reading and writing, and is created if

6154

it does not already exist. This is the behavior that is always used for

6155

sqlite3_open() and sqlite3_open16().</dd>

6156

</dl></p>

6157

6158

<p>If the 3rd parameter to sqlite3_open_v2() is not one of the

6159

combinations shown above optionally combined with other

6160

<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_* bits</a>

6161

then the behavior is undefined.</p>

6162

6163

<p>If the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_NOMUTEX</a> flag is set, then the database connection

6164

opens in the multi-thread <a href="threadsafe.html">threading mode</a> as long as the single-thread

6165

mode has not been set at compile-time or start-time. If the

6166

<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_FULLMUTEX</a> flag is set then the database connection opens

6167

in the serialized <a href="threadsafe.html">threading mode</a> unless single-thread was

6168

previously selected at compile-time or start-time.

6169

The <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_SHAREDCACHE</a> flag causes the database connection to be

6170

eligible to use <a href="sharedcache.html">shared cache mode</a>, regardless of whether or not shared

6171

cache is enabled using <a href="#sqlite3_enable_shared_cache">sqlite3_enable_shared_cache()</a>. The

6172

<a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_PRIVATECACHE</a> flag causes the database connection to not

6173

participate in <a href="sharedcache.html">shared cache mode</a> even if it is enabled.</p>

6174

6175

<p>The fourth parameter to sqlite3_open_v2() is the name of the

6176

<a href="#sqlite3_vfs">sqlite3_vfs</a> object that defines the operating system interface that

6177

the new database connection should use. If the fourth parameter is

6178

a NULL pointer then the default <a href="#sqlite3_vfs">sqlite3_vfs</a> object is used.</p>

6179

6180

<p>If the filename is ":memory:", then a private, temporary in-memory database

6181

is created for the connection. This in-memory database will vanish when

6182

the database connection is closed. Future versions of SQLite might

6183

make use of additional special filenames that begin with the ":" character.

6184

It is recommended that when a database filename actually does begin with

6185

a ":" character you should prefix the filename with a pathname such as

6186

"./" to avoid ambiguity.</p>

6187

6188

<p>If the filename is an empty string, then a private, temporary

6189

on-disk database will be created. This private database will be

6190

automatically deleted as soon as the database connection is closed.</p>

6191

6192

6193

<h3>URI Filenames</h3></p>

6194

6195

<p>If <a href="uri.html">URI filename</a> interpretation is enabled, and the filename argument

6196

begins with "file:", then the filename is interpreted as a URI. URI

6197

filename interpretation is enabled if the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> flag is

6198

set in the fourth argument to sqlite3_open_v2(), or if it has

6199

been enabled globally using the <a href="#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the

6200

<a href="#sqlite3_config">sqlite3_config()</a> method or by the <a href="compile.html#use_uri">SQLITE_USE_URI</a> compile-time option.

6201

As of SQLite version 3.7.7, URI filename interpretation is turned off

6202

by default, but future releases of SQLite might enable URI filename

6203

interpretation by default. See "<a href="uri.html">URI filenames</a>" for additional

6204

information.</p>

6205

6206

<p>URI filenames are parsed according to RFC 3986. If the URI contains an

6207

authority, then it must be either an empty string or the string

6208

"localhost". If the authority is not an empty string or "localhost", an

6209

error is returned to the caller. The fragment component of a URI, if

6210

present, is ignored.</p>

6211

6212

<p>SQLite uses the path component of the URI as the name of the disk file

6213

which contains the database. If the path begins with a '/' character,

6214

then it is interpreted as an absolute path. If the path does not begin

6215

with a '/' (meaning that the authority section is omitted from the URI)

6216

then the path is interpreted as a relative path.

6217

On windows, the first component of an absolute path

6218

is a drive specification (e.g. "C:").</p>

6219

6220

6221

6222

The query component of a URI may contain parameters that are interpreted

6223

either by SQLite itself, or by a <a href="vfs.html">custom VFS implementation</a>.

6224

SQLite interprets the following three query parameters:</p>

6225

6226

<p><ul>

6227

<li> <b>vfs</b>: The "vfs" parameter may be used to specify the name of

6228

a VFS object that provides the operating system interface that should

6229

be used to access the database file on disk. If this option is set to

6230

an empty string the default VFS object is used. Specifying an unknown

6231

VFS is an error. If sqlite3_open_v2() is used and the vfs option is

6232

present, then the VFS specified by the option takes precedence over

6233

the value passed as the fourth parameter to sqlite3_open_v2().</p>

6234

6235

<p><li> <b>mode</b>: The mode parameter may be set to either "ro", "rw",

6236

"rwc", or "memory". Attempting to set it to any other value is

6237

an error.

6238

If "ro" is specified, then the database is opened for read-only

6239

access, just as if the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_READONLY</a> flag had been set in the

6240

third argument to sqlite3_prepare_v2(). If the mode option is set to

6241

"rw", then the database is opened for read-write (but not create)

6242

access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had

6243

been set. Value "rwc" is equivalent to setting both

6244

SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If the mode option is

6245

set to "memory" then a pure <a href="inmemorydb.html">in-memory database</a> that never reads

6246

or writes from disk is used. It is an error to specify a value for

6247

the mode parameter that is less restrictive than that specified by

6248

the flags passed in the third parameter to sqlite3_open_v2().</p>

6249

6250

<p><li> <b>cache</b>: The cache parameter may be set to either "shared" or

6251

"private". Setting it to "shared" is equivalent to setting the

6252

SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to

6253

sqlite3_open_v2(). Setting the cache parameter to "private" is

6254

equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.

6255

If sqlite3_open_v2() is used and the "cache" parameter is present in

6256

a URI filename, its value overrides any behaviour requested by setting

6257

SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.

6258

</ul></p>

6259

6260

<p>Specifying an unknown parameter in the query component of a URI is not an

6261

error. Future versions of SQLite might understand additional query

6262

parameters. See "<a href="uri.html#coreqp">query parameters with special meaning to SQLite</a>" for

6263

additional information.</p>

6264

6265

6266

<h3>URI filename examples</h3></p>

6267

6268

6269

<tr><th> URI filenames <th> Results

6270

6271

Open the file "data.db" in the current directory.

6272

6273

file:///home/fred/data.db <br>

6274

file://localhost/home/fred/data.db <br> <td>

6275

Open the database file "/home/fred/data.db".

6276

<tr><td> file://darkstar/home/fred/data.db <td>

6277

An error. "darkstar" is not a recognized authority.

6278

6279

file:///C:/Documents%20and%20Settings/fred/Desktop/data.db

6280

<td> Windows only: Open the file "data.db" on fred's desktop on drive

6281

C:. Note that the %20 escaping in this example is not strictly

6282

necessary - space characters can be used literally

6283

in URI filenames.

6284

<tr><td> file:data.db?mode=ro&cache=private <td>

6285

Open file "data.db" in the current directory for read-only access.

6286

Regardless of whether or not shared-cache mode is enabled by

6287

default, use a private cache.

6288

<tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>

6289

Open file "/home/fred/data.db". Use the special VFS "unix-nolock".

6290

<tr><td> file:data.db?mode=readonly <td>

6291

An error. "readonly" is not a valid option for the "mode" parameter.

6292

</table></p>

6293

6294

<p>URI hexadecimal escape sequences (%HH) are supported within the path and

6295

query components of a URI. A hexadecimal escape sequence consists of a

6296

percent sign - "%" - followed by exactly two hexadecimal digits

6297

specifying an octet value. Before the path or query components of a

6298

URI filename are interpreted, they are encoded using UTF-8 and all

6299

hexadecimal escape sequences replaced by a single byte containing the

6300

corresponding octet. If this process generates an invalid UTF-8 encoding,

6301

the results are undefined.</p>

6302

6303

<p><b>Note to Windows users:</b> The encoding used for the filename argument

6304

of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever

6305

codepage is currently defined. Filenames containing international

6306

characters must be converted to UTF-8 prior to passing them into

6307

sqlite3_open() or sqlite3_open_v2().

6308

</p><hr><a name="sqlite3_profile"></a>

6309

<h2>Tracing And Profiling Functions</h2><blockquote><pre>void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);

6310

void *sqlite3_profile(sqlite3*,

6311

void(*xProfile)(void*,const char*,sqlite3_uint64), void*);

6312

</pre></blockquote><p>

6313

These routines register callback functions that can be used for

6314

tracing and profiling the execution of SQL statements.</p>

6315

6316

<p>The callback function registered by sqlite3_trace() is invoked at

6317

various times when an SQL statement is being run by <a href="#sqlite3_step">sqlite3_step()</a>.

6318

The sqlite3_trace() callback is invoked with a UTF-8 rendering of the

6319

SQL statement text as the statement first begins executing.

6320

Additional sqlite3_trace() callbacks might occur

6321

as each triggered subprogram is entered. The callbacks for triggers

6322

contain a UTF-8 SQL comment that identifies the trigger.</p>

6323

6324

<p>The callback function registered by sqlite3_profile() is invoked

6325

as each SQL statement finishes. The profile callback contains

6326

the original statement text and an estimate of wall-clock time

6327

of how long that statement took to run. The profile callback

6328

time is in units of nanoseconds, however the current implementation

6329

is only capable of millisecond resolution so the six least significant

6330

digits in the time are meaningless. Future versions of SQLite

6331

might provide greater resolution on the profiler callback. The

6332

sqlite3_profile() function is considered experimental and is

6333

subject to change in future versions of SQLite.

6334

</p><hr><a name="sqlite3_result_blob"></a>

6335

<h2>Setting The Result Of An SQL Function</h2><blockquote><pre>void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));

6336

void sqlite3_result_double(sqlite3_context*, double);

6337

void sqlite3_result_error(sqlite3_context*, const char*, int);

6338

void sqlite3_result_error16(sqlite3_context*, const void*, int);

6339

void sqlite3_result_error_toobig(sqlite3_context*);

6340

void sqlite3_result_error_nomem(sqlite3_context*);

6341

void sqlite3_result_error_code(sqlite3_context*, int);

6342

void sqlite3_result_int(sqlite3_context*, int);

6343

void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);

6344

void sqlite3_result_null(sqlite3_context*);

6345

void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));

6346

void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));

6347

void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));

6348

void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));

6349

void sqlite3_result_value(sqlite3_context*, sqlite3_value*);

6350

void sqlite3_result_zeroblob(sqlite3_context*, int n);

6351

</pre></blockquote><p>

6352

These routines are used by the xFunc or xFinal callbacks that

6353

implement SQL functions and aggregates. See

6354

<a href="#sqlite3_create_function">sqlite3_create_function()</a> and <a href="#sqlite3_create_function">sqlite3_create_function16()</a>

6355

for additional information.</p>

6356

6357

<p>These functions work very much like the <a href="#sqlite3_bind_blob">parameter binding</a> family of

6358

functions used to bind values to host parameters in prepared statements.

6359

Refer to the <a href="#sqlite3_bind_blob">SQL parameter</a> documentation for additional information.</p>

6360

6361

<p>The sqlite3_result_blob() interface sets the result from

6362

an application-defined function to be the BLOB whose content is pointed

6363

to by the second parameter and which is N bytes long where N is the

6364

third parameter.</p>

6365

6366

<p>The sqlite3_result_zeroblob() interfaces set the result of

6367

the application-defined function to be a BLOB containing all zero

6368

bytes and N bytes in size, where N is the value of the 2nd parameter.</p>

6369

6370

<p>The sqlite3_result_double() interface sets the result from

6371

an application-defined function to be a floating point value specified

6372

by its 2nd argument.</p>

6373

6374

<p>The sqlite3_result_error() and sqlite3_result_error16() functions

6375

cause the implemented SQL function to throw an exception.

6376

SQLite uses the string pointed to by the

6377

2nd parameter of sqlite3_result_error() or sqlite3_result_error16()

6378

as the text of an error message. SQLite interprets the error

6379

message string from sqlite3_result_error() as UTF-8. SQLite

6380

interprets the string from sqlite3_result_error16() as UTF-16 in native

6381

byte order. If the third parameter to sqlite3_result_error()

6382

or sqlite3_result_error16() is negative then SQLite takes as the error

6383

message all text up through the first zero character.

6384

If the third parameter to sqlite3_result_error() or

6385

sqlite3_result_error16() is non-negative then SQLite takes that many

6386

bytes (not characters) from the 2nd parameter as the error message.

6387

The sqlite3_result_error() and sqlite3_result_error16()

6388

routines make a private copy of the error message text before

6389

they return. Hence, the calling function can deallocate or

6390

modify the text after they return without harm.

6391

The sqlite3_result_error_code() function changes the error code

6392

returned by SQLite as a result of an error in a function. By default,

6393

the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()

6394

or sqlite3_result_error16() resets the error code to SQLITE_ERROR.</p>

6395

6396

<p>The sqlite3_result_toobig() interface causes SQLite to throw an error

6397

indicating that a string or BLOB is too long to represent.</p>

6398

6399

<p>The sqlite3_result_nomem() interface causes SQLite to throw an error

6400

indicating that a memory allocation failed.</p>

6401

6402

<p>The sqlite3_result_int() interface sets the return value

6403

of the application-defined function to be the 32-bit signed integer

6404

value given in the 2nd argument.

6405

The sqlite3_result_int64() interface sets the return value

6406

of the application-defined function to be the 64-bit signed integer

6407

value given in the 2nd argument.</p>

6408

6409

<p>The sqlite3_result_null() interface sets the return value

6410

of the application-defined function to be NULL.</p>

6411

6412

<p>The sqlite3_result_text(), sqlite3_result_text16(),

6413

sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces

6414

set the return value of the application-defined function to be

6415

a text string which is represented as UTF-8, UTF-16 native byte order,

6416

UTF-16 little endian, or UTF-16 big endian, respectively.

6417

SQLite takes the text result from the application from

6418

the 2nd parameter of the sqlite3_result_text* interfaces.

6419

If the 3rd parameter to the sqlite3_result_text* interfaces

6420

is negative, then SQLite takes result text from the 2nd parameter

6421

through the first zero character.

6422

If the 3rd parameter to the sqlite3_result_text* interfaces

6423

is non-negative, then as many bytes (not characters) of the text

6424

pointed to by the 2nd parameter are taken as the application-defined

6425

function result. If the 3rd parameter is non-negative, then it

6426

must be the byte offset into the string where the NUL terminator would

6427

appear if the string where NUL terminated. If any NUL characters occur

6428

in the string at a byte offset that is less than the value of the 3rd

6429

parameter, then the resulting string will contain embedded NULs and the

6430

result of expressions operating on strings with embedded NULs is undefined.

6431

If the 4th parameter to the sqlite3_result_text* interfaces

6432

or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that

6433

function as the destructor on the text or BLOB result when it has

6434

finished using that result.

6435

If the 4th parameter to the sqlite3_result_text* interfaces or to

6436

sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite

6437

assumes that the text or BLOB result is in constant space and does not

6438

copy the content of the parameter nor call a destructor on the content

6439

when it has finished using that result.

6440

If the 4th parameter to the sqlite3_result_text* interfaces

6441

or sqlite3_result_blob is the special constant SQLITE_TRANSIENT

6442

then SQLite makes a copy of the result into space obtained from

6443

from <a href="#sqlite3_free">sqlite3_malloc()</a> before it returns.</p>

6444

6445

<p>The sqlite3_result_value() interface sets the result of

6446

the application-defined function to be a copy the

6447

<a href="#sqlite3_value">unprotected sqlite3_value</a> object specified by the 2nd parameter. The

6448

sqlite3_result_value() interface makes a copy of the <a href="#sqlite3_value">sqlite3_value</a>

6449

so that the <a href="#sqlite3_value">sqlite3_value</a> specified in the parameter may change or

6450

be deallocated after sqlite3_result_value() returns without harm.

6451

A <a href="#sqlite3_value">protected sqlite3_value</a> object may always be used where an

6452

<a href="#sqlite3_value">unprotected sqlite3_value</a> object is required, so either

6453

kind of <a href="#sqlite3_value">sqlite3_value</a> object can be used with this interface.</p>

6454

6455

<p>If these routines are called from within the different thread

6456

than the one containing the application-defined function that received

6457

the <a href="#sqlite3_context">sqlite3_context</a> pointer, the results are undefined.

6458

</p><hr><a name="sqlite3_stricmp"></a>

6459

<h2>String Comparison</h2><blockquote><pre>int sqlite3_stricmp(const char *, const char *);

6460

int sqlite3_strnicmp(const char *, const char *, int);

6461

</pre></blockquote><p>

6462

The <a href="#sqlite3_stricmp">sqlite3_stricmp()</a> and <a href="#sqlite3_stricmp">sqlite3_strnicmp()</a> APIs allow applications

6463

and extensions to compare the contents of two buffers containing UTF-8

6464

strings in a case-independent fashion, using the same definition of "case

6465

independence" that SQLite uses internally when comparing identifiers.

6466

</p><hr><a name="sqlite3_uri_boolean"></a>

6467

<h2>Obtain Values For URI Parameters</h2><blockquote><pre>const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);

6468

int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);

6469

sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);

6470

</pre></blockquote><p>

6471

These are utility routines, useful to VFS implementations, that check

6472

to see if a database file was a URI that contained a specific query

6473

parameter, and if so obtains the value of that query parameter.</p>

6474

6475

<p>If F is the database filename pointer passed into the xOpen() method of

6476

a VFS implementation when the flags parameter to xOpen() has one or

6477

more of the <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_URI</a> or <a href="#SQLITE_OPEN_AUTOPROXY">SQLITE_OPEN_MAIN_DB</a> bits set and

6478

P is the name of the query parameter, then

6479

sqlite3_uri_parameter(F,P) returns the value of the P

6480

parameter if it exists or a NULL pointer if P does not appear as a

6481

query parameter on F. If P is a query parameter of F

6482

has no explicit value, then sqlite3_uri_parameter(F,P) returns

6483

a pointer to an empty string.</p>

6484

6485

<p>The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean

6486

parameter and returns true (1) or false (0) according to the value

6487

of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the

6488

value of query parameter P is one of "yes", "true", or "on" in any

6489

case or if the value begins with a non-zero number. The

6490

sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of

6491

query parameter P is one of "no", "false", or "off" in any case or

6492

if the value begins with a numeric zero. If P is not a query

6493

parameter on F or if the value of P is does not match any of the

6494

above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).</p>

6495

6496

<p>The sqlite3_uri_int64(F,P,D) routine converts the value of P into a

6497

64-bit signed integer and returns that integer, or D if P does not

6498

exist. If the value of P is something other than an integer, then

6499

zero is returned.</p>

6500

6501

<p>If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and

6502

sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and

6503

is not a database file pathname pointer that SQLite passed into the xOpen

6504

VFS method, then the behavior of this routine is undefined and probably

6505

undesirable.

6506

</p><hr><a name="sqlite3_value_blob"></a>

6507

<h2>Obtaining SQL Function Parameter Values</h2><blockquote><pre>const void *sqlite3_value_blob(sqlite3_value*);

6508

int sqlite3_value_bytes(sqlite3_value*);

6509

int sqlite3_value_bytes16(sqlite3_value*);

6510

double sqlite3_value_double(sqlite3_value*);

6511

int sqlite3_value_int(sqlite3_value*);

6512

sqlite3_int64 sqlite3_value_int64(sqlite3_value*);

6513

const unsigned char *sqlite3_value_text(sqlite3_value*);

6514

const void *sqlite3_value_text16(sqlite3_value*);

6515

const void *sqlite3_value_text16le(sqlite3_value*);

6516

const void *sqlite3_value_text16be(sqlite3_value*);

6517

int sqlite3_value_type(sqlite3_value*);

6518

int sqlite3_value_numeric_type(sqlite3_value*);

6519

</pre></blockquote><p>

6520

The C-language implementation of SQL functions and aggregates uses

6521

this set of interface routines to access the parameter values on

6522

the function or aggregate.</p>

6523

6524

<p>The xFunc (for scalar functions) or xStep (for aggregates) parameters

6525

to <a href="#sqlite3_create_function">sqlite3_create_function()</a> and <a href="#sqlite3_create_function">sqlite3_create_function16()</a>

6526

define callbacks that implement the SQL functions and aggregates.

6527

The 3rd parameter to these callbacks is an array of pointers to

6528

<a href="#sqlite3_value">protected sqlite3_value</a> objects. There is one <a href="#sqlite3_value">sqlite3_value</a> object for

6529

each parameter to the SQL function. These routines are used to

6530

extract values from the <a href="#sqlite3_value">sqlite3_value</a> objects.</p>

6531

6532

<p>These routines work only with <a href="#sqlite3_value">protected sqlite3_value</a> objects.

6533

Any attempt to use these routines on an <a href="#sqlite3_value">unprotected sqlite3_value</a>

6534

object results in undefined behavior.</p>

6535

6536

<p>These routines work just like the corresponding <a href="#sqlite3_column_blob">column access functions</a>

6537

except that these routines take a single <a href="#sqlite3_value">protected sqlite3_value</a> object

6538

pointer instead of a <a href="#sqlite3_stmt">sqlite3_stmt*</a> pointer and an integer column number.</p>

6539

6540

<p>The sqlite3_value_text16() interface extracts a UTF-16 string

6541

in the native byte-order of the host machine. The

6542

sqlite3_value_text16be() and sqlite3_value_text16le() interfaces

6543

extract UTF-16 strings as big-endian and little-endian respectively.</p>

6544

6545

<p>The sqlite3_value_numeric_type() interface attempts to apply

6546

numeric affinity to the value. This means that an attempt is

6547

made to convert the value to an integer or floating point. If

6548

such a conversion is possible without loss of information (in other

6549

words, if the value is a string that looks like a number)

6550

then the conversion is performed. Otherwise no conversion occurs.

6551

The <a href="#SQLITE_BLOB">datatype</a> after conversion is returned.</p>

6552

6553

<p>Please pay particular attention to the fact that the pointer returned

6554

from <a href="#sqlite3_value_blob">sqlite3_value_blob()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>, or

6555

<a href="#sqlite3_value_blob">sqlite3_value_text16()</a> can be invalidated by a subsequent call to

6556

<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>,

6557

or <a href="#sqlite3_value_blob">sqlite3_value_text16()</a>.</p>

6558

6559

<p>These routines must be called from the same thread as

6560

the SQL function that supplied the <a href="#sqlite3_value">sqlite3_value*</a> parameters.

6561

</p><hr><a name="sqlite3_vfs_find"></a>

6562

<h2>Virtual File System Objects</h2><blockquote><pre>sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);

6563

int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);

6564

int sqlite3_vfs_unregister(sqlite3_vfs*);

6565

</pre></blockquote><p>

6566

A virtual filesystem (VFS) is an <a href="#sqlite3_vfs">sqlite3_vfs</a> object

6567

that SQLite uses to interact

6568

with the underlying operating system. Most SQLite builds come with a

6569

single default VFS that is appropriate for the host computer.

6570

New VFSes can be registered and existing VFSes can be unregistered.

6571

The following interfaces are provided.</p>

6572

6573

<p>The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.

6574

Names are case sensitive.

6575

Names are zero-terminated UTF-8 strings.

6576

If there is no match, a NULL pointer is returned.

6577

If zVfsName is NULL then the default VFS is returned.</p>

6578

6579

<p>New VFSes are registered with sqlite3_vfs_register().

6580

Each new VFS becomes the default VFS if the makeDflt flag is set.

6581

The same VFS can be registered multiple times without injury.

6582

To make an existing VFS into the default VFS, register it again

6583

with the makeDflt flag set. If two different VFSes with the

6584

same name are registered, the behavior is undefined. If a

6585

VFS is registered with a name that is NULL or an empty string,

6586

then the behavior is undefined.</p>

6587

6588

<p>Unregister a VFS with the sqlite3_vfs_unregister() interface.

6589

If the default VFS is unregistered, another VFS is chosen as

6590

the default. The choice for the new VFS is arbitrary.

6591

</p><hr><a name="sqlite3_bind_blob"></a>

6592

<h2>Binding Values To Prepared Statements</h2><blockquote><pre>int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));

6593

int sqlite3_bind_double(sqlite3_stmt*, int, double);

6594

int sqlite3_bind_int(sqlite3_stmt*, int, int);

6595

int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);

6596

int sqlite3_bind_null(sqlite3_stmt*, int);

6597

int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));

6598

int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));

6599

int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);

6600

int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

6601

</pre></blockquote><p>

6602

In the SQL statement text input to <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> and its variants,

6603

literals may be replaced by a <a href="lang_expr.html#varparam">parameter</a> that matches one of following

6604

templates:</p>

6605

6606

<p><ul>

6607

<li> ?

6608

<li> ?NNN

6609

<li> :VVV

6610

<li> @VVV

6611

<li> $VVV

6612

</ul></p>

6613

6614

<p>In the templates above, NNN represents an integer literal,

6615

and VVV represents an alphanumeric identifier. The values of these

6616

parameters (also called "host parameter names" or "SQL parameters")

6617

can be set using the sqlite3_bind_*() routines defined here.</p>

6618

6619

<p>The first argument to the sqlite3_bind_*() routines is always

6620

a pointer to the <a href="#sqlite3_stmt">sqlite3_stmt</a> object returned from

6621

<a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or its variants.</p>

6622

6623

<p>The second argument is the index of the SQL parameter to be set.

6624

The leftmost SQL parameter has an index of 1. When the same named

6625

SQL parameter is used more than once, second and subsequent

6626

occurrences have the same index as the first occurrence.

6627

The index for named parameters can be looked up using the

6628

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a> API if desired. The index

6629

for "?NNN" parameters is the value of NNN.

6630

The NNN value must be between 1 and the <a href="#sqlite3_limit">sqlite3_limit()</a>

6631

parameter <a href="#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 999).</p>

6632

6633

<p>The third argument is the value to bind to the parameter.</p>

6634

6635

<p>In those routines that have a fourth argument, its value is the

6636

number of bytes in the parameter. To be clear: the value is the

6637

number of <u>bytes</u> in the value, not the number of characters.

6638

If the fourth parameter is negative, the length of the string is

6639

the number of bytes up to the first zero terminator.

6640

If a non-negative fourth parameter is provided to sqlite3_bind_text()

6641

or sqlite3_bind_text16() then that parameter must be the byte offset

6642

where the NUL terminator would occur assuming the string were NUL

6643

terminated. If any NUL characters occur at byte offsets less than

6644

the value of the fourth parameter then the resulting string value will

6645

contain embedded NULs. The result of expressions involving strings

6646

with embedded NULs is undefined.</p>

6647

6648

<p>The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and

6649

sqlite3_bind_text16() is a destructor used to dispose of the BLOB or

6650

string after SQLite has finished with it. The destructor is called

6651

to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),

6652

sqlite3_bind_text(), or sqlite3_bind_text16() fails.

6653

If the fifth argument is

6654

the special value <a href="#SQLITE_STATIC">SQLITE_STATIC</a>, then SQLite assumes that the

6655

information is in static, unmanaged space and does not need to be freed.

6656

If the fifth argument has the value <a href="#SQLITE_STATIC">SQLITE_TRANSIENT</a>, then

6657

SQLite makes its own private copy of the data immediately, before

6658

the sqlite3_bind_*() routine returns.</p>

6659

6660

<p>The sqlite3_bind_zeroblob() routine binds a BLOB of length N that

6661

is filled with zeroes. A zeroblob uses a fixed amount of memory

6662

(just an integer to hold its size) while it is being processed.

6663

Zeroblobs are intended to serve as placeholders for BLOBs whose

6664

content is later written using

6665

<a href="#sqlite3_blob_open">incremental BLOB I/O</a> routines.

6666

A negative value for the zeroblob results in a zero-length BLOB.</p>

6667

6668

<p>If any of the sqlite3_bind_*() routines are called with a NULL pointer

6669

for the <a href="#sqlite3_stmt">prepared statement</a> or with a prepared statement for which

6670

<a href="#sqlite3_step">sqlite3_step()</a> has been called more recently than <a href="#sqlite3_reset">sqlite3_reset()</a>,

6671

then the call will return <a href="#SQLITE_ABORT">SQLITE_MISUSE</a>. If any sqlite3_bind_()

6672

routine is passed a <a href="#sqlite3_stmt">prepared statement</a> that has been finalized, the

6673

result is undefined and probably harmful.</p>

6674

6675

<p>Bindings are not cleared by the <a href="#sqlite3_reset">sqlite3_reset()</a> routine.

6676

Unbound parameters are interpreted as NULL.</p>

6677

6678

<p>The sqlite3_bind_* routines return <a href="#SQLITE_ABORT">SQLITE_OK</a> on success or an

6679

<a href="#SQLITE_ABORT">error code</a> if anything goes wrong.

6680

<a href="#SQLITE_ABORT">SQLITE_RANGE</a> is returned if the parameter

6681

index is out of range. <a href="#SQLITE_ABORT">SQLITE_NOMEM</a> is returned if malloc() fails.</p>

6682

6683

<p>See also: <a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>,

6684

<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and <a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.

6685

</p><hr><a name="sqlite3_prepare"></a>

6686

<h2>Compiling An SQL Statement</h2><blockquote><pre>int sqlite3_prepare(

6687

sqlite3 *db, /* Database handle */

6688

const char *zSql, /* SQL statement, UTF-8 encoded */

6689

int nByte, /* Maximum length of zSql in bytes. */

6690

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

6691

const char **pzTail /* OUT: Pointer to unused portion of zSql */

6692

);

6693

int sqlite3_prepare_v2(

6694

sqlite3 *db, /* Database handle */

6695

const char *zSql, /* SQL statement, UTF-8 encoded */

6696

int nByte, /* Maximum length of zSql in bytes. */

6697

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

6698

const char **pzTail /* OUT: Pointer to unused portion of zSql */

6699

);

6700

int sqlite3_prepare16(

6701

sqlite3 *db, /* Database handle */

6702

const void *zSql, /* SQL statement, UTF-16 encoded */

6703

int nByte, /* Maximum length of zSql in bytes. */

6704

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

6705

const void **pzTail /* OUT: Pointer to unused portion of zSql */

6706

);

6707

int sqlite3_prepare16_v2(

6708

sqlite3 *db, /* Database handle */

6709

const void *zSql, /* SQL statement, UTF-16 encoded */

6710

int nByte, /* Maximum length of zSql in bytes. */

6711

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

6712

const void **pzTail /* OUT: Pointer to unused portion of zSql */

6713

);

6714

</pre></blockquote><p>

6715

To execute an SQL query, it must first be compiled into a byte-code

6716

program using one of these routines.</p>

6717

6718

<p>The first argument, "db", is a <a href="#sqlite3">database connection</a> obtained from a

6719

prior successful call to <a href="#sqlite3_open">sqlite3_open()</a>, <a href="#sqlite3_open">sqlite3_open_v2()</a> or

6720

<a href="#sqlite3_open">sqlite3_open16()</a>. The database connection must not have been closed.</p>

6721

6722

<p>The second argument, "zSql", is the statement to be compiled, encoded

6723

as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()

6724

interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()

6725

use UTF-16.</p>

6726

6727

<p>If the nByte argument is less than zero, then zSql is read up to the

6728

first zero terminator. If nByte is non-negative, then it is the maximum

6729

number of bytes read from zSql. When nByte is non-negative, the

6730

zSql string ends at either the first '\000' or '\u0000' character or

6731

the nByte-th byte, whichever comes first. If the caller knows

6732

that the supplied string is nul-terminated, then there is a small

6733

performance advantage to be gained by passing an nByte parameter that

6734

is equal to the number of bytes in the input string <i>including</i>

6735

the nul-terminator bytes as this saves SQLite from having to

6736

make a copy of the input string.</p>

6737

6738

<p>If pzTail is not NULL then *pzTail is made to point to the first byte

6739

past the end of the first SQL statement in zSql. These routines only

6740

compile the first statement in zSql, so *pzTail is left pointing to

6741

what remains uncompiled.</p>

6742

6743

<p>*ppStmt is left pointing to a compiled <a href="#sqlite3_stmt">prepared statement</a> that can be

6744

executed using <a href="#sqlite3_step">sqlite3_step()</a>. If there is an error, *ppStmt is set

6745

to NULL. If the input text contains no SQL (if the input is an empty

6746

string or a comment) then *ppStmt is set to NULL.

6747

The calling procedure is responsible for deleting the compiled

6748

SQL statement using <a href="#sqlite3_finalize">sqlite3_finalize()</a> after it has finished with it.

6749

ppStmt may not be NULL.</p>

6750

6751

<p>On success, the sqlite3_prepare() family of routines return <a href="#SQLITE_ABORT">SQLITE_OK</a>;

6752

otherwise an <a href="#SQLITE_ABORT">error code</a> is returned.</p>

6753

6754

<p>The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are

6755

recommended for all new programs. The two older interfaces are retained

6756

for backwards compatibility, but their use is discouraged.

6757

In the "v2" interfaces, the prepared statement

6758

that is returned (the <a href="#sqlite3_stmt">sqlite3_stmt</a> object) contains a copy of the

6759

original SQL text. This causes the <a href="#sqlite3_step">sqlite3_step()</a> interface to

6760

behave differently in three ways:</p>

6761

6762

<p><ol>

6763

<li>

6764

If the database schema changes, instead of returning <a href="#SQLITE_ABORT">SQLITE_SCHEMA</a> as it

6765

always used to do, <a href="#sqlite3_step">sqlite3_step()</a> will automatically recompile the SQL

6766

statement and try to run it again.

6767

</li></p>

6768

6769

<p><li>

6770

When an error occurs, <a href="#sqlite3_step">sqlite3_step()</a> will return one of the detailed

6771

<a href="#SQLITE_ABORT">error codes</a> or <a href="#SQLITE_ABORT_ROLLBACK">extended error codes</a>. The legacy behavior was that

6772

<a href="#sqlite3_step">sqlite3_step()</a> would only return a generic <a href="#SQLITE_ABORT">SQLITE_ERROR</a> result code

6773

and the application would have to make a second call to <a href="#sqlite3_reset">sqlite3_reset()</a>

6774

in order to find the underlying cause of the problem. With the "v2" prepare

6775

interfaces, the underlying reason for the error is returned immediately.

6776

</li></p>

6777

6778

<p><li>

6779

If the specific value bound to <a href="lang_expr.html#varparam">host parameter</a> in the

6780

WHERE clause might influence the choice of query plan for a statement,

6781

then the statement will be automatically recompiled, as if there had been

6782

a schema change, on the first <a href="#sqlite3_step">sqlite3_step()</a> call following any change

6783

to the <a href="#sqlite3_bind_blob">bindings</a> of that <a href="lang_expr.html#varparam">parameter</a>.

6784

The specific value of WHERE-clause <a href="lang_expr.html#varparam">parameter</a> might influence the

6785

choice of query plan if the parameter is the left-hand side of a <a href="lang_expr.html#like">LIKE</a>

6786

or <a href="lang_expr.html#glob">GLOB</a> operator or if the parameter is compared to an indexed column

6787

and the <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> compile-time option is enabled.

6788

the

6789

</li>

6790

</ol>

6791

</p><hr><a name="sqlite3_create_function"></a>

6792

<h2>Create Or Redefine SQL Functions</h2><blockquote><pre>int sqlite3_create_function(

6793

sqlite3 *db,

6794

const char *zFunctionName,

6795

int nArg,

6796

int eTextRep,

6797

void *pApp,

6798

void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

6799

void (*xStep)(sqlite3_context*,int,sqlite3_value**),

6800

void (*xFinal)(sqlite3_context*)

6801

);

6802

int sqlite3_create_function16(

6803

sqlite3 *db,

6804

const void *zFunctionName,

6805

int nArg,

6806

int eTextRep,

6807

void *pApp,

6808

void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

6809

void (*xStep)(sqlite3_context*,int,sqlite3_value**),

6810

void (*xFinal)(sqlite3_context*)

6811

);

6812

int sqlite3_create_function_v2(

6813

sqlite3 *db,

6814

const char *zFunctionName,

6815

int nArg,

6816

int eTextRep,

6817

void *pApp,

6818

void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

6819

void (*xStep)(sqlite3_context*,int,sqlite3_value**),

6820

void (*xFinal)(sqlite3_context*),

6821

void(*xDestroy)(void*)

6822

);

6823

</pre></blockquote><p>

6824

These functions (collectively known as "function creation routines")

6825

are used to add SQL functions or aggregates or to redefine the behavior

6826

of existing SQL functions or aggregates. The only differences between

6827

these routines are the text encoding expected for

6828

the second parameter (the name of the function being created)

6829

and the presence or absence of a destructor callback for

6830

the application data pointer.</p>

6831

6832

<p>The first parameter is the <a href="#sqlite3">database connection</a> to which the SQL

6833

function is to be added. If an application uses more than one database

6834

connection then application-defined SQL functions must be added

6835

to each database connection separately.</p>

6836

6837

<p>The second parameter is the name of the SQL function to be created or

6838

redefined. The length of the name is limited to 255 bytes in a UTF-8

6839

representation, exclusive of the zero-terminator. Note that the name

6840

length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.

6841

Any attempt to create a function with a longer name

6842

will result in <a href="#SQLITE_ABORT">SQLITE_MISUSE</a> being returned.</p>

6843

6844

<p>The third parameter (nArg)

6845

is the number of arguments that the SQL function or

6846

aggregate takes. If this parameter is -1, then the SQL function or

6847

aggregate may take any number of arguments between 0 and the limit

6848

set by <a href="#sqlite3_limit">sqlite3_limit</a>(<a href="#sqlitelimitfunctionarg">SQLITE_LIMIT_FUNCTION_ARG</a>). If the third

6849

parameter is less than -1 or greater than 127 then the behavior is

6850

undefined.</p>

6851

6852

<p>The fourth parameter, eTextRep, specifies what

6853

<a href="#SQLITE_ANY">text encoding</a> this SQL function prefers for

6854

its parameters. Every SQL function implementation must be able to work

6855

with UTF-8, UTF-16le, or UTF-16be. But some implementations may be

6856

more efficient with one encoding than another. An application may

6857

invoke sqlite3_create_function() or sqlite3_create_function16() multiple

6858

times with the same function but with different values of eTextRep.

6859

When multiple implementations of the same function are available, SQLite

6860

will pick the one that involves the least amount of data conversion.

6861

If there is only a single implementation which does not care what text

6862

encoding is used, then the fourth argument should be <a href="#SQLITE_ANY">SQLITE_ANY</a>.</p>

6863

6864

<p>The fifth parameter is an arbitrary pointer. The implementation of the

6865

function can gain access to this pointer using <a href="#sqlite3_user_data">sqlite3_user_data()</a>.</p>

6866

6867

<p>The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are

6868

pointers to C-language functions that implement the SQL function or

6869

aggregate. A scalar SQL function requires an implementation of the xFunc

6870

callback only; NULL pointers must be passed as the xStep and xFinal

6871

parameters. An aggregate SQL function requires an implementation of xStep

6872

and xFinal and NULL pointer must be passed for xFunc. To delete an existing

6873

SQL function or aggregate, pass NULL pointers for all three function

6874

callbacks.</p>

6875

6876

<p>If the ninth parameter to sqlite3_create_function_v2() is not NULL,

6877

then it is destructor for the application data pointer.

6878

The destructor is invoked when the function is deleted, either by being

6879

overloaded or when the database connection closes.

6880

The destructor is also invoked if the call to

6881

sqlite3_create_function_v2() fails.

6882

When the destructor callback of the tenth parameter is invoked, it

6883

is passed a single argument which is a copy of the application data

6884

pointer which was the fifth parameter to sqlite3_create_function_v2().</p>

6885

6886

<p>It is permitted to register multiple implementations of the same

6887

functions with the same name but with either differing numbers of

6888

arguments or differing preferred text encodings. SQLite will use

6889

the implementation that most closely matches the way in which the

6890

SQL function is used. A function implementation with a non-negative

6891

nArg parameter is a better match than a function implementation with

6892

a negative nArg. A function where the preferred text encoding

6893

matches the database encoding is a better

6894

match than a function where the encoding is different.

6895

A function where the encoding difference is between UTF16le and UTF16be

6896

is a closer match than a function where the encoding difference is

6897

between UTF8 and UTF16.</p>

6898

6899

<p>Built-in functions may be overloaded by new application-defined functions.</p>

6900

6901

<p>An application-defined function is permitted to call other

6902

SQLite interfaces. However, such calls must not

6903

close the database connection nor finalize or reset the prepared

6904

statement in which the function is running.

6905

</p><hr><a name="sqlite3_get_autocommit"></a>

6906

<h2>Test For Auto-Commit Mode</h2><blockquote><pre>int sqlite3_get_autocommit(sqlite3*);

6907

</pre></blockquote><p>

6908

The sqlite3_get_autocommit() interface returns non-zero or

6909

zero if the given database connection is or is not in autocommit mode,

6910

respectively. Autocommit mode is on by default.

6911

Autocommit mode is disabled by a <a href="lang_transaction.html">BEGIN</a> statement.

6912

Autocommit mode is re-enabled by a <a href="lang_transaction.html">COMMIT</a> or <a href="lang_transaction.html">ROLLBACK</a>.</p>

6913

6914

<p>If certain kinds of errors occur on a statement within a multi-statement

6915

transaction (errors including <a href="#SQLITE_ABORT">SQLITE_FULL</a>, <a href="#SQLITE_ABORT">SQLITE_IOERR</a>,

6916

<a href="#SQLITE_ABORT">SQLITE_NOMEM</a>, <a href="#SQLITE_ABORT">SQLITE_BUSY</a>, and <a href="#SQLITE_ABORT">SQLITE_INTERRUPT</a>) then the

6917

transaction might be rolled back automatically. The only way to

6918

find out whether SQLite automatically rolled back the transaction after

6919

an error is to use this function.</p>

6920

6921

<p>If another thread changes the autocommit status of the database

6922

connection while this routine is running, then the return value

6923

is undefined.

6924

</p><hr><a name="sqlite3_column_blob"></a>

6925

<h2>Result Values From A Query</h2><blockquote><pre>const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);

6926

int sqlite3_column_bytes(sqlite3_stmt*, int iCol);

6927

int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);

6928

double sqlite3_column_double(sqlite3_stmt*, int iCol);

6929

int sqlite3_column_int(sqlite3_stmt*, int iCol);

6930

sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);

6931

const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);

6932

const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);

6933

int sqlite3_column_type(sqlite3_stmt*, int iCol);

6934

sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

6935

</pre></blockquote><p>

6936

These routines form the "result set" interface.</p>

6937

6938

<p>These routines return information about a single column of the current

6939

result row of a query. In every case the first argument is a pointer

6940

to the <a href="#sqlite3_stmt">prepared statement</a> that is being evaluated (the <a href="#sqlite3_stmt">sqlite3_stmt*</a>

6941

that was returned from <a href="#sqlite3_prepare">sqlite3_prepare_v2()</a> or one of its variants)

6942

and the second argument is the index of the column for which information

6943

should be returned. The leftmost column of the result set has the index 0.

6944

The number of columns in the result can be determined using

6945

<a href="#sqlite3_column_count">sqlite3_column_count()</a>.</p>

6946

6947

<p>If the SQL statement does not currently point to a valid row, or if the

6948

column index is out of range, the result is undefined.

6949

These routines may only be called when the most recent call to

6950

<a href="#sqlite3_step">sqlite3_step()</a> has returned <a href="#SQLITE_ABORT">SQLITE_ROW</a> and neither

6951

<a href="#sqlite3_reset">sqlite3_reset()</a> nor <a href="#sqlite3_finalize">sqlite3_finalize()</a> have been called subsequently.

6952

If any of these routines are called after <a href="#sqlite3_reset">sqlite3_reset()</a> or

6953

<a href="#sqlite3_finalize">sqlite3_finalize()</a> or after <a href="#sqlite3_step">sqlite3_step()</a> has returned

6954

something other than <a href="#SQLITE_ABORT">SQLITE_ROW</a>, the results are undefined.

6955

If <a href="#sqlite3_step">sqlite3_step()</a> or <a href="#sqlite3_reset">sqlite3_reset()</a> or <a href="#sqlite3_finalize">sqlite3_finalize()</a>

6956

are called from a different thread while any of these routines

6957

are pending, then the results are undefined.</p>

6958

6959

<p>The sqlite3_column_type() routine returns the

6960

<a href="#SQLITE_BLOB">datatype code</a> for the initial data type

6961

of the result column. The returned value is one of <a href="#SQLITE_BLOB">SQLITE_INTEGER</a>,

6962

<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 value

6963

returned by sqlite3_column_type() is only meaningful if no type

6964

conversions have occurred as described below. After a type conversion,

6965

the value returned by sqlite3_column_type() is undefined. Future

6966

versions of SQLite may change the behavior of sqlite3_column_type()

6967

following a type conversion.</p>

6968

6969

<p>If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()

6970

routine returns the number of bytes in that BLOB or string.

6971

If the result is a UTF-16 string, then sqlite3_column_bytes() converts

6972

the string to UTF-8 and then returns the number of bytes.

6973

If the result is a numeric value then sqlite3_column_bytes() uses

6974

<a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to convert that value to a UTF-8 string and returns

6975

the number of bytes in that string.

6976

If the result is NULL, then sqlite3_column_bytes() returns zero.</p>

6977

6978

<p>If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()

6979

routine returns the number of bytes in that BLOB or string.

6980

If the result is a UTF-8 string, then sqlite3_column_bytes16() converts

6981

the string to UTF-16 and then returns the number of bytes.

6982

If the result is a numeric value then sqlite3_column_bytes16() uses

6983

<a href="#sqlite3_mprintf">sqlite3_snprintf()</a> to convert that value to a UTF-16 string and returns

6984

the number of bytes in that string.

6985

If the result is NULL, then sqlite3_column_bytes16() returns zero.</p>

6986

6987

<p>The values returned by <a href="#sqlite3_column_blob">sqlite3_column_bytes()</a> and

6988

<a href="#sqlite3_column_blob">sqlite3_column_bytes16()</a> do not include the zero terminators at the end

6989

of the string. For clarity: the values returned by

6990

<a href="#sqlite3_column_blob">sqlite3_column_bytes()</a> and <a href="#sqlite3_column_blob">sqlite3_column_bytes16()</a> are the number of

6991

bytes in the string, not the number of characters.</p>

6992

6993

<p>Strings returned by sqlite3_column_text() and sqlite3_column_text16(),

6994

even empty strings, are always zero-terminated. The return

6995

value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.</p>

6996

6997

<p>The object returned by <a href="#sqlite3_column_blob">sqlite3_column_value()</a> is an

6998

<a href="#sqlite3_value">unprotected sqlite3_value</a> object. An unprotected sqlite3_value object

6999

may only be used with <a href="#sqlite3_bind_blob">sqlite3_bind_value()</a> and <a href="#sqlite3_result_blob">sqlite3_result_value()</a>.

7000

If the <a href="#sqlite3_value">unprotected sqlite3_value</a> object returned by

7001

<a href="#sqlite3_column_blob">sqlite3_column_value()</a> is used in any other way, including calls

7002

to routines like <a href="#sqlite3_value_blob">sqlite3_value_int()</a>, <a href="#sqlite3_value_blob">sqlite3_value_text()</a>,

7003

or <a href="#sqlite3_value_blob">sqlite3_value_bytes()</a>, then the behavior is undefined.</p>

7004

7005

<p>These routines attempt to convert the value where appropriate. For

7006

example, if the internal representation is FLOAT and a text result

7007

is requested, <a href="#sqlite3_mprintf">sqlite3_snprintf()</a> is used internally to perform the

7008

conversion automatically. The following table details the conversions

7009

that are applied:</p>

7010

7011

7012

7013

<tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion</p>

7014

7015

<p><tr><td> NULL <td> INTEGER <td> Result is 0

7016

<tr><td> NULL <td> FLOAT <td> Result is 0.0

7017

<tr><td> NULL <td> TEXT <td> Result is NULL pointer

7018

<tr><td> NULL <td> BLOB <td> Result is NULL pointer

7019

<tr><td> INTEGER <td> FLOAT <td> Convert from integer to float

7020

<tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer

7021

<tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT

7022

<tr><td> FLOAT <td> INTEGER <td> Convert from float to integer

7023

<tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float

7024

<tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT

7025

<tr><td> TEXT <td> INTEGER <td> Use atoi()

7026

<tr><td> TEXT <td> FLOAT <td> Use atof()

7027

<tr><td> TEXT <td> BLOB <td> No change

7028

<tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()

7029

<tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()

7030

<tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed

7031

</table>

7032

</blockquote></p>

7033

7034

<p>The table above makes reference to standard C library functions atoi()

7035

and atof(). SQLite does not really use these functions. It has its

7036

own equivalent internal routines. The atoi() and atof() names are

7037

used in the table for brevity and because they are familiar to most

7038

C programmers.</p>

7039

7040

<p>Note that when type conversions occur, pointers returned by prior

7041

calls to sqlite3_column_blob(), sqlite3_column_text(), and/or

7042

sqlite3_column_text16() may be invalidated.

7043

Type conversions and pointer invalidations might occur

7044

in the following cases:</p>

7045

7046

<p><ul>

7047

<li> The initial content is a BLOB and sqlite3_column_text() or

7048

sqlite3_column_text16() is called. A zero-terminator might

7049

need to be added to the string.</li>

7050

<li> The initial content is UTF-8 text and sqlite3_column_bytes16() or

7051

sqlite3_column_text16() is called. The content must be converted

7052

to UTF-16.</li>

7053

<li> The initial content is UTF-16 text and sqlite3_column_bytes() or

7054

sqlite3_column_text() is called. The content must be converted

7055

to UTF-8.</li>

7056

</ul></p>

7057

7058

<p>Conversions between UTF-16be and UTF-16le are always done in place and do

7059

not invalidate a prior pointer, though of course the content of the buffer

7060

that the prior pointer references will have been modified. Other kinds

7061

of conversion are done in place when it is possible, but sometimes they

7062

are not possible and in those cases prior pointers are invalidated.</p>

7063

7064

<p>The safest and easiest to remember policy is to invoke these routines

7065

in one of the following ways:</p>

7066

7067

<p><ul>

7068

<li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>

7069

<li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>

7070

<li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>

7071

</ul></p>

7072

7073

<p>In other words, you should call sqlite3_column_text(),

7074

sqlite3_column_blob(), or sqlite3_column_text16() first to force the result

7075

into the desired format, then invoke sqlite3_column_bytes() or

7076

sqlite3_column_bytes16() to find the size of the result. Do not mix calls

7077

to sqlite3_column_text() or sqlite3_column_blob() with calls to

7078

sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()

7079

with calls to sqlite3_column_bytes().</p>

7080

7081

<p>The pointers returned are valid until a type conversion occurs as

7082

described above, or until <a href="#sqlite3_step">sqlite3_step()</a> or <a href="#sqlite3_reset">sqlite3_reset()</a> or

7083

<a href="#sqlite3_finalize">sqlite3_finalize()</a> is called. The memory space used to hold strings

7084

and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned

7085

<a href="#sqlite3_column_blob">sqlite3_column_blob()</a>, <a href="#sqlite3_column_blob">sqlite3_column_text()</a>, etc. into

7086

<a href="#sqlite3_free">sqlite3_free()</a>.</p>

7087

7088

<p>If a memory allocation error occurs during the evaluation of any

7089

of these routines, a default value is returned. The default value

7090

is either the integer 0, the floating point number 0.0, or a NULL

7091

pointer. Subsequent calls to <a href="#sqlite3_errcode">sqlite3_errcode()</a> will return

7092

<a href="#SQLITE_ABORT">SQLITE_NOMEM</a>.

7093

</p><hr>

7094