~ubuntu-branches/ubuntu/trusty/charybdis/trusty-proposed : revision 1

1

/*

2

** 2001 September 15

3

**

4

** The author disclaims copyright to this source code. In place of

5

** a legal notice, here is a blessing:

6

**

7

** May you do good and not evil.

8

** May you find forgiveness for yourself and forgive others.

9

** May you share freely, never taking more than you give.

10

**

11

*************************************************************************

12

** This header file defines the interface that the SQLite library

13

** presents to client programs. If a C-function, structure, datatype,

14

** or constant definition does not appear in this file, then it is

15

** not a published API of SQLite, is subject to change without

16

** notice, and should not be referenced by programs that use SQLite.

17

**

18

** Some of the definitions that are in this file are marked as

19

** "experimental". Experimental interfaces are normally new

20

** features recently added to SQLite. We do not anticipate changes

21

** to experimental interfaces but reserve to make minor changes if

22

** experience from use "in the wild" suggest such changes are prudent.

23

**

24

** The official C-language API documentation for SQLite is derived

25

** from comments in this file. This file is the authoritative source

26

** on how SQLite interfaces are suppose to operate.

27

**

28

** The name of this file under configuration management is "sqlite.h.in".

29

** The makefile makes some minor changes to this file (such as inserting

30

** the version number) and changes its name to "sqlite3.h" as

31

** part of the build process.

32

**

33

** @(#) $Id: sqlite3.h 25424 2008-05-20 23:25:54Z androsyn $

34

*/

35

#ifndef _SQLITE3_H_

36

#define _SQLITE3_H_

37

#include <stdarg.h> /* Needed for the definition of va_list */

38

39

/*

40

** Make sure we can call this stuff from C++.

41

*/

42

#ifdef __cplusplus

43

extern "C" {

44

#endif

45

46

47

/*

48

** Add the ability to override 'extern'

49

*/

50

#ifndef SQLITE_EXTERN

51

# define SQLITE_EXTERN extern

52

#endif

53

54

/*

55

** Make sure these symbols where not defined by some previous header

56

** file.

57

*/

58

#ifdef SQLITE_VERSION

59

# undef SQLITE_VERSION

60

#endif

61

#ifdef SQLITE_VERSION_NUMBER

62

# undef SQLITE_VERSION_NUMBER

63

#endif

64

65

/*

66

** CAPI3REF: Compile-Time Library Version Numbers {F10010}

67

**

68

** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in

69

** the sqlite3.h file specify the version of SQLite with which

70

** that header file is associated.

71

**

72

** The "version" of SQLite is a string of the form "X.Y.Z".

73

** The phrase "alpha" or "beta" might be appended after the Z.

74

** The X value is major version number always 3 in SQLite3.

75

** The X value only changes when backwards compatibility is

76

** broken and we intend to never break

77

** backwards compatibility. The Y value is the minor version

78

** number and only changes when

79

** there are major feature enhancements that are forwards compatible

80

** but not backwards compatible. The Z value is release number

81

** and is incremented with

82

** each release but resets back to 0 when Y is incremented.

83

**

84

** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].

85

**

86

** INVARIANTS:

87

**

88

** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file

89

** evaluates to a string literal that is the SQLite version

90

** with which the header file is associated.

91

**

92

** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer

93

** with the value (X*1000000 + Y*1000 + Z) where X, Y, and

94

** Z are the major version, minor version, and release number.

95

*/

96

#define SQLITE_VERSION "3.5.9"

97

#define SQLITE_VERSION_NUMBER 3005009

98

99

/*

100

** CAPI3REF: Run-Time Library Version Numbers {F10020}

101

** KEYWORDS: sqlite3_version

102

**

103

** These features provide the same information as the [SQLITE_VERSION]

104

** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated

105

** with the library instead of the header file. Cautious programmers might

106

** include a check in their application to verify that

107

** sqlite3_libversion_number() always returns the value

108

** [SQLITE_VERSION_NUMBER].

109

**

110

** The sqlite3_libversion() function returns the same information as is

111

** in the sqlite3_version[] string constant. The function is provided

112

** for use in DLLs since DLL users usually do not have direct access to string

113

** constants within the DLL.

114

**

115

** INVARIANTS:

116

**

117

** {F10021} The [sqlite3_libversion_number()] interface returns an integer

118

** equal to [SQLITE_VERSION_NUMBER].

119

**

120

** {F10022} The [sqlite3_version] string constant contains the text of the

121

** [SQLITE_VERSION] string.

122

**

123

** {F10023} The [sqlite3_libversion()] function returns

124

** a pointer to the [sqlite3_version] string constant.

125

*/

126

SQLITE_EXTERN const char sqlite3_version[];

127

const char *sqlite3_libversion(void);

128

int sqlite3_libversion_number(void);

129

130

/*

131

** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}

132

**

133

** SQLite can be compiled with or without mutexes. When

134

** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes

135

** are enabled and SQLite is threadsafe. When that macro is false,

136

** the mutexes are omitted. Without the mutexes, it is not safe

137

** to use SQLite from more than one thread.

138

**

139

** There is a measurable performance penalty for enabling mutexes.

140

** So if speed is of utmost importance, it makes sense to disable

141

** the mutexes. But for maximum safety, mutexes should be enabled.

142

** The default behavior is for mutexes to be enabled.

143

**

144

** This interface can be used by a program to make sure that the

145

** version of SQLite that it is linking against was compiled with

146

** the desired setting of the SQLITE_THREADSAFE macro.

147

**

148

** INVARIANTS:

149

**

150

** {F10101} The [sqlite3_threadsafe()] function returns nonzero if

151

** SQLite was compiled with its mutexes enabled or zero

152

** if SQLite was compiled with mutexes disabled.

153

*/

154

int sqlite3_threadsafe(void);

155

156

/*

157

** CAPI3REF: Database Connection Handle {F12000}

158

** KEYWORDS: {database connection} {database connections}

159

**

160

** Each open SQLite database is represented by pointer to an instance of the

161

** opaque structure named "sqlite3". It is useful to think of an sqlite3

162

** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and

163

** [sqlite3_open_v2()] interfaces are its constructors

164

** and [sqlite3_close()] is its destructor. There are many other interfaces

165

** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and

166

** [sqlite3_busy_timeout()] to name but three) that are methods on this

167

** object.

168

*/

169

typedef struct sqlite3 sqlite3;

170

171

172

/*

173

** CAPI3REF: 64-Bit Integer Types {F10200}

174

** KEYWORDS: sqlite_int64 sqlite_uint64

175

**

176

** Because there is no cross-platform way to specify 64-bit integer types

177

** SQLite includes typedefs for 64-bit signed and unsigned integers.

178

**

179

** The sqlite3_int64 and sqlite3_uint64 are the preferred type

180

** definitions. The sqlite_int64 and sqlite_uint64 types are

181

** supported for backwards compatibility only.

182

**

183

** INVARIANTS:

184

**

185

** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a

186

** 64-bit signed integer.

187

**

188

** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify

189

** a 64-bit unsigned integer.

190

*/

191

#ifdef SQLITE_INT64_TYPE

192

typedef SQLITE_INT64_TYPE sqlite_int64;

193

typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

194

#elif defined(_MSC_VER) || defined(__BORLANDC__)

195

typedef __int64 sqlite_int64;

196

typedef unsigned __int64 sqlite_uint64;

197

#else

198

typedef long long int sqlite_int64;

199

typedef unsigned long long int sqlite_uint64;

200

#endif

201

typedef sqlite_int64 sqlite3_int64;

202

typedef sqlite_uint64 sqlite3_uint64;

203

204

/*

205

** If compiling for a processor that lacks floating point support,

206

** substitute integer for floating-point

207

*/

208

#ifdef SQLITE_OMIT_FLOATING_POINT

209

# define double sqlite3_int64

210

#endif

211

212

/*

213

** CAPI3REF: Closing A Database Connection {F12010}

214

**

215

** This routine is the destructor for the [sqlite3] object.

216

**

217

** Applications should [sqlite3_finalize | finalize] all

218

** [prepared statements] and

219

** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs]

220

** associated with the [sqlite3] object prior

221

** to attempting to close the [sqlite3] object.

222

**

223

** <todo>What happens to pending transactions? Are they

224

** rolled back, or abandoned?</todo>

225

**

226

** INVARIANTS:

227

**

228

** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object

229

** allocated by a prior call to [sqlite3_open()],

230

** [sqlite3_open16()], or [sqlite3_open_v2()].

231

**

232

** {F12012} The [sqlite3_close()] function releases all memory used by the

233

** connection and closes all open files.

234

**

235

** {F12013} If the database connection contains

236

** [prepared statements] that have not been

237

** finalized by [sqlite3_finalize()], then [sqlite3_close()]

238

** returns [SQLITE_BUSY] and leaves the connection open.

239

**

240

** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.

241

**

242

** LIMITATIONS:

243

**

244

** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object

245

** pointer previously obtained from [sqlite3_open()] or the

246

** equivalent, or NULL.

247

**

248

** {U12016} The parameter to [sqlite3_close()] must not have been previously

249

** closed.

250

*/

251

int sqlite3_close(sqlite3 *);

252

253

/*

254

** The type for a callback function.

255

** This is legacy and deprecated. It is included for historical

256

** compatibility and is not documented.

257

*/

258

typedef int (*sqlite3_callback)(void*,int,char**, char**);

259

260

/*

261

** CAPI3REF: One-Step Query Execution Interface {F12100}

262

**

263

** The sqlite3_exec() interface is a convenient way of running

264

** one or more SQL statements without a lot of C code. The

265

** SQL statements are passed in as the second parameter to

266

** sqlite3_exec(). The statements are evaluated one by one

267

** until either an error or an interrupt is encountered or

268

** until they are all done. The 3rd parameter is an optional

269

** callback that is invoked once for each row of any query results

270

** produced by the SQL statements. The 5th parameter tells where

271

** to write any error messages.

272

**

273

** The sqlite3_exec() interface is implemented in terms of

274

** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].

275

** The sqlite3_exec() routine does nothing that cannot be done

276

** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].

277

** The sqlite3_exec() is just a convenient wrapper.

278

**

279

** INVARIANTS:

280

**

281

** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8

282

** encoded, semicolon-separated, SQL statements in the

283

** zero-terminated string of its 2nd parameter within the

284

** context of the [sqlite3] object given in the 1st parameter.

285

**

286

** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all

287

** SQL statements run successfully.

288

**

289

** {F12105} The return value of [sqlite3_exec()] is an appropriate

290

** non-zero error code if any SQL statement fails.

291

**

292

** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]

293

** return results and the 3rd parameter is not NULL, then

294

** the callback function specified by the 3rd parameter is

295

** invoked once for each row of result.

296

**

297

** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]

298

** will aborted the SQL statement it is currently evaluating,

299

** skip all subsequent SQL statements, and return [SQLITE_ABORT].

300

** <todo>What happens to *errmsg here? Does the result code for

301

** sqlite3_errcode() get set?</todo>

302

**

303

** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through

304

** as the 1st parameter of the callback.

305

**

306

** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its

307

** callback to be the number of columns in the current row of

308

** result.

309

**

310

** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its

311

** callback to be an array of pointers to strings holding the

312

** values for each column in the current result set row as

313

** obtained from [sqlite3_column_text()].

314

**

315

** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its

316

** callback to be an array of pointers to strings holding the

317

** names of result columns as obtained from [sqlite3_column_name()].

318

**

319

** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then

320

** [sqlite3_exec()] never invokes a callback. All query

321

** results are silently discarded.

322

**

323

** {F12128} If an error occurs while parsing or evaluating any of the SQL

324

** statements handed to [sqlite3_exec()] then [sqlite3_exec()] will

325

** return an [error code] other than [SQLITE_OK].

326

**

327

** {F12131} If an error occurs while parsing or evaluating any of the SQL

328

** handed to [sqlite3_exec()] and if the 5th parameter (errmsg)

329

** to [sqlite3_exec()] is not NULL, then an error message is

330

** allocated using the equivalent of [sqlite3_mprintf()] and

331

** *errmsg is made to point to that message.

332

**

333

** {F12134} The [sqlite3_exec()] routine does not change the value of

334

** *errmsg if errmsg is NULL or if there are no errors.

335

**

336

** {F12137} The [sqlite3_exec()] function sets the error code and message

337

** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and

338

** [sqlite3_errmsg16()].

339

**

340

** LIMITATIONS:

341

**

342

** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open

343

** [database connection].

344

**

345

** {U12142} The database connection must not be closed while

346

** [sqlite3_exec()] is running.

347

**

348

** {U12143} The calling function is should use [sqlite3_free()] to free

349

** the memory that *errmsg is left pointing at once the error

350

** message is no longer needed.

351

**

352

** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]

353

** must remain unchanged while [sqlite3_exec()] is running.

354

*/

355

int sqlite3_exec(

356

sqlite3*, /* An open database */

357

const char *sql, /* SQL to be evaluted */

358

int (*callback)(void*,int,char**,char**), /* Callback function */

359

void *, /* 1st argument to callback */

360

char **errmsg /* Error msg written here */

361

);

362

363

/*

364

** CAPI3REF: Result Codes {F10210}

365

** KEYWORDS: SQLITE_OK {error code} {error codes}

366

**

367

** Many SQLite functions return an integer result code from the set shown

368

** here in order to indicates success or failure.

369

**

370

** See also: [SQLITE_IOERR_READ | extended result codes]

371

*/

372

#define SQLITE_OK 0 /* Successful result */

373

/* beginning-of-error-codes */

374

#define SQLITE_ERROR 1 /* SQL error or missing database */

375

#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */

376

#define SQLITE_PERM 3 /* Access permission denied */

377

#define SQLITE_ABORT 4 /* Callback routine requested an abort */

378

#define SQLITE_BUSY 5 /* The database file is locked */

379

#define SQLITE_LOCKED 6 /* A table in the database is locked */

380

#define SQLITE_NOMEM 7 /* A malloc() failed */

381

#define SQLITE_READONLY 8 /* Attempt to write a readonly database */

382

#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/

383

#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */

384

#define SQLITE_CORRUPT 11 /* The database disk image is malformed */

385

#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */

386

#define SQLITE_FULL 13 /* Insertion failed because database is full */

387

#define SQLITE_CANTOPEN 14 /* Unable to open the database file */

388

#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */

389

#define SQLITE_EMPTY 16 /* Database is empty */

390

#define SQLITE_SCHEMA 17 /* The database schema changed */

391

#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */

392

#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */

393

#define SQLITE_MISMATCH 20 /* Data type mismatch */

394

#define SQLITE_MISUSE 21 /* Library used incorrectly */

395

#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */

396

#define SQLITE_AUTH 23 /* Authorization denied */

397

#define SQLITE_FORMAT 24 /* Auxiliary database format error */

398

#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */

399

#define SQLITE_NOTADB 26 /* File opened that is not a database file */

400

#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */

401

#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */

402

/* end-of-error-codes */

403

404

/*

405

** CAPI3REF: Extended Result Codes {F10220}

406

** KEYWORDS: {extended error code} {extended error codes}

407

** KEYWORDS: {extended result codes}

408

**

409

** In its default configuration, SQLite API routines return one of 26 integer

410

** [SQLITE_OK | result codes]. However, experience has shown that

411

** many of these result codes are too course-grained. They do not provide as

412

** much information about problems as programmers might like. In an effort to

413

** address this, newer versions of SQLite (version 3.3.8 and later) include

414

** support for additional result codes that provide more detailed information

415

** about errors. The extended result codes are enabled or disabled

416

** for each database connection using the [sqlite3_extended_result_codes()]

417

** API.

418

**

419

** Some of the available extended result codes are listed here.

420

** One may expect the number of extended result codes will be expand

421

** over time. Software that uses extended result codes should expect

422

** to see new result codes in future releases of SQLite.

423

**

424

** The SQLITE_OK result code will never be extended. It will always

425

** be exactly zero.

426

**

427

** INVARIANTS:

428

**

429

** {F10223} The symbolic name for an extended result code always contains

430

** a related primary result code as a prefix.

431

**

432

** {F10224} Primary result code names contain a single "_" character.

433

**

434

** {F10225} Extended result code names contain two or more "_" characters.

435

**

436

** {F10226} The numeric value of an extended result code contains the

437

** numeric value of its corresponding primary result code in

438

** its least significant 8 bits.

439

*/

440

#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))

441

#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))

442

#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))

443

#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))

444

#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))

445

#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))

446

#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))

447

#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))

448

#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))

449

#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))

450

#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))

451

#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))

452

453

/*

454

** CAPI3REF: Flags For File Open Operations {F10230}

455

**

456

** These bit values are intended for use in the

457

** 3rd parameter to the [sqlite3_open_v2()] interface and

458

** in the 4th parameter to the xOpen method of the

459

** [sqlite3_vfs] object.

460

*/

461

#define SQLITE_OPEN_READONLY 0x00000001

462

#define SQLITE_OPEN_READWRITE 0x00000002

463

#define SQLITE_OPEN_CREATE 0x00000004

464

#define SQLITE_OPEN_DELETEONCLOSE 0x00000008

465

#define SQLITE_OPEN_EXCLUSIVE 0x00000010

466

#define SQLITE_OPEN_MAIN_DB 0x00000100

467

#define SQLITE_OPEN_TEMP_DB 0x00000200

468

#define SQLITE_OPEN_TRANSIENT_DB 0x00000400

469

#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800

470

#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000

471

#define SQLITE_OPEN_SUBJOURNAL 0x00002000

472

#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000

473

474

/*

475

** CAPI3REF: Device Characteristics {F10240}

476

**

477

** The xDeviceCapabilities method of the [sqlite3_io_methods]

478

** object returns an integer which is a vector of the these

479

** bit values expressing I/O characteristics of the mass storage

480

** device that holds the file that the [sqlite3_io_methods]

481

** refers to.

482

**

483

** The SQLITE_IOCAP_ATOMIC property means that all writes of

484

** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values

485

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

486

** are aligned to an address which is an integer multiple of

487

** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means

488

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

489

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

490

** way around. The SQLITE_IOCAP_SEQUENTIAL property means that

491

** information is written to disk in the same order as calls

492

** to xWrite().

493

*/

494

#define SQLITE_IOCAP_ATOMIC 0x00000001

495

#define SQLITE_IOCAP_ATOMIC512 0x00000002

496

#define SQLITE_IOCAP_ATOMIC1K 0x00000004

497

#define SQLITE_IOCAP_ATOMIC2K 0x00000008

498

#define SQLITE_IOCAP_ATOMIC4K 0x00000010

499

#define SQLITE_IOCAP_ATOMIC8K 0x00000020

500

#define SQLITE_IOCAP_ATOMIC16K 0x00000040

501

#define SQLITE_IOCAP_ATOMIC32K 0x00000080

502

#define SQLITE_IOCAP_ATOMIC64K 0x00000100

503

#define SQLITE_IOCAP_SAFE_APPEND 0x00000200

504

#define SQLITE_IOCAP_SEQUENTIAL 0x00000400

505

506

/*

507

** CAPI3REF: File Locking Levels {F10250}

508

**

509

** SQLite uses one of these integer values as the second

510

** argument to calls it makes to the xLock() and xUnlock() methods

511

** of an [sqlite3_io_methods] object.

512

*/

513

#define SQLITE_LOCK_NONE 0

514

#define SQLITE_LOCK_SHARED 1

515

#define SQLITE_LOCK_RESERVED 2

516

#define SQLITE_LOCK_PENDING 3

517

#define SQLITE_LOCK_EXCLUSIVE 4

518

519

/*

520

** CAPI3REF: Synchronization Type Flags {F10260}

521

**

522

** When SQLite invokes the xSync() method of an

523

** [sqlite3_io_methods] object it uses a combination of

524

** these integer values as the second argument.

525

**

526

** When the SQLITE_SYNC_DATAONLY flag is used, it means that the

527

** sync operation only needs to flush data to mass storage. Inode

528

** information need not be flushed. The SQLITE_SYNC_NORMAL flag means

529

** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means

530

** to use Mac OS-X style fullsync instead of fsync().

531

*/

532

#define SQLITE_SYNC_NORMAL 0x00002

533

#define SQLITE_SYNC_FULL 0x00003

534

#define SQLITE_SYNC_DATAONLY 0x00010

535

536

537

/*

538

** CAPI3REF: OS Interface Open File Handle {F11110}

539

**

540

** An [sqlite3_file] object represents an open file in the OS

541

** interface layer. Individual OS interface implementations will

542

** want to subclass this object by appending additional fields

543

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

544

** [sqlite3_io_methods] object that defines methods for performing

545

** I/O operations on the open file.

546

*/

547

typedef struct sqlite3_file sqlite3_file;

548

struct sqlite3_file {

549

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

550

};

551

552

/*

553

** CAPI3REF: OS Interface File Virtual Methods Object {F11120}

554

**

555

** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to

556

** an instance of this object. This object defines the

557

** methods used to perform various operations against the open file.

558

**

559

** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or

560

** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().

561

* The second choice is an

562

** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to

563

** indicate that only the data of the file and not its inode needs to be

564

** synced.

565

**

566

** The integer values to xLock() and xUnlock() are one of

567

** <ul>

568

** <li> [SQLITE_LOCK_NONE],

569

** <li> [SQLITE_LOCK_SHARED],

570

** <li> [SQLITE_LOCK_RESERVED],

571

** <li> [SQLITE_LOCK_PENDING], or

572

** <li> [SQLITE_LOCK_EXCLUSIVE].

573

** </ul>

574

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

575

** The xCheckReservedLock() method looks

576

** to see if any database connection, either in this

577

** process or in some other process, is holding an RESERVED,

578

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

579

** if such a lock exists and false if not.

580

**

581

** The xFileControl() method is a generic interface that allows custom

582

** VFS implementations to directly control an open file using the

583

** [sqlite3_file_control()] interface. The second "op" argument

584

** is an integer opcode. The third

585

** argument is a generic pointer which is intended to be a pointer

586

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

587

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

588

** functions to enable blocking locks with timeouts, to change the

589

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

590

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

591

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

592

** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.

593

** Applications that define a custom xFileControl method should use opcodes

594

** greater than 100 to avoid conflicts.

595

**

596

** The xSectorSize() method returns the sector size of the

597

** device that underlies the file. The sector size is the

598

** minimum write that can be performed without disturbing

599

** other bytes in the file. The xDeviceCharacteristics()

600

** method returns a bit vector describing behaviors of the

601

** underlying device:

602

**

603

** <ul>

604

** <li> [SQLITE_IOCAP_ATOMIC]

605

** <li> [SQLITE_IOCAP_ATOMIC512]

606

** <li> [SQLITE_IOCAP_ATOMIC1K]

607

** <li> [SQLITE_IOCAP_ATOMIC2K]

608

** <li> [SQLITE_IOCAP_ATOMIC4K]

609

** <li> [SQLITE_IOCAP_ATOMIC8K]

610

** <li> [SQLITE_IOCAP_ATOMIC16K]

611

** <li> [SQLITE_IOCAP_ATOMIC32K]

612

** <li> [SQLITE_IOCAP_ATOMIC64K]

613

** <li> [SQLITE_IOCAP_SAFE_APPEND]

614

** <li> [SQLITE_IOCAP_SEQUENTIAL]

615

** </ul>

616

**

617

** The SQLITE_IOCAP_ATOMIC property means that all writes of

618

** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values

619

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

620

** are aligned to an address which is an integer multiple of

621

** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means

622

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

623

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

624

** way around. The SQLITE_IOCAP_SEQUENTIAL property means that

625

** information is written to disk in the same order as calls

626

** to xWrite().

627

*/

628

typedef struct sqlite3_io_methods sqlite3_io_methods;

629

struct sqlite3_io_methods {

630

int iVersion;

631

int (*xClose)(sqlite3_file*);

632

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

633

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

634

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

635

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

636

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

637

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

638

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

639

int (*xCheckReservedLock)(sqlite3_file*);

640

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

641

int (*xSectorSize)(sqlite3_file*);

642

int (*xDeviceCharacteristics)(sqlite3_file*);

643

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

644

};

645

646

/*

647

** CAPI3REF: Standard File Control Opcodes {F11310}

648

**

649

** These integer constants are opcodes for the xFileControl method

650

** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]

651

** interface.

652

**

653

** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This

654

** opcode causes the xFileControl method to write the current state of

655

** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],

656

** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])

657

** into an integer that the pArg argument points to. This capability

658

** is used during testing and only needs to be supported when SQLITE_TEST

659

** is defined.

660

*/

661

#define SQLITE_FCNTL_LOCKSTATE 1

662

663

/*

664

** CAPI3REF: Mutex Handle {F17110}

665

**

666

** The mutex module within SQLite defines [sqlite3_mutex] to be an

667

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

668

** at the internal representation of an [sqlite3_mutex]. It only

669

** deals with pointers to the [sqlite3_mutex] object.

670

**

671

** Mutexes are created using [sqlite3_mutex_alloc()].

672

*/

673

typedef struct sqlite3_mutex sqlite3_mutex;

674

675

/*

676

** CAPI3REF: OS Interface Object {F11140}

677

**

678

** An instance of this object defines the interface between the

679

** SQLite core and the underlying operating system. The "vfs"

680

** in the name of the object stands for "virtual file system".

681

**

682

** The iVersion field is initially 1 but may be larger for future

683

** versions of SQLite. Additional fields may be appended to this

684

** object when the iVersion value is increased.

685

**

686

** The szOsFile field is the size of the subclassed [sqlite3_file]

687

** structure used by this VFS. mxPathname is the maximum length of

688

** a pathname in this VFS.

689

**

690

** Registered sqlite3_vfs objects are kept on a linked list formed by

691

** the pNext pointer. The [sqlite3_vfs_register()]

692

** and [sqlite3_vfs_unregister()] interfaces manage this list

693

** in a thread-safe way. The [sqlite3_vfs_find()] interface

694

** searches the list.

695

**

696

** The pNext field is the only field in the sqlite3_vfs

697

** structure that SQLite will ever modify. SQLite will only access

698

** or modify this field while holding a particular static mutex.

699

** The application should never modify anything within the sqlite3_vfs

700

** object once the object has been registered.

701

**

702

** The zName field holds the name of the VFS module. The name must

703

** be unique across all VFS modules.

704

**

705

** {F11141} SQLite will guarantee that the zFilename string passed to

706

** xOpen() is a full pathname as generated by xFullPathname() and

707

** that the string will be valid and unchanged until xClose() is

708

** called. {END} So the [sqlite3_file] can store a pointer to the

709

** filename if it needs to remember the filename for some reason.

710

**

711

** {F11142} The flags argument to xOpen() includes all bits set in

712

** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]

713

** or [sqlite3_open16()] is used, then flags includes at least

714

** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}

715

** If xOpen() opens a file read-only then it sets *pOutFlags to

716

** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be

717

** set.

718

**

719

** {F11143} SQLite will also add one of the following flags to the xOpen()

720

** call, depending on the object being opened:

721

**

722

** <ul>

723

** <li> [SQLITE_OPEN_MAIN_DB]

724

** <li> [SQLITE_OPEN_MAIN_JOURNAL]

725

** <li> [SQLITE_OPEN_TEMP_DB]

726

** <li> [SQLITE_OPEN_TEMP_JOURNAL]

727

** <li> [SQLITE_OPEN_TRANSIENT_DB]

728

** <li> [SQLITE_OPEN_SUBJOURNAL]

729

** <li> [SQLITE_OPEN_MASTER_JOURNAL]

730

** </ul> {END}

731

**

732

** The file I/O implementation can use the object type flags to

733

** changes the way it deals with files. For example, an application

734

** that does not care about crash recovery or rollback might make

735

** the open of a journal file a no-op. Writes to this journal would

736

** also be no-ops, and any attempt to read the journal would return

737

** SQLITE_IOERR. Or the implementation might recognize that a database

738

** file will be doing page-aligned sector reads and writes in a random

739

** order and set up its I/O subsystem accordingly.

740

**

741

** SQLite might also add one of the following flags to the xOpen

742

** method:

743

**

744

** <ul>

745

** <li> [SQLITE_OPEN_DELETEONCLOSE]

746

** <li> [SQLITE_OPEN_EXCLUSIVE]

747

** </ul>

748

**

749

** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be

750

** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE]

751

** will be set for TEMP databases, journals and for subjournals.

752

** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened

753

** for exclusive access. This flag is set for all files except

754

** for the main database file. {END}

755

**

756

** {F11148} At least szOsFile bytes of memory are allocated by SQLite

757

** to hold the [sqlite3_file] structure passed as the third

758

** argument to xOpen. {END} The xOpen method does not have to

759

** allocate the structure; it should just fill it in.

760

**

761

** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]

762

** to test for the existance of a file,

763

** or [SQLITE_ACCESS_READWRITE] to test to see

764

** if a file is readable and writable, or [SQLITE_ACCESS_READ]

765

** to test to see if a file is at least readable. {END} The file can be a

766

** directory.

767

**

768

** {F11150} SQLite will always allocate at least mxPathname+1 bytes for

769

** the output buffers for xGetTempname and xFullPathname. {F11151} The exact

770

** size of the output buffer is also passed as a parameter to both

771

** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN

772

** should be returned. As this is handled as a fatal error by SQLite,

773

** vfs implementations should endeavor to prevent this by setting

774

** mxPathname to a sufficiently large value.

775

**

776

** The xRandomness(), xSleep(), and xCurrentTime() interfaces

777

** are not strictly a part of the filesystem, but they are

778

** included in the VFS structure for completeness.

779

** The xRandomness() function attempts to return nBytes bytes

780

** of good-quality randomness into zOut. The return value is

781

** the actual number of bytes of randomness obtained. The

782

** xSleep() method causes the calling thread to sleep for at

783

** least the number of microseconds given. The xCurrentTime()

784

** method returns a Julian Day Number for the current date and

785

** time.

786

*/

787

typedef struct sqlite3_vfs sqlite3_vfs;

788

struct sqlite3_vfs {

789

int iVersion; /* Structure version number */

790

int szOsFile; /* Size of subclassed sqlite3_file */

791

int mxPathname; /* Maximum file pathname length */

792

sqlite3_vfs *pNext; /* Next registered VFS */

793

const char *zName; /* Name of this virtual file system */

794

void *pAppData; /* Pointer to application-specific data */

795

int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,

796

int flags, int *pOutFlags);

797

int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);

798

int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);

799

int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);

800

int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);

801

void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);

802

void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);

803

void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);

804

void (*xDlClose)(sqlite3_vfs*, void*);

805

int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);

806

int (*xSleep)(sqlite3_vfs*, int microseconds);

807

int (*xCurrentTime)(sqlite3_vfs*, double*);

808

/* New fields may be appended in figure versions. The iVersion

809

** value will increment whenever this happens. */

810

};

811

812

/*

813

** CAPI3REF: Flags for the xAccess VFS method {F11190}

814

**

815

** {F11191} These integer constants can be used as the third parameter to

816

** the xAccess method of an [sqlite3_vfs] object. {END} They determine

817

** what kind of permissions the xAccess method is

818

** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method

819

** simply checks to see if the file exists. {F11193} With

820

** SQLITE_ACCESS_READWRITE, the xAccess method checks to see

821

** if the file is both readable and writable. {F11194} With

822

** SQLITE_ACCESS_READ the xAccess method

823

** checks to see if the file is readable.

824

*/

825

#define SQLITE_ACCESS_EXISTS 0

826

#define SQLITE_ACCESS_READWRITE 1

827

#define SQLITE_ACCESS_READ 2

828

829

/*

830

** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}

831

**

832

** The sqlite3_extended_result_codes() routine enables or disables the

833

** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.

834

** The extended result codes are disabled by default for historical

835

** compatibility.

836

**

837

** INVARIANTS:

838

**

839

** {F12201} Each new [database connection] has the

840

** [extended result codes] feature

841

** disabled by default.

842

**

843

** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable

844

** [extended result codes] for the

845

** [database connection] D if the F parameter

846

** is true, or disable them if F is false.

847

*/

848

int sqlite3_extended_result_codes(sqlite3*, int onoff);

849

850

/*

851

** CAPI3REF: Last Insert Rowid {F12220}

852

**

853

** Each entry in an SQLite table has a unique 64-bit signed

854

** integer key called the "rowid". The rowid is always available

855

** as an undeclared column named ROWID, OID, or _ROWID_ as long as those

856

** names are not also used by explicitly declared columns. If

857

** the table has a column of type INTEGER PRIMARY KEY then that column

858

** is another alias for the rowid.

859

**

860

** This routine returns the rowid of the most recent

861

** successful INSERT into the database from the database connection

862

** shown in the first argument. If no successful inserts

863

** have ever occurred on this database connection, zero is returned.

864

**

865

** If an INSERT occurs within a trigger, then the rowid of the

866

** inserted row is returned by this routine as long as the trigger

867

** is running. But once the trigger terminates, the value returned

868

** by this routine reverts to the last value inserted before the

869

** trigger fired.

870

**

871

** An INSERT that fails due to a constraint violation is not a

872

** successful insert and does not change the value returned by this

873

** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,

874

** and INSERT OR ABORT make no changes to the return value of this

875

** routine when their insertion fails. When INSERT OR REPLACE

876

** encounters a constraint violation, it does not fail. The

877

** INSERT continues to completion after deleting rows that caused

878

** the constraint problem so INSERT OR REPLACE will always change

879

** the return value of this interface.

880

**

881

** For the purposes of this routine, an insert is considered to

882

** be successful even if it is subsequently rolled back.

883

**

884

** INVARIANTS:

885

**

886

** {F12221} The [sqlite3_last_insert_rowid()] function returns the

887

** rowid of the most recent successful insert done

888

** on the same database connection and within the same

889

** trigger context, or zero if there have

890

** been no qualifying inserts on that connection.

891

**

892

** {F12223} The [sqlite3_last_insert_rowid()] function returns

893

** same value when called from the same trigger context

894

** immediately before and after a ROLLBACK.

895

**

896

** LIMITATIONS:

897

**

898

** {U12232} If a separate thread does a new insert on the same

899

** database connection while the [sqlite3_last_insert_rowid()]

900

** function is running and thus changes the last insert rowid,

901

** then the value returned by [sqlite3_last_insert_rowid()] is

902

** unpredictable and might not equal either the old or the new

903

** last insert rowid.

904

*/

905

sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);

906

907

/*

908

** CAPI3REF: Count The Number Of Rows Modified {F12240}

909

**

910

** This function returns the number of database rows that were changed

911

** or inserted or deleted by the most recently completed SQL statement

912

** on the connection specified by the first parameter. Only

913

** changes that are directly specified by the INSERT, UPDATE, or

914

** DELETE statement are counted. Auxiliary changes caused by

915

** triggers are not counted. Use the [sqlite3_total_changes()] function

916

** to find the total number of changes including changes caused by triggers.

917

**

918

** A "row change" is a change to a single row of a single table

919

** caused by an INSERT, DELETE, or UPDATE statement. Rows that

920

** are changed as side effects of REPLACE constraint resolution,

921

** rollback, ABORT processing, DROP TABLE, or by any other

922

** mechanisms do not count as direct row changes.

923

**

924

** A "trigger context" is a scope of execution that begins and

925

** ends with the script of a trigger. Most SQL statements are

926

** evaluated outside of any trigger. This is the "top level"

927

** trigger context. If a trigger fires from the top level, a

928

** new trigger context is entered for the duration of that one

929

** trigger. Subtriggers create subcontexts for their duration.

930

**

931

** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does

932

** not create a new trigger context.

933

**

934

** This function returns the number of direct row changes in the

935

** most recent INSERT, UPDATE, or DELETE statement within the same

936

** trigger context.

937

**

938

** So when called from the top level, this function returns the

939

** number of changes in the most recent INSERT, UPDATE, or DELETE

940

** that also occurred at the top level.

941

** Within the body of a trigger, the sqlite3_changes() interface

942

** can be called to find the number of

943

** changes in the most recently completed INSERT, UPDATE, or DELETE

944

** statement within the body of the same trigger.

945

** However, the number returned does not include in changes

946

** caused by subtriggers since they have their own context.

947

**

948

** SQLite implements the command "DELETE FROM table" without

949

** a WHERE clause by dropping and recreating the table. (This is much

950

** faster than going through and deleting individual elements from the

951

** table.) Because of this optimization, the deletions in

952

** "DELETE FROM table" are not row changes and will not be counted

953

** by the sqlite3_changes() or [sqlite3_total_changes()] functions.

954

** To get an accurate count of the number of rows deleted, use

955

** "DELETE FROM table WHERE 1" instead.

956

**

957

** INVARIANTS:

958

**

959

** {F12241} The [sqlite3_changes()] function returns the number of

960

** row changes caused by the most recent INSERT, UPDATE,

961

** or DELETE statement on the same database connection and

962

** within the same trigger context, or zero if there have

963

** not been any qualifying row changes.

964

**

965

** LIMITATIONS:

966

**

967

** {U12252} If a separate thread makes changes on the same database connection

968

** while [sqlite3_changes()] is running then the value returned

969

** is unpredictable and unmeaningful.

970

*/

971

int sqlite3_changes(sqlite3*);

972

973

/*

974

** CAPI3REF: Total Number Of Rows Modified {F12260}

975

***

976

** This function returns the number of row changes caused

977

** by INSERT, UPDATE or DELETE statements since the database handle

978

** was opened. The count includes all changes from all trigger

979

** contexts. But the count does not include changes used to

980

** implement REPLACE constraints, do rollbacks or ABORT processing,

981

** or DROP table processing.

982

** The changes

983

** are counted as soon as the statement that makes them is completed

984

** (when the statement handle is passed to [sqlite3_reset()] or

985

** [sqlite3_finalize()]).

986

**

987

** SQLite implements the command "DELETE FROM table" without

988

** a WHERE clause by dropping and recreating the table. (This is much

989

** faster than going

990

** through and deleting individual elements from the table.) Because of

991

** this optimization, the change count for "DELETE FROM table" will be

992

** zero regardless of the number of elements that were originally in the

993

** table. To get an accurate count of the number of rows deleted, use

994

** "DELETE FROM table WHERE 1" instead.

995

**

996

** See also the [sqlite3_changes()] interface.

997

**

998

** INVARIANTS:

999

**

1000

** {F12261} The [sqlite3_total_changes()] returns the total number

1001

** of row changes caused by INSERT, UPDATE, and/or DELETE

1002

** statements on the same [database connection], in any

1003

** trigger context, since the database connection was

1004

** created.

1005

**

1006

** LIMITATIONS:

1007

**

1008

** {U12264} If a separate thread makes changes on the same database connection

1009

** while [sqlite3_total_changes()] is running then the value

1010

** returned is unpredictable and unmeaningful.

1011

*/

1012

int sqlite3_total_changes(sqlite3*);

1013

1014

/*

1015

** CAPI3REF: Interrupt A Long-Running Query {F12270}

1016

**

1017

** This function causes any pending database operation to abort and

1018

** return at its earliest opportunity. This routine is typically

1019

** called in response to a user action such as pressing "Cancel"

1020

** or Ctrl-C where the user wants a long query operation to halt

1021

** immediately.

1022

**

1023

** It is safe to call this routine from a thread different from the

1024

** thread that is currently running the database operation. But it

1025

** is not safe to call this routine with a database connection that

1026

** is closed or might close before sqlite3_interrupt() returns.

1027

**

1028

** If an SQL is very nearly finished at the time when sqlite3_interrupt()

1029

** is called, then it might not have an opportunity to be interrupted.

1030

** It might continue to completion.

1031

** An SQL operation that is interrupted will return

1032

** [SQLITE_INTERRUPT]. If the interrupted SQL operation is an

1033

** INSERT, UPDATE, or DELETE that is inside an explicit transaction,

1034

** then the entire transaction will be rolled back automatically.

1035

** A call to sqlite3_interrupt() has no effect on SQL statements

1036

** that are started after sqlite3_interrupt() returns.

1037

**

1038

** INVARIANTS:

1039

**

1040

** {F12271} The [sqlite3_interrupt()] interface will force all running

1041

** SQL statements associated with the same database connection

1042

** to halt after processing at most one additional row of

1043

** data.

1044

**

1045

** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]

1046

** will return [SQLITE_INTERRUPT].

1047

**

1048

** LIMITATIONS:

1049

**

1050

** {U12279} If the database connection closes while [sqlite3_interrupt()]

1051

** is running then bad things will likely happen.

1052

*/

1053

void sqlite3_interrupt(sqlite3*);

1054

1055

/*

1056

** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}

1057

**

1058

** These routines are useful for command-line input to determine if the

1059

** currently entered text seems to form complete a SQL statement or

1060

** if additional input is needed before sending the text into

1061

** SQLite for parsing. These routines return true if the input string

1062

** appears to be a complete SQL statement. A statement is judged to be

1063

** complete if it ends with a semicolon token and is not a fragment of a

1064

** CREATE TRIGGER statement. Semicolons that are embedded within

1065

** string literals or quoted identifier names or comments are not

1066

** independent tokens (they are part of the token in which they are

1067

** embedded) and thus do not count as a statement terminator.

1068

**

1069

** These routines do not parse the SQL and

1070

** so will not detect syntactically incorrect SQL.

1071

**

1072

** INVARIANTS:

1073

**

1074

** {F10511} The sqlite3_complete() and sqlite3_complete16() functions

1075

** return true (non-zero) if and only if the last

1076

** non-whitespace token in their input is a semicolon that

1077

** is not in between the BEGIN and END of a CREATE TRIGGER

1078

** statement.

1079

**

1080

** LIMITATIONS:

1081

**

1082

** {U10512} The input to sqlite3_complete() must be a zero-terminated

1083

** UTF-8 string.

1084

**

1085

** {U10513} The input to sqlite3_complete16() must be a zero-terminated

1086

** UTF-16 string in native byte order.

1087

*/

1088

int sqlite3_complete(const char *sql);

1089

int sqlite3_complete16(const void *sql);

1090

1091

/*

1092

** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}

1093

**

1094

** This routine identifies a callback function that might be

1095

** invoked whenever an attempt is made to open a database table

1096

** that another thread or process has locked.

1097

** If the busy callback is NULL, then [SQLITE_BUSY]

1098

** or [SQLITE_IOERR_BLOCKED]

1099

** is returned immediately upon encountering the lock.

1100

** If the busy callback is not NULL, then the

1101

** callback will be invoked with two arguments. The

1102

** first argument to the handler is a copy of the void* pointer which

1103

** is the third argument to this routine. The second argument to

1104

** the handler is the number of times that the busy handler has

1105

** been invoked for this locking event. If the

1106

** busy callback returns 0, then no additional attempts are made to

1107

** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.

1108

** If the callback returns non-zero, then another attempt

1109

** is made to open the database for reading and the cycle repeats.

1110

**

1111

** The presence of a busy handler does not guarantee that

1112

** it will be invoked when there is lock contention.

1113

** If SQLite determines that invoking the busy handler could result in

1114

** a deadlock, it will go ahead and return [SQLITE_BUSY] or

1115

** [SQLITE_IOERR_BLOCKED] instead of invoking the

1116

** busy handler.

1117

** Consider a scenario where one process is holding a read lock that

1118

** it is trying to promote to a reserved lock and

1119

** a second process is holding a reserved lock that it is trying

1120

** to promote to an exclusive lock. The first process cannot proceed

1121

** because it is blocked by the second and the second process cannot

1122

** proceed because it is blocked by the first. If both processes

1123

** invoke the busy handlers, neither will make any progress. Therefore,

1124

** SQLite returns [SQLITE_BUSY] for the first process, hoping that this

1125

** will induce the first process to release its read lock and allow

1126

** the second process to proceed.

1127

**

1128

** The default busy callback is NULL.

1129

**

1130

** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]

1131

** when SQLite is in the middle of a large transaction where all the

1132

** changes will not fit into the in-memory cache. SQLite will

1133

** already hold a RESERVED lock on the database file, but it needs

1134

** to promote this lock to EXCLUSIVE so that it can spill cache

1135

** pages into the database file without harm to concurrent

1136

** readers. If it is unable to promote the lock, then the in-memory

1137

** cache will be left in an inconsistent state and so the error

1138

** code is promoted from the relatively benign [SQLITE_BUSY] to

1139

** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion

1140

** forces an automatic rollback of the changes. See the

1141

** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">

1142

** CorruptionFollowingBusyError</a> wiki page for a discussion of why

1143

** this is important.

1144

**

1145

** There can only be a single busy handler defined for each database

1146

** connection. Setting a new busy handler clears any previous one.

1147

** Note that calling [sqlite3_busy_timeout()] will also set or clear

1148

** the busy handler.

1149

**

1150

** INVARIANTS:

1151

**

1152

** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler

1153

** callback in the database connection identified by the 1st

1154

** parameter with a new busy handler identified by the 2nd and 3rd

1155

** parameters.

1156

**

1157

** {F12312} The default busy handler for new database connections is NULL.

1158

**

1159

** {F12314} When two or more database connection share a common cache,

1160

** the busy handler for the database connection currently using

1161

** the cache is invoked when the cache encounters a lock.

1162

**

1163

** {F12316} If a busy handler callback returns zero, then the SQLite

1164

** interface that provoked the locking event will return

1165

** [SQLITE_BUSY].

1166

**

1167

** {F12318} SQLite will invokes the busy handler with two argument which

1168

** are a copy of the pointer supplied by the 3rd parameter to

1169

** [sqlite3_busy_handler()] and a count of the number of prior

1170

** invocations of the busy handler for the same locking event.

1171

**

1172

** LIMITATIONS:

1173

**

1174

** {U12319} A busy handler should not call close the database connection

1175

** or prepared statement that invoked the busy handler.

1176

*/

1177

int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

1178

1179

/*

1180

** CAPI3REF: Set A Busy Timeout {F12340}

1181

**

1182

** This routine sets a [sqlite3_busy_handler | busy handler]

1183

** that sleeps for a while when a

1184

** table is locked. The handler will sleep multiple times until

1185

** at least "ms" milliseconds of sleeping have been done. {F12343} After

1186

** "ms" milliseconds of sleeping, the handler returns 0 which

1187

** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].

1188

**

1189

** Calling this routine with an argument less than or equal to zero

1190

** turns off all busy handlers.

1191

**

1192

** There can only be a single busy handler for a particular database

1193

** connection. If another busy handler was defined

1194

** (using [sqlite3_busy_handler()]) prior to calling

1195

** this routine, that other busy handler is cleared.

1196

**

1197

** INVARIANTS:

1198

**

1199

** {F12341} The [sqlite3_busy_timeout()] function overrides any prior

1200

** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting

1201

** on the same database connection.

1202

**

1203

** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than

1204

** or equal to zero, then the busy handler is cleared so that

1205

** all subsequent locking events immediately return [SQLITE_BUSY].

1206

**

1207

** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive

1208

** number N, then a busy handler is set that repeatedly calls

1209

** the xSleep() method in the VFS interface until either the

1210

** lock clears or until the cumulative sleep time reported back

1211

** by xSleep() exceeds N milliseconds.

1212

*/

1213

int sqlite3_busy_timeout(sqlite3*, int ms);

1214

1215

/*

1216

** CAPI3REF: Convenience Routines For Running Queries {F12370}

1217

**

1218

** Definition: A result table is memory data structure created by the

1219

** [sqlite3_get_table()] interface. A result table records the

1220

** complete query results from one or more queries.

1221

**

1222

** The table conceptually has a number of rows and columns. But

1223

** these numbers are not part of the result table itself. These

1224

** numbers are obtained separately. Let N be the number of rows

1225

** and M be the number of columns.

1226

**

1227

** A result table is an array of pointers to zero-terminated

1228

** UTF-8 strings. There are (N+1)*M elements in the array.

1229

** The first M pointers point to zero-terminated strings that

1230

** contain the names of the columns.

1231

** The remaining entries all point to query results. NULL

1232

** values are give a NULL pointer. All other values are in

1233

** their UTF-8 zero-terminated string representation as returned by

1234

** [sqlite3_column_text()].

1235

**

1236

** A result table might consists of one or more memory allocations.

1237

** It is not safe to pass a result table directly to [sqlite3_free()].

1238

** A result table should be deallocated using [sqlite3_free_table()].

1239

**

1240

** As an example of the result table format, suppose a query result

1241

** is as follows:

1242

**

1243

** <blockquote><pre>

1244

** Name | Age

1245

** -----------------------

1246

** Alice | 43

1247

** Bob | 28

1248

** Cindy | 21

1249

** </pre></blockquote>

1250

**

1251

** There are two column (M==2) and three rows (N==3). Thus the

1252

** result table has 8 entries. Suppose the result table is stored

1253

** in an array names azResult. Then azResult holds this content:

1254

**

1255

** <blockquote><pre>

1256

** azResult[0] = "Name";

1257

** azResult[1] = "Age";

1258

** azResult[2] = "Alice";

1259

** azResult[3] = "43";

1260

** azResult[4] = "Bob";

1261

** azResult[5] = "28";

1262

** azResult[6] = "Cindy";

1263

** azResult[7] = "21";

1264

** </pre></blockquote>

1265

**

1266

** The sqlite3_get_table() function evaluates one or more

1267

** semicolon-separated SQL statements in the zero-terminated UTF-8

1268

** string of its 2nd parameter. It returns a result table to the

1269

** pointer given in its 3rd parameter.

1270

**

1271

** After the calling function has finished using the result, it should

1272

** pass the pointer to the result table to sqlite3_free_table() in order to

1273

** release the memory that was malloc-ed. Because of the way the

1274

** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling

1275

** function must not try to call [sqlite3_free()] directly. Only

1276

** [sqlite3_free_table()] is able to release the memory properly and safely.

1277

**

1278

** The sqlite3_get_table() interface is implemented as a wrapper around

1279

** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access

1280

** to any internal data structures of SQLite. It uses only the public

1281

** interface defined here. As a consequence, errors that occur in the

1282

** wrapper layer outside of the internal [sqlite3_exec()] call are not

1283

** reflected in subsequent calls to [sqlite3_errcode()] or

1284

** [sqlite3_errmsg()].

1285

**

1286

** INVARIANTS:

1287

**

1288

** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then

1289

** it frees the result table under construction, aborts the

1290

** query in process, skips any subsequent queries, sets the

1291

** *resultp output pointer to NULL and returns [SQLITE_NOMEM].

1292

**

1293

** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL

1294

** then [sqlite3_get_table()] write the number of columns in the

1295

** result set of the query into *ncolumn if the query is

1296

** successful (if the function returns SQLITE_OK).

1297

**

1298

** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL

1299

** then [sqlite3_get_table()] write the number of rows in the

1300

** result set of the query into *nrow if the query is

1301

** successful (if the function returns SQLITE_OK).

1302

**

1303

** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value

1304

** to the number of columns in the result set of the query in the

1305

** sql parameter, or to zero if the query in sql has an empty

1306

** result set.

1307

*/

1308

int sqlite3_get_table(

1309

sqlite3*, /* An open database */

1310

const char *sql, /* SQL to be evaluated */

1311

char ***pResult, /* Results of the query */

1312

int *nrow, /* Number of result rows written here */

1313

int *ncolumn, /* Number of result columns written here */

1314

char **errmsg /* Error msg written here */

1315

);

1316

void sqlite3_free_table(char **result);

1317

1318

/*

1319

** CAPI3REF: Formatted String Printing Functions {F17400}

1320

**

1321

** These routines are workalikes of the "printf()" family of functions

1322

** from the standard C library.

1323

**

1324

** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their

1325

** results into memory obtained from [sqlite3_malloc()].

1326

** The strings returned by these two routines should be

1327

** released by [sqlite3_free()]. Both routines return a

1328

** NULL pointer if [sqlite3_malloc()] is unable to allocate enough

1329

** memory to hold the resulting string.

1330

**

1331

** In sqlite3_snprintf() routine is similar to "snprintf()" from

1332

** the standard C library. The result is written into the

1333

** buffer supplied as the second parameter whose size is given by

1334

** the first parameter. Note that the order of the

1335

** first two parameters is reversed from snprintf(). This is an

1336

** historical accident that cannot be fixed without breaking

1337

** backwards compatibility. Note also that sqlite3_snprintf()

1338

** returns a pointer to its buffer instead of the number of

1339

** characters actually written into the buffer. We admit that

1340

** the number of characters written would be a more useful return

1341

** value but we cannot change the implementation of sqlite3_snprintf()

1342

** now without breaking compatibility.

1343

**

1344

** As long as the buffer size is greater than zero, sqlite3_snprintf()

1345

** guarantees that the buffer is always zero-terminated. The first

1346

** parameter "n" is the total size of the buffer, including space for

1347

** the zero terminator. So the longest string that can be completely

1348

** written will be n-1 characters.

1349

**

1350

** These routines all implement some additional formatting

1351

** options that are useful for constructing SQL statements.

1352

** All of the usual printf formatting options apply. In addition, there

1353

** is are "%q", "%Q", and "%z" options.

1354

**

1355

** The %q option works like %s in that it substitutes a null-terminated

1356

** string from the argument list. But %q also doubles every '\'' character.

1357

** %q is designed for use inside a string literal. By doubling each '\''

1358

** character it escapes that character and allows it to be inserted into

1359

** the string.

1360

**

1361

** For example, so some string variable contains text as follows:

1362

**

1363

** <blockquote><pre>

1364

** char *zText = "It's a happy day!";

1365

** </pre></blockquote>

1366

**

1367

** One can use this text in an SQL statement as follows:

1368

**

1369

** <blockquote><pre>

1370

** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);

1371

** sqlite3_exec(db, zSQL, 0, 0, 0);

1372

** sqlite3_free(zSQL);

1373

** </pre></blockquote>

1374

**

1375

** Because the %q format string is used, the '\'' character in zText

1376

** is escaped and the SQL generated is as follows:

1377

**

1378

** <blockquote><pre>

1379

** INSERT INTO table1 VALUES('It''s a happy day!')

1380

** </pre></blockquote>

1381

**

1382

** This is correct. Had we used %s instead of %q, the generated SQL

1383

** would have looked like this:

1384

**

1385

** <blockquote><pre>

1386

** INSERT INTO table1 VALUES('It's a happy day!');

1387

** </pre></blockquote>

1388

**

1389

** This second example is an SQL syntax error. As a general rule you

1390

** should always use %q instead of %s when inserting text into a string

1391

** literal.

1392

**

1393

** The %Q option works like %q except it also adds single quotes around

1394

** the outside of the total string. Or if the parameter in the argument

1395

** list is a NULL pointer, %Q substitutes the text "NULL" (without single

1396

** quotes) in place of the %Q option. {END} So, for example, one could say:

1397

**

1398

** <blockquote><pre>

1399

** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);

1400

** sqlite3_exec(db, zSQL, 0, 0, 0);

1401

** sqlite3_free(zSQL);

1402

** </pre></blockquote>

1403

**

1404

** The code above will render a correct SQL statement in the zSQL

1405

** variable even if the zText variable is a NULL pointer.

1406

**

1407

** The "%z" formatting option works exactly like "%s" with the

1408

** addition that after the string has been read and copied into

1409

** the result, [sqlite3_free()] is called on the input string. {END}

1410

**

1411

** INVARIANTS:

1412

**

1413

** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces

1414

** return either pointers to zero-terminated UTF-8 strings held in

1415

** memory obtained from [sqlite3_malloc()] or NULL pointers if

1416

** a call to [sqlite3_malloc()] fails.

1417

**

1418

** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated

1419

** UTF-8 string into the buffer pointed to by the second parameter

1420

** provided that the first parameter is greater than zero.

1421

**

1422

** {F17407} The [sqlite3_snprintf()] interface does not writes slots of

1423

** its output buffer (the second parameter) outside the range

1424

** of 0 through N-1 (where N is the first parameter)

1425

** regardless of the length of the string

1426

** requested by the format specification.

1427

**

1428

*/

1429

char *sqlite3_mprintf(const char*,...);

1430

char *sqlite3_vmprintf(const char*, va_list);

1431

char *sqlite3_snprintf(int,char*,const char*, ...);

1432

1433

/*

1434

** CAPI3REF: Memory Allocation Subsystem {F17300}

1435

**

1436

** The SQLite core uses these three routines for all of its own

1437

** internal memory allocation needs. "Core" in the previous sentence

1438

** does not include operating-system specific VFS implementation. The

1439

** windows VFS uses native malloc and free for some operations.

1440

**

1441

** The sqlite3_malloc() routine returns a pointer to a block

1442

** of memory at least N bytes in length, where N is the parameter.

1443

** If sqlite3_malloc() is unable to obtain sufficient free

1444

** memory, it returns a NULL pointer. If the parameter N to

1445

** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns

1446

** a NULL pointer.

1447

**

1448

** Calling sqlite3_free() with a pointer previously returned

1449

** by sqlite3_malloc() or sqlite3_realloc() releases that memory so

1450

** that it might be reused. The sqlite3_free() routine is

1451

** a no-op if is called with a NULL pointer. Passing a NULL pointer

1452

** to sqlite3_free() is harmless. After being freed, memory

1453

** should neither be read nor written. Even reading previously freed

1454

** memory might result in a segmentation fault or other severe error.

1455

** Memory corruption, a segmentation fault, or other severe error

1456

** might result if sqlite3_free() is called with a non-NULL pointer that

1457

** was not obtained from sqlite3_malloc() or sqlite3_free().

1458

**

1459

** The sqlite3_realloc() interface attempts to resize a

1460

** prior memory allocation to be at least N bytes, where N is the

1461

** second parameter. The memory allocation to be resized is the first

1462

** parameter. If the first parameter to sqlite3_realloc()

1463

** is a NULL pointer then its behavior is identical to calling

1464

** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().

1465

** If the second parameter to sqlite3_realloc() is zero or

1466

** negative then the behavior is exactly the same as calling

1467

** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().

1468

** Sqlite3_realloc() returns a pointer to a memory allocation

1469

** of at least N bytes in size or NULL if sufficient memory is unavailable.

1470

** If M is the size of the prior allocation, then min(N,M) bytes

1471

** of the prior allocation are copied into the beginning of buffer returned

1472

** by sqlite3_realloc() and the prior allocation is freed.

1473

** If sqlite3_realloc() returns NULL, then the prior allocation

1474

** is not freed.

1475

**

1476

** The memory returned by sqlite3_malloc() and sqlite3_realloc()

1477

** is always aligned to at least an 8 byte boundary. {END}

1478

**

1479

** The default implementation

1480

** of the memory allocation subsystem uses the malloc(), realloc()

1481

** and free() provided by the standard C library. {F17382} However, if

1482

** SQLite is compiled with the following C preprocessor macro

1483

**

1484

** <blockquote> SQLITE_MEMORY_SIZE=NNN </blockquote>

1485

**

1486

** where NNN is an integer, then SQLite create a static

1487

** array of at least NNN bytes in size and use that array

1488

** for all of its dynamic memory allocation needs. {END} Additional

1489

** memory allocator options may be added in future releases.

1490

**

1491

** In SQLite version 3.5.0 and 3.5.1, it was possible to define

1492

** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in

1493

** implementation of these routines to be omitted. That capability

1494

** is no longer provided. Only built-in memory allocators can be

1495

** used.

1496

**

1497

** The windows OS interface layer calls

1498

** the system malloc() and free() directly when converting

1499

** filenames between the UTF-8 encoding used by SQLite

1500

** and whatever filename encoding is used by the particular windows

1501

** installation. Memory allocation errors are detected, but

1502

** they are reported back as [SQLITE_CANTOPEN] or

1503

** [SQLITE_IOERR] rather than [SQLITE_NOMEM].

1504

**

1505

** INVARIANTS:

1506

**

1507

** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to

1508

** newly checked-out block of at least N bytes of memory

1509

** that is 8-byte aligned,

1510

** or it returns NULL if it is unable to fulfill the request.

1511

**

1512

** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if

1513

** N is less than or equal to zero.

1514

**

1515

** {F17305} The [sqlite3_free(P)] interface releases memory previously

1516

** returned from [sqlite3_malloc()] or [sqlite3_realloc()],

1517

** making it available for reuse.

1518

**

1519

** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op.

1520

**

1521

** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call

1522

** to [sqlite3_malloc(N)].

1523

**

1524

** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call

1525

** to [sqlite3_free(P)].

1526

**

1527

** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],

1528

** and [sqlite3_free()] for all of its memory allocation and

1529

** deallocation needs.

1530

**

1531

** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer

1532

** to a block of checked-out memory of at least N bytes in size

1533

** that is 8-byte aligned, or a NULL pointer.

1534

**

1535

** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first

1536

** copies the first K bytes of content from P into the newly allocated

1537

** where K is the lessor of N and the size of the buffer P.

1538

**

1539

** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first

1540

** releases the buffer P.

1541

**

1542

** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is

1543

** not modified or released.

1544

**

1545

** LIMITATIONS:

1546

**

1547

** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]

1548

** must be either NULL or else a pointer obtained from a prior

1549

** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has

1550

** not been released.

1551

**

1552

** {U17351} The application must not read or write any part of

1553

** a block of memory after it has been released using

1554

** [sqlite3_free()] or [sqlite3_realloc()].

1555

**

1556

*/

1557

void *sqlite3_malloc(int);

1558

void *sqlite3_realloc(void*, int);

1559

void sqlite3_free(void*);

1560

1561

/*

1562

** CAPI3REF: Memory Allocator Statistics {F17370}

1563

**

1564

** SQLite provides these two interfaces for reporting on the status

1565

** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]

1566

** the memory allocation subsystem included within the SQLite.

1567

**

1568

** INVARIANTS:

1569

**

1570

** {F17371} The [sqlite3_memory_used()] routine returns the

1571

** number of bytes of memory currently outstanding

1572

** (malloced but not freed).

1573

**

1574

** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum

1575

** value of [sqlite3_memory_used()]

1576

** since the highwater mark was last reset.

1577

**

1578

** {F17374} The values returned by [sqlite3_memory_used()] and

1579

** [sqlite3_memory_highwater()] include any overhead

1580

** added by SQLite in its implementation of [sqlite3_malloc()],

1581

** but not overhead added by the any underlying system library

1582

** routines that [sqlite3_malloc()] may call.

1583

**

1584

** {F17375} The memory highwater mark is reset to the current value of

1585

** [sqlite3_memory_used()] if and only if the parameter to

1586

** [sqlite3_memory_highwater()] is true. The value returned

1587

** by [sqlite3_memory_highwater(1)] is the highwater mark

1588

** prior to the reset.

1589

*/

1590

sqlite3_int64 sqlite3_memory_used(void);

1591

sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

1592

1593

/*

1594

** CAPI3REF: Pseudo-Random Number Generator {F17390}

1595

**

1596

** SQLite contains a high-quality pseudo-random number generator (PRNG) used to

1597

** select random ROWIDs when inserting new records into a table that

1598

** already uses the largest possible ROWID. The PRNG is also used for

1599

** the build-in random() and randomblob() SQL functions. This interface allows

1600

** appliations to access the same PRNG for other purposes.

1601

**

1602

** A call to this routine stores N bytes of randomness into buffer P.

1603

**

1604

** The first time this routine is invoked (either internally or by

1605

** the application) the PRNG is seeded using randomness obtained

1606

** from the xRandomness method of the default [sqlite3_vfs] object.

1607

** On all subsequent invocations, the pseudo-randomness is generated

1608

** internally and without recourse to the [sqlite3_vfs] xRandomness

1609

** method.

1610

**

1611

** INVARIANTS:

1612

**

1613

** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of

1614

** high-quality pseudo-randomness into buffer P.

1615

*/

1616

void sqlite3_randomness(int N, void *P);

1617

1618

/*

1619

** CAPI3REF: Compile-Time Authorization Callbacks {F12500}

1620

**

1621

** This routine registers a authorizer callback with a particular

1622

** [database connection], supplied in the first argument.

1623

** The authorizer callback is invoked as SQL statements are being compiled

1624

** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],

1625

** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various

1626

** points during the compilation process, as logic is being created

1627

** to perform various actions, the authorizer callback is invoked to

1628

** see if those actions are allowed. The authorizer callback should

1629

** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the

1630

** specific action but allow the SQL statement to continue to be

1631

** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be

1632

** rejected with an error. If the authorizer callback returns

1633

** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]

1634

** then [sqlite3_prepare_v2()] or equivalent call that triggered

1635

** the authorizer will fail with an error message.

1636

**

1637

** When the callback returns [SQLITE_OK], that means the operation

1638

** requested is ok. When the callback returns [SQLITE_DENY], the

1639

** [sqlite3_prepare_v2()] or equivalent call that triggered the

1640

** authorizer will fail with an error message explaining that

1641

** access is denied. If the authorizer code is [SQLITE_READ]

1642

** and the callback returns [SQLITE_IGNORE] then the

1643

** [prepared statement] statement is constructed to substitute

1644

** a NULL value in place of the table column that would have

1645

** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]

1646

** return can be used to deny an untrusted user access to individual

1647

** columns of a table.

1648

**

1649

** The first parameter to the authorizer callback is a copy of

1650

** the third parameter to the sqlite3_set_authorizer() interface.

1651

** The second parameter to the callback is an integer

1652

** [SQLITE_COPY | action code] that specifies the particular action

1653

** to be authorized. The third through sixth

1654

** parameters to the callback are zero-terminated strings that contain

1655

** additional details about the action to be authorized.

1656

**

1657

** An authorizer is used when [sqlite3_prepare | preparing]

1658

** SQL statements from an untrusted

1659

** source, to ensure that the SQL statements do not try to access data

1660

** that they are not allowed to see, or that they do not try to

1661

** execute malicious statements that damage the database. For

1662

** example, an application may allow a user to enter arbitrary

1663

** SQL queries for evaluation by a database. But the application does

1664

** not want the user to be able to make arbitrary changes to the

1665

** database. An authorizer could then be put in place while the

1666

** user-entered SQL is being [sqlite3_prepare | prepared] that

1667

** disallows everything except [SELECT] statements.

1668

**

1669

** Applications that need to process SQL from untrusted sources

1670

** might also consider lowering resource limits using [sqlite3_limit()]

1671

** and limiting database size using the [max_page_count] [PRAGMA]

1672

** in addition to using an authorizer.

1673

**

1674

** Only a single authorizer can be in place on a database connection

1675

** at a time. Each call to sqlite3_set_authorizer overrides the

1676

** previous call. Disable the authorizer by installing a NULL callback.

1677

** The authorizer is disabled by default.

1678

**

1679

** Note that the authorizer callback is invoked only during

1680

** [sqlite3_prepare()] or its variants. Authorization is not

1681

** performed during statement evaluation in [sqlite3_step()].

1682

**

1683

** INVARIANTS:

1684

**

1685

** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a

1686

** authorizer callback with database connection D.

1687

**

1688

** {F12502} The authorizer callback is invoked as SQL statements are

1689

** being compiled

1690

**

1691

** {F12503} If the authorizer callback returns any value other than

1692

** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then

1693

** the [sqlite3_prepare_v2()] or equivalent call that caused

1694

** the authorizer callback to run shall fail with an

1695

** [SQLITE_ERROR] error code and an appropriate error message.

1696

**

1697

** {F12504} When the authorizer callback returns [SQLITE_OK], the operation

1698

** described is coded normally.

1699

**

1700

** {F12505} When the authorizer callback returns [SQLITE_DENY], the

1701

** [sqlite3_prepare_v2()] or equivalent call that caused the

1702

** authorizer callback to run shall fail

1703

** with an [SQLITE_ERROR] error code and an error message

1704

** explaining that access is denied.

1705

**

1706

** {F12506} If the authorizer code (the 2nd parameter to the authorizer

1707

** callback) is [SQLITE_READ] and the authorizer callback returns

1708

** [SQLITE_IGNORE] then the prepared statement is constructed to

1709

** insert a NULL value in place of the table column that would have

1710

** been read if [SQLITE_OK] had been returned.

1711

**

1712

** {F12507} If the authorizer code (the 2nd parameter to the authorizer

1713

** callback) is anything other than [SQLITE_READ], then

1714

** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].

1715

**

1716

** {F12510} The first parameter to the authorizer callback is a copy of

1717

** the third parameter to the [sqlite3_set_authorizer()] interface.

1718

**

1719

** {F12511} The second parameter to the callback is an integer

1720

** [SQLITE_COPY | action code] that specifies the particular action

1721

** to be authorized.

1722

**

1723

** {F12512} The third through sixth parameters to the callback are

1724

** zero-terminated strings that contain

1725

** additional details about the action to be authorized.

1726

**

1727

** {F12520} Each call to [sqlite3_set_authorizer()] overrides the

1728

** any previously installed authorizer.

1729

**

1730

** {F12521} A NULL authorizer means that no authorization

1731

** callback is invoked.

1732

**

1733

** {F12522} The default authorizer is NULL.

1734

*/

1735

int sqlite3_set_authorizer(

1736

sqlite3*,

1737

int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),

1738

void *pUserData

1739

);

1740

1741

/*

1742

** CAPI3REF: Authorizer Return Codes {F12590}

1743

**

1744

** The [sqlite3_set_authorizer | authorizer callback function] must

1745

** return either [SQLITE_OK] or one of these two constants in order

1746

** to signal SQLite whether or not the action is permitted. See the

1747

** [sqlite3_set_authorizer | authorizer documentation] for additional

1748

** information.

1749

*/

1750

#define SQLITE_DENY 1 /* Abort the SQL statement with an error */

1751

#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */

1752

1753

/*

1754

** CAPI3REF: Authorizer Action Codes {F12550}

1755

**

1756

** The [sqlite3_set_authorizer()] interface registers a callback function

1757

** that is invoked to authorizer certain SQL statement actions. The

1758

** second parameter to the callback is an integer code that specifies

1759

** what action is being authorized. These are the integer action codes that

1760

** the authorizer callback may be passed.

1761

**

1762

** These action code values signify what kind of operation is to be

1763

** authorized. The 3rd and 4th parameters to the authorization

1764

** callback function will be parameters or NULL depending on which of these

1765

** codes is used as the second parameter. The 5th parameter to the

1766

** authorizer callback is the name of the database ("main", "temp",

1767

** etc.) if applicable. The 6th parameter to the authorizer callback

1768

** is the name of the inner-most trigger or view that is responsible for

1769

** the access attempt or NULL if this access attempt is directly from

1770

** top-level SQL code.

1771

**

1772

** INVARIANTS:

1773

**

1774

** {F12551} The second parameter to an

1775

** [sqlite3_set_authorizer | authorizer callback is always an integer

1776

** [SQLITE_COPY | authorizer code] that specifies what action

1777

** is being authorized.

1778

**

1779

** {F12552} The 3rd and 4th parameters to the

1780

** [sqlite3_set_authorizer | authorization callback function]

1781

** will be parameters or NULL depending on which

1782

** [SQLITE_COPY | authorizer code] is used as the second parameter.

1783

**

1784

** {F12553} The 5th parameter to the

1785

** [sqlite3_set_authorizer | authorizer callback] is the name

1786

** of the database (example: "main", "temp", etc.) if applicable.

1787

**

1788

** {F12554} The 6th parameter to the

1789

** [sqlite3_set_authorizer | authorizer callback] is the name

1790

** of the inner-most trigger or view that is responsible for

1791

** the access attempt or NULL if this access attempt is directly from

1792

** top-level SQL code.

1793

*/

1794

/******************************************* 3rd ************ 4th ***********/

1795

#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */

1796

#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */

1797

#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */

1798

#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */

1799

#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */

1800

#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */

1801

#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */

1802

#define SQLITE_CREATE_VIEW 8 /* View Name NULL */

1803

#define SQLITE_DELETE 9 /* Table Name NULL */

1804

#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */

1805

#define SQLITE_DROP_TABLE 11 /* Table Name NULL */

1806

#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */

1807

#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */

1808

#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */

1809

#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */

1810

#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */

1811

#define SQLITE_DROP_VIEW 17 /* View Name NULL */

1812

#define SQLITE_INSERT 18 /* Table Name NULL */

1813

#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */

1814

#define SQLITE_READ 20 /* Table Name Column Name */

1815

#define SQLITE_SELECT 21 /* NULL NULL */

1816

#define SQLITE_TRANSACTION 22 /* NULL NULL */

1817

#define SQLITE_UPDATE 23 /* Table Name Column Name */

1818

#define SQLITE_ATTACH 24 /* Filename NULL */

1819

#define SQLITE_DETACH 25 /* Database Name NULL */

1820

#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */

1821

#define SQLITE_REINDEX 27 /* Index Name NULL */

1822

#define SQLITE_ANALYZE 28 /* Table Name NULL */

1823

#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */

1824

#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */

1825

#define SQLITE_FUNCTION 31 /* Function Name NULL */

1826

#define SQLITE_COPY 0 /* No longer used */

1827

1828

/*

1829

** CAPI3REF: Tracing And Profiling Functions {F12280}

1830

**

1831

** These routines register callback functions that can be used for

1832

** tracing and profiling the execution of SQL statements.

1833

**

1834

** The callback function registered by sqlite3_trace() is invoked at

1835

** various times when an SQL statement is being run by [sqlite3_step()].

1836

** The callback returns a UTF-8 rendering of the SQL statement text

1837

** as the statement first begins executing. Additional callbacks occur

1838

** as each triggersubprogram is entered. The callbacks for triggers

1839

** contain a UTF-8 SQL comment that identifies the trigger.

1840

**

1841

** The callback function registered by sqlite3_profile() is invoked

1842

** as each SQL statement finishes. The profile callback contains

1843

** the original statement text and an estimate of wall-clock time

1844

** of how long that statement took to run.

1845

**

1846

** The sqlite3_profile() API is currently considered experimental and

1847

** is subject to change or removal in a future release.

1848

**

1849

** The trigger reporting feature of the trace callback is considered

1850

** experimental and is subject to change or removal in future releases.

1851

** Future versions of SQLite might also add new trace callback

1852

** invocations.

1853

**

1854

** INVARIANTS:

1855

**

1856

** {F12281} The callback function registered by [sqlite3_trace()] is

1857

** whenever an SQL statement first begins to execute and

1858

** whenever a trigger subprogram first begins to run.

1859

**

1860

** {F12282} Each call to [sqlite3_trace()] overrides the previously

1861

** registered trace callback.

1862

**

1863

** {F12283} A NULL trace callback disables tracing.

1864

**

1865

** {F12284} The first argument to the trace callback is a copy of

1866

** the pointer which was the 3rd argument to [sqlite3_trace()].

1867

**

1868

** {F12285} The second argument to the trace callback is a

1869

** zero-terminated UTF8 string containing the original text

1870

** of the SQL statement as it was passed into [sqlite3_prepare_v2()]

1871

** or the equivalent, or an SQL comment indicating the beginning

1872

** of a trigger subprogram.

1873

**

1874

** {F12287} The callback function registered by [sqlite3_profile()] is invoked

1875

** as each SQL statement finishes.

1876

**

1877

** {F12288} The first parameter to the profile callback is a copy of

1878

** the 3rd parameter to [sqlite3_profile()].

1879

**

1880

** {F12289} The second parameter to the profile callback is a

1881

** zero-terminated UTF-8 string that contains the complete text of

1882

** the SQL statement as it was processed by [sqlite3_prepare_v2()]

1883

** or the equivalent.

1884

**

1885

** {F12290} The third parameter to the profile callback is an estimate

1886

** of the number of nanoseconds of wall-clock time required to

1887

** run the SQL statement from start to finish.

1888

*/

1889

void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);

1890

void *sqlite3_profile(sqlite3*,

1891

void(*xProfile)(void*,const char*,sqlite3_uint64), void*);

1892

1893

/*

1894

** CAPI3REF: Query Progress Callbacks {F12910}

1895

**

1896

** This routine configures a callback function - the

1897

** progress callback - that is invoked periodically during long

1898

** running calls to [sqlite3_exec()], [sqlite3_step()] and

1899

** [sqlite3_get_table()]. An example use for this

1900

** interface is to keep a GUI updated during a large query.

1901

**

1902

** If the progress callback returns non-zero, the opertion is

1903

** interrupted. This feature can be used to implement a

1904

** "Cancel" button on a GUI dialog box.

1905

**

1906

** INVARIANTS:

1907

**

1908

** {F12911} The callback function registered by [sqlite3_progress_handler()]

1909

** is invoked periodically during long running calls to

1910

** [sqlite3_step()].

1911

**

1912

** {F12912} The progress callback is invoked once for every N virtual

1913

** machine opcodes, where N is the second argument to

1914

** the [sqlite3_progress_handler()] call that registered

1915

** the callback. <todo>What if N is less than 1?</todo>

1916

**

1917

** {F12913} The progress callback itself is identified by the third

1918

** argument to [sqlite3_progress_handler()].

1919

**

1920

** {F12914} The fourth argument [sqlite3_progress_handler()] is a

1921

*** void pointer passed to the progress callback

1922

** function each time it is invoked.

1923

**

1924

** {F12915} If a call to [sqlite3_step()] results in fewer than

1925

** N opcodes being executed,

1926

** then the progress callback is never invoked. {END}

1927

**

1928

** {F12916} Every call to [sqlite3_progress_handler()]

1929

** overwrites any previously registere progress handler.

1930

**

1931

** {F12917} If the progress handler callback is NULL then no progress

1932

** handler is invoked.

1933

**

1934

** {F12918} If the progress callback returns a result other than 0, then

1935

** the behavior is a if [sqlite3_interrupt()] had been called.

1936

*/

1937

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

1938

1939

/*

1940

** CAPI3REF: Opening A New Database Connection {F12700}

1941

**

1942

** These routines open an SQLite database file whose name

1943

** is given by the filename argument.

1944

** The filename argument is interpreted as UTF-8

1945

** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16

1946

** in the native byte order for [sqlite3_open16()].

1947

** An [sqlite3*] handle is usually returned in *ppDb, even

1948

** if an error occurs. The only exception is if SQLite is unable

1949

** to allocate memory to hold the [sqlite3] object, a NULL will

1950

** be written into *ppDb instead of a pointer to the [sqlite3] object.

1951

** If the database is opened (and/or created)

1952

** successfully, then [SQLITE_OK] is returned. Otherwise an

1953

** error code is returned. The

1954

** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain

1955

** an English language description of the error.

1956

**

1957

** The default encoding for the database will be UTF-8 if

1958

** [sqlite3_open()] or [sqlite3_open_v2()] is called and

1959

** UTF-16 in the native byte order if [sqlite3_open16()] is used.

1960

**

1961

** Whether or not an error occurs when it is opened, resources

1962

** associated with the [sqlite3*] handle should be released by passing it

1963

** to [sqlite3_close()] when it is no longer required.

1964

**

1965

** The [sqlite3_open_v2()] interface works like [sqlite3_open()]

1966

** except that it acccepts two additional parameters for additional control

1967

** over the new database connection. The flags parameter can be

1968

** one of:

1969

**

1970

** <ol>

1971

** <li> [SQLITE_OPEN_READONLY]

1972

** <li> [SQLITE_OPEN_READWRITE]

1973

** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]

1974

** </ol>

1975

**

1976

** The first value opens the database read-only.

1977

** If the database does not previously exist, an error is returned.

1978

** The second option opens

1979

** the database for reading and writing if possible, or reading only if

1980

** if the file is write protected. In either case the database

1981

** must already exist or an error is returned. The third option

1982

** opens the database for reading and writing and creates it if it does

1983

** not already exist.

1984

** The third options is behavior that is always used for [sqlite3_open()]

1985

** and [sqlite3_open16()].

1986

**

1987

** If the 3rd parameter to [sqlite3_open_v2()] is not one of the

1988

** combinations shown above then the behavior is undefined.

1989

**

1990

** If the filename is ":memory:", then an private

1991

** in-memory database is created for the connection. This in-memory

1992

** database will vanish when the database connection is closed. Future

1993

** version of SQLite might make use of additional special filenames

1994

** that begin with the ":" character. It is recommended that

1995

** when a database filename really does begin with

1996

** ":" that you prefix the filename with a pathname like "./" to

1997

** avoid ambiguity.

1998

**

1999

** If the filename is an empty string, then a private temporary

2000

** on-disk database will be created. This private database will be

2001

** automatically deleted as soon as the database connection is closed.

2002

**

2003

** The fourth parameter to sqlite3_open_v2() is the name of the

2004

** [sqlite3_vfs] object that defines the operating system

2005

** interface that the new database connection should use. If the

2006

** fourth parameter is a NULL pointer then the default [sqlite3_vfs]

2007

** object is used.

2008

**

2009

** Note to windows users: The encoding used for the filename argument

2010

** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever

2011

** codepage is currently defined. Filenames containing international

2012

** characters must be converted to UTF-8 prior to passing them into

2013

** [sqlite3_open()] or [sqlite3_open_v2()].

2014

**

2015

** INVARIANTS:

2016

**

2017

** {F12701} The [sqlite3_open()], [sqlite3_open16()], and

2018

** [sqlite3_open_v2()] interfaces create a new

2019

** [database connection] associated with

2020

** the database file given in their first parameter.

2021

**

2022

** {F12702} The filename argument is interpreted as UTF-8

2023

** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16

2024

** in the native byte order for [sqlite3_open16()].

2025

**

2026

** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],

2027

** or [sqlite3_open_v2()] writes a pointer to a new

2028

** [database connection] into *ppDb.

2029

**

2030

** {F12704} The [sqlite3_open()], [sqlite3_open16()], and

2031

** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,

2032

** or an appropriate [error code] on failure.

2033

**

2034

** {F12706} The default text encoding for a new database created using

2035

** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.

2036

**

2037

** {F12707} The default text encoding for a new database created using

2038

** [sqlite3_open16()] will be UTF-16.

2039

**

2040

** {F12709} The [sqlite3_open(F,D)] interface is equivalent to

2041

** [sqlite3_open_v2(F,D,G,0)] where the G parameter is

2042

** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].

2043

**

2044

** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the

2045

** bit value [SQLITE_OPEN_READONLY] then the database is opened

2046

** for reading only.

2047

**

2048

** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the

2049

** bit value [SQLITE_OPEN_READWRITE] then the database is opened

2050

** reading and writing if possible, or for reading only if the

2051

** file is write protected by the operating system.

2052

**

2053

** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the

2054

** bit value [SQLITE_OPEN_CREATE] and the database does not

2055

** previously exist, an error is returned.

2056

**

2057

** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the

2058

** bit value [SQLITE_OPEN_CREATE] and the database does not

2059

** previously exist, then an attempt is made to create and

2060

** initialize the database.

2061

**

2062

** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],

2063

** or [sqlite3_open_v2()] is ":memory:", then an private,

2064

** ephemeral, in-memory database is created for the connection.

2065

** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required

2066

** in sqlite3_open_v2()?</todo>

2067

**

2068

** {F12719} If the filename is NULL or an empty string, then a private,

2069

** ephermeral on-disk database will be created.

2070

** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required

2071

** in sqlite3_open_v2()?</todo>

2072

**

2073

** {F12721} The [database connection] created by

2074

** [sqlite3_open_v2(F,D,G,V)] will use the

2075

** [sqlite3_vfs] object identified by the V parameter, or

2076

** the default [sqlite3_vfs] object is V is a NULL pointer.

2077

*/

2078

int sqlite3_open(

2079

const char *filename, /* Database filename (UTF-8) */

2080

sqlite3 **ppDb /* OUT: SQLite db handle */

2081

);

2082

int sqlite3_open16(

2083

const void *filename, /* Database filename (UTF-16) */

2084

sqlite3 **ppDb /* OUT: SQLite db handle */

2085

);

2086

int sqlite3_open_v2(

2087

const char *filename, /* Database filename (UTF-8) */

2088

sqlite3 **ppDb, /* OUT: SQLite db handle */

2089

int flags, /* Flags */

2090

const char *zVfs /* Name of VFS module to use */

2091

);

2092

2093

/*

2094

** CAPI3REF: Error Codes And Messages {F12800}

2095

**

2096

** The sqlite3_errcode() interface returns the numeric

2097

** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]

2098

** for the most recent failed sqlite3_* API call associated

2099

** with [sqlite3] handle 'db'. If a prior API call failed but the

2100

** most recent API call succeeded, the return value from sqlite3_errcode()

2101

** is undefined.

2102

**

2103

** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language

2104

** text that describes the error, as either UTF8 or UTF16 respectively.

2105

** Memory to hold the error message string is managed internally.

2106

** The application does not need to worry with freeing the result.

2107

** However, the error string might be overwritten or deallocated by

2108

** subsequent calls to other SQLite interface functions.

2109

**

2110

** INVARIANTS:

2111

**

2112

** {F12801} The [sqlite3_errcode(D)] interface returns the numeric

2113

** [SQLITE_OK | result code] or

2114

** [SQLITE_IOERR_READ | extended result code]

2115

** for the most recently failed interface call associated

2116

** with [database connection] D.

2117

**

2118

** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]

2119

** interfaces return English-language text that describes

2120

** the error in the mostly recently failed interface call,

2121

** encoded as either UTF8 or UTF16 respectively.

2122

**

2123

** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]

2124

** are valid until the next SQLite interface call.

2125

**

2126

** {F12808} Calls to API routines that do not return an error code

2127

** (example: [sqlite3_data_count()]) do not

2128

** change the error code or message returned by

2129

** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].

2130

**

2131

** {F12809} Interfaces that are not associated with a specific

2132

** [database connection] (examples:

2133

** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]

2134

** do not change the values returned by

2135

** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].

2136

*/

2137

int sqlite3_errcode(sqlite3 *db);

2138

const char *sqlite3_errmsg(sqlite3*);

2139

const void *sqlite3_errmsg16(sqlite3*);

2140

2141

/*

2142

** CAPI3REF: SQL Statement Object {F13000}

2143

** KEYWORDS: {prepared statement} {prepared statements}

2144

**

2145

** An instance of this object represent single SQL statements. This

2146

** object is variously known as a "prepared statement" or a

2147

** "compiled SQL statement" or simply as a "statement".

2148

**

2149

** The life of a statement object goes something like this:

2150

**

2151

** <ol>

2152

** <li> Create the object using [sqlite3_prepare_v2()] or a related

2153

** function.

2154

** <li> Bind values to host parameters using

2155

** [sqlite3_bind_blob | sqlite3_bind_* interfaces].

2156

** <li> Run the SQL by calling [sqlite3_step()] one or more times.

2157

** <li> Reset the statement using [sqlite3_reset()] then go back

2158

** to step 2. Do this zero or more times.

2159

** <li> Destroy the object using [sqlite3_finalize()].

2160

** </ol>

2161

**

2162

** Refer to documentation on individual methods above for additional

2163

** information.

2164

*/

2165

typedef struct sqlite3_stmt sqlite3_stmt;

2166

2167

/*

2168

** CAPI3REF: Run-time Limits {F12760}

2169

**

2170

** This interface allows the size of various constructs to be limited

2171

** on a connection by connection basis. The first parameter is the

2172

** [database connection] whose limit is to be set or queried. The

2173

** second parameter is one of the [limit categories] that define a

2174

** class of constructs to be size limited. The third parameter is the

2175

** new limit for that construct. The function returns the old limit.

2176

**

2177

** If the new limit is a negative number, the limit is unchanged.

2178

** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper

2179

** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ.

2180

** (The "_LIMIT_" in the name is changed to "_MAX_".)

2181

** Attempts to increase a limit above its hard upper bound are

2182

** silently truncated to the hard upper limit.

2183

**

2184

** Run time limits are intended for use in applications that manage

2185

** both their own internal database and also databases that are controlled

2186

** by untrusted external sources. An example application might be a

2187

** webbrowser that has its own databases for storing history and

2188

** separate databases controlled by javascript applications downloaded

2189

** off the internet. The internal databases can be given the

2190

** large, default limits. Databases managed by external sources can

2191

** be given much smaller limits designed to prevent a denial of service

2192

** attach. Developers might also want to use the [sqlite3_set_authorizer()]

2193

** interface to further control untrusted SQL. The size of the database

2194

** created by an untrusted script can be contained using the

2195

** [max_page_count] [PRAGMA].

2196

**

2197

** This interface is currently considered experimental and is subject

2198

** to change or removal without prior notice.

2199

**

2200

** INVARIANTS:

2201

**

2202

** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is

2203

** positive changes the

2204

** limit on the size of construct C in [database connection] D

2205

** to the lessor of V and the hard upper bound on the size

2206

** of C that is set at compile-time.

2207

**

2208

** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative

2209

** leaves the state of [database connection] D unchanged.

2210

**

2211

** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the

2212

** value of the limit on the size of construct C in

2213

** in [database connection] D as it was prior to the call.

2214

*/

2215

int sqlite3_limit(sqlite3*, int id, int newVal);

2216

2217

/*

2218

** CAPI3REF: Run-Time Limit Categories {F12790}

2219

** KEYWORDS: {limit category} {limit categories}

2220

**

2221

** These constants define various aspects of a [database connection]

2222

** that can be limited in size by calls to [sqlite3_limit()].

2223

** The meanings of the various limits are as follows:

2224

**

2225

** <dl>

2226

** <dt>SQLITE_LIMIT_LENGTH</dt>

2227

** <dd>The maximum size of any

2228

** string or blob or table row.<dd>

2229

**

2230

** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>

2231

** <dd>The maximum length of an SQL statement.</dd>

2232

**

2233

** <dt>SQLITE_LIMIT_COLUMN</dt>

2234

** <dd>The maximum number of columns in a table definition or in the

2235

** result set of a SELECT or the maximum number of columns in an index

2236

** or in an ORDER BY or GROUP BY clause.</dd>

2237

**

2238

** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>

2239

** <dd>The maximum depth of the parse tree on any expression.</dd>

2240

**

2241

** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>

2242

** <dd>The maximum number of terms in a compound SELECT statement.</dd>

2243

**

2244

** <dt>SQLITE_LIMIT_VDBE_OP</dt>

2245

** <dd>The maximum number of instructions in a virtual machine program

2246

** used to implement an SQL statement.</dd>

2247

**

2248

** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>

2249

** <dd>The maximum number of arguments on a function.</dd>

2250

**

2251

** <dt>SQLITE_LIMIT_ATTACHED</dt>

2252

** <dd>The maximum number of attached databases.</dd>

2253

**

2254

** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>

2255

** <dd>The maximum length of the pattern argument to the LIKE or

2256

** GLOB operators.</dd>

2257

**

2258

** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>

2259

** <dd>The maximum number of variables in an SQL statement that can

2260

** be bound.</dd>

2261

** </dl>

2262

*/

2263

#define SQLITE_LIMIT_LENGTH 0

2264

#define SQLITE_LIMIT_SQL_LENGTH 1

2265

#define SQLITE_LIMIT_COLUMN 2

2266

#define SQLITE_LIMIT_EXPR_DEPTH 3

2267

#define SQLITE_LIMIT_COMPOUND_SELECT 4

2268

#define SQLITE_LIMIT_VDBE_OP 5

2269

#define SQLITE_LIMIT_FUNCTION_ARG 6

2270

#define SQLITE_LIMIT_ATTACHED 7

2271

#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8

2272

#define SQLITE_LIMIT_VARIABLE_NUMBER 9

2273

2274

/*

2275

** CAPI3REF: Compiling An SQL Statement {F13010}

2276

**

2277

** To execute an SQL query, it must first be compiled into a byte-code

2278

** program using one of these routines.

2279

**

2280

** The first argument "db" is an [database connection]

2281

** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]

2282

** or [sqlite3_open16()].

2283

** The second argument "zSql" is the statement to be compiled, encoded

2284

** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()

2285

** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()

2286

** use UTF-16. {END}

2287

**

2288

** If the nByte argument is less

2289

** than zero, then zSql is read up to the first zero terminator.

2290

** If nByte is non-negative, then it is the maximum number of

2291

** bytes read from zSql. When nByte is non-negative, the

2292

** zSql string ends at either the first '\000' or '\u0000' character or

2293

** the nByte-th byte, whichever comes first. If the caller knows

2294

** that the supplied string is nul-terminated, then there is a small

2295

** performance advantage to be had by passing an nByte parameter that

2296

** is equal to the number of bytes in the input string including

2297

** the nul-terminator bytes.{END}

2298

**

2299

** *pzTail is made to point to the first byte past the end of the

2300

** first SQL statement in zSql. These routines only compiles the first

2301

** statement in zSql, so *pzTail is left pointing to what remains

2302

** uncompiled.

2303

**

2304

** *ppStmt is left pointing to a compiled [prepared statement] that can be

2305

** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is

2306

** set to NULL. If the input text contains no SQL (if the input

2307

** is and empty string or a comment) then *ppStmt is set to NULL.

2308

** {U13018} The calling procedure is responsible for deleting the

2309

** compiled SQL statement

2310

** using [sqlite3_finalize()] after it has finished with it.

2311

**

2312

** On success, [SQLITE_OK] is returned. Otherwise an

2313

** [error code] is returned.

2314

**

2315

** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are

2316

** recommended for all new programs. The two older interfaces are retained

2317

** for backwards compatibility, but their use is discouraged.

2318

** In the "v2" interfaces, the prepared statement

2319

** that is returned (the [sqlite3_stmt] object) contains a copy of the

2320

** original SQL text. {END} This causes the [sqlite3_step()] interface to

2321

** behave a differently in two ways:

2322

**

2323

** <ol>

2324

** <li>

2325

** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it

2326

** always used to do, [sqlite3_step()] will automatically recompile the SQL

2327

** statement and try to run it again. If the schema has changed in

2328

** a way that makes the statement no longer valid, [sqlite3_step()] will still

2329

** return [SQLITE_SCHEMA]. But unlike the legacy behavior,

2330

** [SQLITE_SCHEMA] is now a fatal error. Calling

2331

** [sqlite3_prepare_v2()] again will not make the

2332

** error go away. Note: use [sqlite3_errmsg()] to find the text

2333

** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}

2334

** </li>

2335

**

2336

** <li>

2337

** When an error occurs,

2338

** [sqlite3_step()] will return one of the detailed

2339

** [error codes] or [extended error codes].

2340

** The legacy behavior was that [sqlite3_step()] would only return a generic

2341

** [SQLITE_ERROR] result code and you would have to make a second call to

2342

** [sqlite3_reset()] in order to find the underlying cause of the problem.

2343

** With the "v2" prepare interfaces, the underlying reason for the error is

2344

** returned immediately.

2345

** </li>

2346

** </ol>

2347

**

2348

** INVARIANTS:

2349

**

2350

** {F13011} The [sqlite3_prepare(db,zSql,...)] and

2351

** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the

2352

** text in their zSql parameter as UTF-8.

2353

**

2354

** {F13012} The [sqlite3_prepare16(db,zSql,...)] and

2355

** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the

2356

** text in their zSql parameter as UTF-16 in the native byte order.

2357

**

2358

** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]

2359

** and its variants is less than zero, then SQL text is

2360

** read from zSql is read up to the first zero terminator.

2361

**

2362

** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]

2363

** and its variants is non-negative, then at most nBytes bytes

2364

** SQL text is read from zSql.

2365

**

2366

** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants

2367

** if the zSql input text contains more than one SQL statement

2368

** and pzTail is not NULL, then *pzTail is made to point to the

2369

** first byte past the end of the first SQL statement in zSql.

2370

** <todo>What does *pzTail point to if there is one statement?</todo>

2371

**

2372

** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]

2373

** or one of its variants writes into *ppStmt a pointer to a new

2374

** [prepared statement] or a pointer to NULL

2375

** if zSql contains nothing other than whitespace or comments.

2376

**

2377

** {F13019} The [sqlite3_prepare_v2()] interface and its variants return

2378

** [SQLITE_OK] or an appropriate [error code] upon failure.

2379

**

2380

** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its

2381

** variants returns an error (any value other than [SQLITE_OK])

2382

** it first sets *ppStmt to NULL.

2383

*/

2384

int sqlite3_prepare(

2385

sqlite3 *db, /* Database handle */

2386

const char *zSql, /* SQL statement, UTF-8 encoded */

2387

int nByte, /* Maximum length of zSql in bytes. */

2388

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

2389

const char **pzTail /* OUT: Pointer to unused portion of zSql */

2390

);

2391

int sqlite3_prepare_v2(

2392

sqlite3 *db, /* Database handle */

2393

const char *zSql, /* SQL statement, UTF-8 encoded */

2394

int nByte, /* Maximum length of zSql in bytes. */

2395

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

2396

const char **pzTail /* OUT: Pointer to unused portion of zSql */

2397

);

2398

int sqlite3_prepare16(

2399

sqlite3 *db, /* Database handle */

2400

const void *zSql, /* SQL statement, UTF-16 encoded */

2401

int nByte, /* Maximum length of zSql in bytes. */

2402

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

2403

const void **pzTail /* OUT: Pointer to unused portion of zSql */

2404

);

2405

int sqlite3_prepare16_v2(

2406

sqlite3 *db, /* Database handle */

2407

const void *zSql, /* SQL statement, UTF-16 encoded */

2408

int nByte, /* Maximum length of zSql in bytes. */

2409

sqlite3_stmt **ppStmt, /* OUT: Statement handle */

2410

const void **pzTail /* OUT: Pointer to unused portion of zSql */

2411

);

2412

2413

/*

2414

** CAPIREF: Retrieving Statement SQL {F13100}

2415

**

2416

** This intereface can be used to retrieve a saved copy of the original

2417

** SQL text used to create a [prepared statement].

2418

**

2419

** INVARIANTS:

2420

**

2421

** {F13101} If the [prepared statement] passed as

2422

** the an argument to [sqlite3_sql()] was compiled

2423

** compiled using either [sqlite3_prepare_v2()] or

2424

** [sqlite3_prepare16_v2()],

2425

** then [sqlite3_sql()] function returns a pointer to a

2426

** zero-terminated string containing a UTF-8 rendering

2427

** of the original SQL statement.

2428

**

2429

** {F13102} If the [prepared statement] passed as

2430

** the an argument to [sqlite3_sql()] was compiled

2431

** compiled using either [sqlite3_prepare()] or

2432

** [sqlite3_prepare16()],

2433

** then [sqlite3_sql()] function returns a NULL pointer.

2434

**

2435

** {F13103} The string returned by [sqlite3_sql(S)] is valid until the

2436

** [prepared statement] S is deleted using [sqlite3_finalize(S)].

2437

*/

2438

const char *sqlite3_sql(sqlite3_stmt *pStmt);

2439

2440

/*

2441

** CAPI3REF: Dynamically Typed Value Object {F15000}

2442

** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}

2443

**

2444

** SQLite uses the sqlite3_value object to represent all values

2445

** that can be stored in a database table.

2446

** SQLite uses dynamic typing for the values it stores.

2447

** Values stored in sqlite3_value objects can be

2448

** be integers, floating point values, strings, BLOBs, or NULL.

2449

**

2450

** An sqlite3_value object may be either "protected" or "unprotected".

2451

** Some interfaces require a protected sqlite3_value. Other interfaces

2452

** will accept either a protected or an unprotected sqlite3_value.

2453

** Every interface that accepts sqlite3_value arguments specifies

2454

** whether or not it requires a protected sqlite3_value.

2455

**

2456

** The terms "protected" and "unprotected" refer to whether or not

2457

** a mutex is held. A internal mutex is held for a protected

2458

** sqlite3_value object but no mutex is held for an unprotected

2459

** sqlite3_value object. If SQLite is compiled to be single-threaded

2460

** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0)

2461

** then there is no distinction between

2462

** protected and unprotected sqlite3_value objects and they can be

2463

** used interchangable. However, for maximum code portability it

2464

** is recommended that applications make the distinction between

2465

** between protected and unprotected sqlite3_value objects even if

2466

** they are single threaded.

2467

**

2468

** The sqlite3_value objects that are passed as parameters into the

2469

** implementation of application-defined SQL functions are protected.

2470

** The sqlite3_value object returned by

2471

** [sqlite3_column_value()] is unprotected.

2472

** Unprotected sqlite3_value objects may only be used with

2473

** [sqlite3_result_value()] and [sqlite3_bind_value()]. All other

2474

** interfaces that use sqlite3_value require protected sqlite3_value objects.

2475

*/

2476

typedef struct Mem sqlite3_value;

2477

2478

/*

2479

** CAPI3REF: SQL Function Context Object {F16001}

2480

**

2481

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

2482

** sqlite3_context object. A pointer to an sqlite3_context

2483

** object is always first parameter to application-defined SQL functions.

2484

*/

2485

typedef struct sqlite3_context sqlite3_context;

2486

2487

/*

2488

** CAPI3REF: Binding Values To Prepared Statements {F13500}

2489

**

2490

** In the SQL strings input to [sqlite3_prepare_v2()] and its

2491

** variants, literals may be replace by a parameter in one

2492

** of these forms:

2493

**

2494

** <ul>

2495

** <li> ?

2496

** <li> ?NNN

2497

** <li> :VVV

2498

** <li> @VVV

2499

** <li> $VVV

2500

** </ul>

2501

**

2502

** In the parameter forms shown above NNN is an integer literal,

2503

** VVV alpha-numeric parameter name.

2504

** The values of these parameters (also called "host parameter names"

2505

** or "SQL parameters")

2506

** can be set using the sqlite3_bind_*() routines defined here.

2507

**

2508

** The first argument to the sqlite3_bind_*() routines always

2509

** is a pointer to the [sqlite3_stmt] object returned from

2510

** [sqlite3_prepare_v2()] or its variants. The second

2511

** argument is the index of the parameter to be set. The

2512

** first parameter has an index of 1. When the same named

2513

** parameter is used more than once, second and subsequent

2514

** occurrences have the same index as the first occurrence.

2515

** The index for named parameters can be looked up using the

2516

** [sqlite3_bind_parameter_name()] API if desired. The index

2517

** for "?NNN" parameters is the value of NNN.

2518

** The NNN value must be between 1 and the compile-time

2519

** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).

2520

**

2521

** The third argument is the value to bind to the parameter.

2522

**

2523

** In those

2524

** routines that have a fourth argument, its value is the number of bytes

2525

** in the parameter. To be clear: the value is the number of bytes

2526

** in the value, not the number of characters.

2527

** If the fourth parameter is negative, the length of the string is

2528

** number of bytes up to the first zero terminator.

2529

**

2530

** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and

2531

** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or

2532

** string after SQLite has finished with it. If the fifth argument is

2533

** the special value [SQLITE_STATIC], then SQLite assumes that the

2534

** information is in static, unmanaged space and does not need to be freed.

2535

** If the fifth argument has the value [SQLITE_TRANSIENT], then

2536

** SQLite makes its own private copy of the data immediately, before

2537

** the sqlite3_bind_*() routine returns.

2538

**

2539

** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that

2540

** is filled with zeros. A zeroblob uses a fixed amount of memory

2541

** (just an integer to hold it size) while it is being processed.

2542

** Zeroblobs are intended to serve as place-holders for BLOBs whose

2543

** content is later written using

2544

** [sqlite3_blob_open | increment BLOB I/O] routines. A negative

2545

** value for the zeroblob results in a zero-length BLOB.

2546

**

2547

** The sqlite3_bind_*() routines must be called after

2548

** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and

2549

** before [sqlite3_step()].

2550

** Bindings are not cleared by the [sqlite3_reset()] routine.

2551

** Unbound parameters are interpreted as NULL.

2552

**

2553

** These routines return [SQLITE_OK] on success or an error code if

2554

** anything goes wrong. [SQLITE_RANGE] is returned if the parameter

2555

** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.

2556

** [SQLITE_MISUSE] might be returned if these routines are called on a

2557

** virtual machine that is the wrong state or which has already been finalized.

2558

** Detection of misuse is unreliable. Applications should not depend

2559

** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a

2560

** a logic error in the application. Future versions of SQLite might

2561

** panic rather than return SQLITE_MISUSE.

2562

**

2563

** See also: [sqlite3_bind_parameter_count()],

2564

** [sqlite3_bind_parameter_name()], and

2565

** [sqlite3_bind_parameter_index()].

2566

**

2567

** INVARIANTS:

2568

**

2569

** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes

2570

** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"

2571

** as SQL parameters, where NNN is any sequence of one or more

2572

** digits and where VVV is any sequence of one or more

2573

** alphanumeric characters or "::" optionally followed by

2574

** a string containing no spaces and contained within parentheses.

2575

**

2576

** {F13509} The initial value of an SQL parameter is NULL.

2577

**

2578

** {F13512} The index of an "?" SQL parameter is one larger than the

2579

** largest index of SQL parameter to the left, or 1 if

2580

** the "?" is the leftmost SQL parameter.

2581

**

2582

** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.

2583

**

2584

** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is

2585

** the same as the index of leftmost occurances of the same

2586

** parameter, or one more than the largest index over all

2587

** parameters to the left if this is the first occurrance

2588

** of this parameter, or 1 if this is the leftmost parameter.

2589

**

2590

** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with

2591

** an [SQLITE_RANGE] error if the index of an SQL parameter

2592

** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.

2593

**

2594

** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]

2595

** associate the value V with all SQL parameters having an

2596

** index of N in the [prepared statement] S.

2597

**

2598

** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]

2599

** override prior calls with the same values of S and N.

2600

**

2601

** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]

2602

** persist across calls to [sqlite3_reset(S)].

2603

**

2604

** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],

2605

** [sqlite3_bind_text(S,N,V,L,D)], or

2606

** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L

2607

** bytes of the blob or string pointed to by V, when L

2608

** is non-negative.

2609

**

2610

** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or

2611

** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters

2612

** from V through the first zero character when L is negative.

2613

**

2614

** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],

2615

** [sqlite3_bind_text(S,N,V,L,D)], or

2616

** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special

2617

** constant [SQLITE_STATIC], SQLite assumes that the value V

2618

** is held in static unmanaged space that will not change

2619

** during the lifetime of the binding.

2620

**

2621

** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],

2622

** [sqlite3_bind_text(S,N,V,L,D)], or

2623

** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special

2624

** constant [SQLITE_TRANSIENT], the routine makes a

2625

** private copy of V value before it returns.

2626

**

2627

** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],

2628

** [sqlite3_bind_text(S,N,V,L,D)], or

2629

** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to

2630

** a function, SQLite invokes that function to destroy the

2631

** V value after it has finished using the V value.

2632

**

2633

** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound

2634

** is a blob of L bytes, or a zero-length blob if L is negative.

2635

**

2636

** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may

2637

** be either a [protected sqlite3_value] object or an

2638

** [unprotected sqlite3_value] object.

2639

*/

2640

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));

2641

int sqlite3_bind_double(sqlite3_stmt*, int, double);

2642

int sqlite3_bind_int(sqlite3_stmt*, int, int);

2643

int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);

2644

int sqlite3_bind_null(sqlite3_stmt*, int);

2645

int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));

2646

int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));

2647

int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);

2648

int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

2649

2650

/*

2651

** CAPI3REF: Number Of SQL Parameters {F13600}

2652

**

2653

** This routine can be used to find the number of SQL parameters

2654

** in a prepared statement. SQL parameters are tokens of the

2655

** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as

2656

** place-holders for values that are [sqlite3_bind_blob | bound]

2657

** to the parameters at a later time.

2658

**

2659

** This routine actually returns the index of the largest parameter.

2660

** For all forms except ?NNN, this will correspond to the number of

2661

** unique parameters. If parameters of the ?NNN are used, there may

2662

** be gaps in the list.

2663

**

2664

** See also: [sqlite3_bind_blob|sqlite3_bind()],

2665

** [sqlite3_bind_parameter_name()], and

2666

** [sqlite3_bind_parameter_index()].

2667

**

2668

** INVARIANTS:

2669

**

2670

** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns

2671

** the largest index of all SQL parameters in the

2672

** [prepared statement] S, or 0 if S

2673

** contains no SQL parameters.

2674

*/

2675

int sqlite3_bind_parameter_count(sqlite3_stmt*);

2676

2677

/*

2678

** CAPI3REF: Name Of A Host Parameter {F13620}

2679

**

2680

** This routine returns a pointer to the name of the n-th

2681

** SQL parameter in a [prepared statement].

2682

** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"

2683

** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"

2684

** respectively.

2685

** In other words, the initial ":" or "$" or "@" or "?"

2686

** is included as part of the name.

2687

** Parameters of the form "?" without a following integer have no name.

2688

**

2689

** The first host parameter has an index of 1, not 0.

2690

**

2691

** If the value n is out of range or if the n-th parameter is

2692

** nameless, then NULL is returned. The returned string is

2693

** always in the UTF-8 encoding even if the named parameter was

2694

** originally specified as UTF-16 in [sqlite3_prepare16()] or

2695

** [sqlite3_prepare16_v2()].

2696

**

2697

** See also: [sqlite3_bind_blob|sqlite3_bind()],

2698

** [sqlite3_bind_parameter_count()], and

2699

** [sqlite3_bind_parameter_index()].

2700

**

2701

** INVARIANTS:

2702

**

2703

** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns

2704

** a UTF-8 rendering of the name of the SQL parameter in

2705

** [prepared statement] S having index N, or

2706

** NULL if there is no SQL parameter with index N or if the

2707

** parameter with index N is an anonymous parameter "?".

2708

*/

2709

const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

2710

2711

/*

2712

** CAPI3REF: Index Of A Parameter With A Given Name {F13640}

2713

**

2714

** Return the index of an SQL parameter given its name. The

2715

** index value returned is suitable for use as the second

2716

** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero

2717

** is returned if no matching parameter is found. The parameter

2718

** name must be given in UTF-8 even if the original statement

2719

** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].

2720

**

2721

** See also: [sqlite3_bind_blob|sqlite3_bind()],

2722

** [sqlite3_bind_parameter_count()], and

2723

** [sqlite3_bind_parameter_index()].

2724

**

2725

** INVARIANTS:

2726

**

2727

** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns

2728

** the index of SQL parameter in [prepared statement]

2729

** S whose name matches the UTF-8 string N, or 0 if there is

2730

** no match.

2731

*/

2732

int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

2733

2734

/*

2735

** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}

2736

**

2737

** Contrary to the intuition of many, [sqlite3_reset()] does not

2738

** reset the [sqlite3_bind_blob | bindings] on a

2739

** [prepared statement]. Use this routine to

2740

** reset all host parameters to NULL.

2741

**

2742

** INVARIANTS:

2743

**

2744

** {F13661} The [sqlite3_clear_bindings(S)] interface resets all

2745

** SQL parameter bindings in [prepared statement] S

2746

** back to NULL.

2747

*/

2748

int sqlite3_clear_bindings(sqlite3_stmt*);

2749

2750

/*

2751

** CAPI3REF: Number Of Columns In A Result Set {F13710}

2752

**

2753

** Return the number of columns in the result set returned by the

2754

** [prepared statement]. This routine returns 0

2755

** if pStmt is an SQL statement that does not return data (for

2756

** example an UPDATE).

2757

**

2758

** INVARIANTS:

2759

**

2760

** {F13711} The [sqlite3_column_count(S)] interface returns the number of

2761

** columns in the result set generated by the

2762

** [prepared statement] S, or 0 if S does not generate

2763

** a result set.

2764

*/

2765

int sqlite3_column_count(sqlite3_stmt *pStmt);

2766

2767

/*

2768

** CAPI3REF: Column Names In A Result Set {F13720}

2769

**

2770

** These routines return the name assigned to a particular column

2771

** in the result set of a SELECT statement. The sqlite3_column_name()

2772

** interface returns a pointer to a zero-terminated UTF8 string

2773

** and sqlite3_column_name16() returns a pointer to a zero-terminated

2774

** UTF16 string. The first parameter is the

2775

** [prepared statement] that implements the SELECT statement.

2776

** The second parameter is the column number. The left-most column is

2777

** number 0.

2778

**

2779

** The returned string pointer is valid until either the

2780

** [prepared statement] is destroyed by [sqlite3_finalize()]

2781

** or until the next call sqlite3_column_name() or sqlite3_column_name16()

2782

** on the same column.

2783

**

2784

** If sqlite3_malloc() fails during the processing of either routine

2785

** (for example during a conversion from UTF-8 to UTF-16) then a

2786

** NULL pointer is returned.

2787

**

2788

** The name of a result column is the value of the "AS" clause for

2789

** that column, if there is an AS clause. If there is no AS clause

2790

** then the name of the column is unspecified and may change from

2791

** one release of SQLite to the next.

2792

**

2793

** INVARIANTS:

2794

**

2795

** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]

2796

** interface returns the name

2797

** of the Nth column (where 0 is the left-most column) for the

2798

** result set of [prepared statement] S as a

2799

** zero-terminated UTF-8 string.

2800

**

2801

** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]

2802

** interface returns the name

2803

** of the Nth column (where 0 is the left-most column) for the

2804

** result set of [prepared statement] S as a

2805

** zero-terminated UTF-16 string in the native byte order.

2806

**

2807

** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]

2808

** interfaces return a NULL pointer if they are unable to

2809

** allocate memory memory to hold there normal return strings.

2810

**

2811

** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or

2812

** [sqlite3_column_name16(S,N)] is out of range, then the

2813

** interfaces returns a NULL pointer.

2814

**

2815

** {F13726} The strings returned by [sqlite3_column_name(S,N)] and

2816

** [sqlite3_column_name16(S,N)] are valid until the next

2817

** call to either routine with the same S and N parameters

2818

** or until [sqlite3_finalize(S)] is called.

2819

**

2820

** {F13727} When a result column of a [SELECT] statement contains

2821

** an AS clause, the name of that column is the indentifier

2822

** to the right of the AS keyword.

2823

*/

2824

const char *sqlite3_column_name(sqlite3_stmt*, int N);

2825

const void *sqlite3_column_name16(sqlite3_stmt*, int N);

2826

2827

/*

2828

** CAPI3REF: Source Of Data In A Query Result {F13740}

2829

**

2830

** These routines provide a means to determine what column of what

2831

** table in which database a result of a SELECT statement comes from.

2832

** The name of the database or table or column can be returned as

2833

** either a UTF8 or UTF16 string. The _database_ routines return

2834

** the database name, the _table_ routines return the table name, and

2835

** the origin_ routines return the column name.

2836

** The returned string is valid until

2837

** the [prepared statement] is destroyed using

2838

** [sqlite3_finalize()] or until the same information is requested

2839

** again in a different encoding.

2840

**

2841

** The names returned are the original un-aliased names of the

2842

** database, table, and column.

2843

**

2844

** The first argument to the following calls is a [prepared statement].

2845

** These functions return information about the Nth column returned by

2846

** the statement, where N is the second function argument.

2847

**

2848

** If the Nth column returned by the statement is an expression

2849

** or subquery and is not a column value, then all of these functions

2850

** return NULL. These routine might also return NULL if a memory

2851

** allocation error occurs. Otherwise, they return the

2852

** name of the attached database, table and column that query result

2853

** column was extracted from.

2854

**

2855

** As with all other SQLite APIs, those postfixed with "16" return

2856

** UTF-16 encoded strings, the other functions return UTF-8. {END}

2857

**

2858

** These APIs are only available if the library was compiled with the

2859

** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.

2860

**

2861

** {U13751}

2862

** If two or more threads call one or more of these routines against the same

2863

** prepared statement and column at the same time then the results are

2864

** undefined.

2865

**

2866

** INVARIANTS:

2867

**

2868

** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either

2869

** the UTF-8 zero-terminated name of the database from which the

2870

** Nth result column of [prepared statement] S

2871

** is extracted, or NULL if the the Nth column of S is a

2872

** general expression or if unable to allocate memory

2873

** to store the name.

2874

**

2875

** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either

2876

** the UTF-16 native byte order

2877

** zero-terminated name of the database from which the

2878

** Nth result column of [prepared statement] S

2879

** is extracted, or NULL if the the Nth column of S is a

2880

** general expression or if unable to allocate memory

2881

** to store the name.

2882

**

2883

** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either

2884

** the UTF-8 zero-terminated name of the table from which the

2885

** Nth result column of [prepared statement] S

2886

** is extracted, or NULL if the the Nth column of S is a

2887

** general expression or if unable to allocate memory

2888

** to store the name.

2889

**

2890

** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either

2891

** the UTF-16 native byte order

2892

** zero-terminated name of the table from which the

2893

** Nth result column of [prepared statement] S

2894

** is extracted, or NULL if the the Nth column of S is a

2895

** general expression or if unable to allocate memory

2896

** to store the name.

2897

**

2898

** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either

2899

** the UTF-8 zero-terminated name of the table column from which the

2900

** Nth result column of [prepared statement] S

2901

** is extracted, or NULL if the the Nth column of S is a

2902

** general expression or if unable to allocate memory

2903

** to store the name.

2904

**

2905

** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either

2906

** the UTF-16 native byte order

2907

** zero-terminated name of the table column from which the

2908

** Nth result column of [prepared statement] S

2909

** is extracted, or NULL if the the Nth column of S is a

2910

** general expression or if unable to allocate memory

2911

** to store the name.

2912

**

2913

** {F13748} The return values from

2914

** [sqlite3_column_database_name|column metadata interfaces]

2915

** are valid

2916

** for the lifetime of the [prepared statement]

2917

** or until the encoding is changed by another metadata

2918

** interface call for the same prepared statement and column.

2919

**

2920

** LIMITATIONS:

2921

**

2922

** {U13751} If two or more threads call one or more

2923

** [sqlite3_column_database_name|column metadata interfaces]

2924

** the same [prepared statement] and result column

2925

** at the same time then the results are undefined.

2926

*/

2927

const char *sqlite3_column_database_name(sqlite3_stmt*,int);

2928

const void *sqlite3_column_database_name16(sqlite3_stmt*,int);

2929

const char *sqlite3_column_table_name(sqlite3_stmt*,int);

2930

const void *sqlite3_column_table_name16(sqlite3_stmt*,int);

2931

const char *sqlite3_column_origin_name(sqlite3_stmt*,int);

2932

const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);

2933

2934

/*

2935

** CAPI3REF: Declared Datatype Of A Query Result {F13760}

2936

**

2937

** The first parameter is a [prepared statement].

2938

** If this statement is a SELECT statement and the Nth column of the

2939

** returned result set of that SELECT is a table column (not an

2940

** expression or subquery) then the declared type of the table

2941

** column is returned. If the Nth column of the result set is an

2942

** expression or subquery, then a NULL pointer is returned.

2943

** The returned string is always UTF-8 encoded. {END}

2944

** For example, in the database schema:

2945

**

2946

** CREATE TABLE t1(c1 VARIANT);

2947

**

2948

** And the following statement compiled:

2949

**

2950

** SELECT c1 + 1, c1 FROM t1;

2951

**

2952

** Then this routine would return the string "VARIANT" for the second

2953

** result column (i==1), and a NULL pointer for the first result column

2954

** (i==0).

2955

**

2956

** SQLite uses dynamic run-time typing. So just because a column

2957

** is declared to contain a particular type does not mean that the

2958

** data stored in that column is of the declared type. SQLite is

2959

** strongly typed, but the typing is dynamic not static. Type

2960

** is associated with individual values, not with the containers

2961

** used to hold those values.

2962

**

2963

** INVARIANTS:

2964

**

2965

** {F13761} A successful call to [sqlite3_column_decltype(S,N)]

2966

** returns a zero-terminated UTF-8 string containing the

2967

** the declared datatype of the table column that appears

2968

** as the Nth column (numbered from 0) of the result set to the

2969

** [prepared statement] S.

2970

**

2971

** {F13762} A successful call to [sqlite3_column_decltype16(S,N)]

2972

** returns a zero-terminated UTF-16 native byte order string

2973

** containing the declared datatype of the table column that appears

2974

** as the Nth column (numbered from 0) of the result set to the

2975

** [prepared statement] S.

2976

**

2977

** {F13763} If N is less than 0 or N is greater than or equal to

2978

** the number of columns in [prepared statement] S

2979

** or if the Nth column of S is an expression or subquery rather

2980

** than a table column or if a memory allocation failure

2981

** occurs during encoding conversions, then

2982

** calls to [sqlite3_column_decltype(S,N)] or

2983

** [sqlite3_column_decltype16(S,N)] return NULL.

2984

*/

2985

const char *sqlite3_column_decltype(sqlite3_stmt*,int);

2986

const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

2987

2988

/*

2989

** CAPI3REF: Evaluate An SQL Statement {F13200}

2990

**

2991

** After an [prepared statement] has been prepared with a call

2992

** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of

2993

** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],

2994

** then this function must be called one or more times to evaluate the

2995

** statement.

2996

**

2997

** The details of the behavior of this sqlite3_step() interface depend

2998

** on whether the statement was prepared using the newer "v2" interface

2999

** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy

3000

** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the

3001

** new "v2" interface is recommended for new applications but the legacy

3002

** interface will continue to be supported.

3003

**

3004

** In the legacy interface, the return value will be either [SQLITE_BUSY],

3005

** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].

3006

** With the "v2" interface, any of the other [SQLITE_OK | result code]

3007

** or [SQLITE_IOERR_READ | extended result code] might be returned as

3008

** well.

3009

**

3010

** [SQLITE_BUSY] means that the database engine was unable to acquire the

3011

** database locks it needs to do its job. If the statement is a COMMIT

3012

** or occurs outside of an explicit transaction, then you can retry the

3013

** statement. If the statement is not a COMMIT and occurs within a

3014

** explicit transaction then you should rollback the transaction before

3015

** continuing.

3016

**

3017

** [SQLITE_DONE] means that the statement has finished executing

3018

** successfully. sqlite3_step() should not be called again on this virtual

3019

** machine without first calling [sqlite3_reset()] to reset the virtual

3020

** machine back to its initial state.

3021

**

3022

** If the SQL statement being executed returns any data, then

3023

** [SQLITE_ROW] is returned each time a new row of data is ready

3024

** for processing by the caller. The values may be accessed using

3025

** the [sqlite3_column_int | column access functions].

3026

** sqlite3_step() is called again to retrieve the next row of data.

3027

**

3028

** [SQLITE_ERROR] means that a run-time error (such as a constraint

3029

** violation) has occurred. sqlite3_step() should not be called again on

3030

** the VM. More information may be found by calling [sqlite3_errmsg()].

3031

** With the legacy interface, a more specific error code (example:

3032

** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)

3033

** can be obtained by calling [sqlite3_reset()] on the

3034

** [prepared statement]. In the "v2" interface,

3035

** the more specific error code is returned directly by sqlite3_step().

3036

**

3037

** [SQLITE_MISUSE] means that the this routine was called inappropriately.

3038

** Perhaps it was called on a [prepared statement] that has

3039

** already been [sqlite3_finalize | finalized] or on one that had

3040

** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could

3041

** be the case that the same database connection is being used by two or

3042

** more threads at the same moment in time.

3043

**

3044

** Goofy Interface Alert:

3045

** In the legacy interface,

3046

** the sqlite3_step() API always returns a generic error code,

3047

** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]

3048

** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or

3049

** [sqlite3_finalize()] in order to find one of the specific

3050

** [error codes] that better describes the error.

3051

** We admit that this is a goofy design. The problem has been fixed

3052

** with the "v2" interface. If you prepare all of your SQL statements

3053

** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead

3054

** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the

3055

** more specific [error codes] are returned directly

3056

** by sqlite3_step(). The use of the "v2" interface is recommended.

3057

**

3058

** INVARIANTS:

3059

**

3060

** {F13202} If [prepared statement] S is ready to be

3061

** run, then [sqlite3_step(S)] advances that prepared statement

3062

** until to completion or until it is ready to return another

3063

** row of the result set or an interrupt or run-time error occurs.

3064

**

3065

** {F15304} When a call to [sqlite3_step(S)] causes the

3066

** [prepared statement] S to run to completion,

3067

** the function returns [SQLITE_DONE].

3068

**

3069

** {F15306} When a call to [sqlite3_step(S)] stops because it is ready

3070

** to return another row of the result set, it returns

3071

** [SQLITE_ROW].

3072

**

3073

** {F15308} If a call to [sqlite3_step(S)] encounters an

3074

** [sqlite3_interrupt|interrupt] or a run-time error,

3075

** it returns an appropraite error code that is not one of

3076

** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].

3077

**

3078

** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error

3079

** occurs during a call to [sqlite3_step(S)]

3080

** for a [prepared statement] S created using

3081

** legacy interfaces [sqlite3_prepare()] or

3082

** [sqlite3_prepare16()] then the function returns either

3083

** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].

3084

*/

3085

int sqlite3_step(sqlite3_stmt*);

3086

3087

/*

3088

** CAPI3REF: Number of columns in a result set {F13770}

3089

**

3090

** Return the number of values in the current row of the result set.

3091

**

3092

** INVARIANTS:

3093

**

3094

** {F13771} After a call to [sqlite3_step(S)] that returns

3095

** [SQLITE_ROW], the [sqlite3_data_count(S)] routine

3096

** will return the same value as the

3097

** [sqlite3_column_count(S)] function.

3098

**

3099

** {F13772} After [sqlite3_step(S)] has returned any value other than

3100

** [SQLITE_ROW] or before [sqlite3_step(S)] has been

3101

** called on the [prepared statement] for

3102

** the first time since it was [sqlite3_prepare|prepared]

3103

** or [sqlite3_reset|reset], the [sqlite3_data_count(S)]

3104

** routine returns zero.

3105

*/

3106

int sqlite3_data_count(sqlite3_stmt *pStmt);

3107

3108

/*

3109

** CAPI3REF: Fundamental Datatypes {F10265}

3110

** KEYWORDS: SQLITE_TEXT

3111

**

3112

** {F10266}Every value in SQLite has one of five fundamental datatypes:

3113

**

3114

** <ul>

3115

** <li> 64-bit signed integer

3116

** <li> 64-bit IEEE floating point number

3117

** <li> string

3118

** <li> BLOB

3119

** <li> NULL

3120

** </ul> {END}

3121

**

3122

** These constants are codes for each of those types.

3123

**

3124

** Note that the SQLITE_TEXT constant was also used in SQLite version 2

3125

** for a completely different meaning. Software that links against both

3126

** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not

3127

** SQLITE_TEXT.

3128

*/

3129

#define SQLITE_INTEGER 1

3130

#define SQLITE_FLOAT 2

3131

#define SQLITE_BLOB 4

3132

#define SQLITE_NULL 5

3133

#ifdef SQLITE_TEXT

3134

# undef SQLITE_TEXT

3135

#else

3136

# define SQLITE_TEXT 3

3137

#endif

3138

#define SQLITE3_TEXT 3

3139

3140

/*

3141

** CAPI3REF: Results Values From A Query {F13800}

3142

**

3143

** These routines form the "result set query" interface.

3144

**

3145

** These routines return information about

3146

** a single column of the current result row of a query. In every

3147

** case the first argument is a pointer to the

3148

** [prepared statement] that is being

3149

** evaluated (the [sqlite3_stmt*] that was returned from

3150

** [sqlite3_prepare_v2()] or one of its variants) and

3151

** the second argument is the index of the column for which information

3152

** should be returned. The left-most column of the result set

3153

** has an index of 0.

3154

**

3155

** If the SQL statement is not currently point to a valid row, or if the

3156

** the column index is out of range, the result is undefined.

3157

** These routines may only be called when the most recent call to

3158

** [sqlite3_step()] has returned [SQLITE_ROW] and neither

3159

** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.

3160

** If any of these routines are called after [sqlite3_reset()] or

3161

** [sqlite3_finalize()] or after [sqlite3_step()] has returned

3162

** something other than [SQLITE_ROW], the results are undefined.

3163

** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]

3164

** are called from a different thread while any of these routines

3165

** are pending, then the results are undefined.

3166

**

3167

** The sqlite3_column_type() routine returns

3168

** [SQLITE_INTEGER | datatype code] for the initial data type

3169

** of the result column. The returned value is one of [SQLITE_INTEGER],

3170

** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value

3171

** returned by sqlite3_column_type() is only meaningful if no type

3172

** conversions have occurred as described below. After a type conversion,

3173

** the value returned by sqlite3_column_type() is undefined. Future

3174

** versions of SQLite may change the behavior of sqlite3_column_type()

3175

** following a type conversion.

3176

**

3177

** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()

3178

** routine returns the number of bytes in that BLOB or string.

3179

** If the result is a UTF-16 string, then sqlite3_column_bytes() converts

3180

** the string to UTF-8 and then returns the number of bytes.

3181

** If the result is a numeric value then sqlite3_column_bytes() uses

3182

** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns

3183

** the number of bytes in that string.

3184

** The value returned does not include the zero terminator at the end

3185

** of the string. For clarity: the value returned is the number of

3186

** bytes in the string, not the number of characters.

3187

**

3188

** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),

3189

** even empty strings, are always zero terminated. The return

3190

** value from sqlite3_column_blob() for a zero-length blob is an arbitrary

3191

** pointer, possibly even a NULL pointer.

3192

**

3193

** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()

3194

** but leaves the result in UTF-16 in native byte order instead of UTF-8.

3195

** The zero terminator is not included in this count.

3196

**

3197

** The object returned by [sqlite3_column_value()] is an

3198

** [unprotected sqlite3_value] object. An unprotected sqlite3_value object

3199

** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].

3200

** If the [unprotected sqlite3_value] object returned by

3201

** [sqlite3_column_value()] is used in any other way, including calls

3202

** to routines like

3203

** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()],

3204

** then the behavior is undefined.

3205

**

3206

** These routines attempt to convert the value where appropriate. For

3207

** example, if the internal representation is FLOAT and a text result

3208

** is requested, [sqlite3_snprintf()] is used internally to do the conversion

3209

** automatically. The following table details the conversions that

3210

** are applied:

3211

**

3212

** <blockquote>

3213

** <table border="1">

3214

** <tr><th> Internal Type <th> Requested Type <th> Conversion

3215

**

3216

** <tr><td> NULL <td> INTEGER <td> Result is 0

3217

** <tr><td> NULL <td> FLOAT <td> Result is 0.0

3218

** <tr><td> NULL <td> TEXT <td> Result is NULL pointer

3219

** <tr><td> NULL <td> BLOB <td> Result is NULL pointer

3220

** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float

3221

** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer

3222

** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT

3223

** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer

3224

** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float

3225

** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT

3226

** <tr><td> TEXT <td> INTEGER <td> Use atoi()

3227

** <tr><td> TEXT <td> FLOAT <td> Use atof()

3228

** <tr><td> TEXT <td> BLOB <td> No change

3229

** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()

3230

** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()

3231

** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed

3232

** </table>

3233

** </blockquote>

3234

**

3235

** The table above makes reference to standard C library functions atoi()

3236

** and atof(). SQLite does not really use these functions. It has its

3237

** on equavalent internal routines. The atoi() and atof() names are

3238

** used in the table for brevity and because they are familiar to most

3239

** C programmers.

3240

**

3241

** Note that when type conversions occur, pointers returned by prior

3242

** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or

3243

** sqlite3_column_text16() may be invalidated.

3244

** Type conversions and pointer invalidations might occur

3245

** in the following cases:

3246

**

3247

** <ul>

3248

** <li> The initial content is a BLOB and sqlite3_column_text()

3249

** or sqlite3_column_text16() is called. A zero-terminator might

3250

** need to be added to the string.</li>

3251

**

3252

** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or

3253

** sqlite3_column_text16() is called. The content must be converted

3254

** to UTF-16.</li>

3255

**

3256

** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or

3257

** sqlite3_column_text() is called. The content must be converted

3258

** to UTF-8.</li>

3259

** </ul>

3260

**

3261

** Conversions between UTF-16be and UTF-16le are always done in place and do

3262

** not invalidate a prior pointer, though of course the content of the buffer

3263

** that the prior pointer points to will have been modified. Other kinds

3264

** of conversion are done in place when it is possible, but sometime it is

3265

** not possible and in those cases prior pointers are invalidated.

3266

**

3267

** The safest and easiest to remember policy is to invoke these routines

3268

** in one of the following ways:

3269

**

3270

** <ul>

3271

** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>

3272

** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>

3273

** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>

3274

** </ul>

3275

**

3276

** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),

3277

** or sqlite3_column_text16() first to force the result into the desired

3278

** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to

3279

** find the size of the result. Do not mix call to sqlite3_column_text() or

3280

** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not

3281

** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().

3282

**

3283

** The pointers returned are valid until a type conversion occurs as

3284

** described above, or until [sqlite3_step()] or [sqlite3_reset()] or

3285

** [sqlite3_finalize()] is called. The memory space used to hold strings

3286

** and blobs is freed automatically. Do not pass the pointers returned

3287

** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into

3288

** [sqlite3_free()].

3289

**

3290

** If a memory allocation error occurs during the evaluation of any

3291

** of these routines, a default value is returned. The default value

3292

** is either the integer 0, the floating point number 0.0, or a NULL

3293

** pointer. Subsequent calls to [sqlite3_errcode()] will return

3294

** [SQLITE_NOMEM].

3295

**

3296

** INVARIANTS:

3297

**

3298

** {F13803} The [sqlite3_column_blob(S,N)] interface converts the

3299

** Nth column in the current row of the result set for

3300

** [prepared statement] S into a blob and then returns a

3301

** pointer to the converted value.

3302

**

3303

** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the

3304

** number of bytes in the blob or string (exclusive of the

3305

** zero terminator on the string) that was returned by the

3306

** most recent call to [sqlite3_column_blob(S,N)] or

3307

** [sqlite3_column_text(S,N)].

3308

**

3309

** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the

3310

** number of bytes in the string (exclusive of the

3311

** zero terminator on the string) that was returned by the

3312

** most recent call to [sqlite3_column_text16(S,N)].

3313

**

3314

** {F13812} The [sqlite3_column_double(S,N)] interface converts the

3315

** Nth column in the current row of the result set for

3316

** [prepared statement] S into a floating point value and

3317

** returns a copy of that value.

3318

**

3319

** {F13815} The [sqlite3_column_int(S,N)] interface converts the

3320

** Nth column in the current row of the result set for

3321

** [prepared statement] S into a 64-bit signed integer and

3322

** returns the lower 32 bits of that integer.

3323

**

3324

** {F13818} The [sqlite3_column_int64(S,N)] interface converts the

3325

** Nth column in the current row of the result set for

3326

** [prepared statement] S into a 64-bit signed integer and

3327

** returns a copy of that integer.

3328

**

3329

** {F13821} The [sqlite3_column_text(S,N)] interface converts the

3330

** Nth column in the current row of the result set for

3331

** [prepared statement] S into a zero-terminated UTF-8

3332

** string and returns a pointer to that string.

3333

**

3334

** {F13824} The [sqlite3_column_text16(S,N)] interface converts the

3335

** Nth column in the current row of the result set for

3336

** [prepared statement] S into a zero-terminated 2-byte

3337

** aligned UTF-16 native byte order

3338

** string and returns a pointer to that string.

3339

**

3340

** {F13827} The [sqlite3_column_type(S,N)] interface returns

3341

** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],

3342

** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for

3343

** the Nth column in the current row of the result set for

3344

** [prepared statement] S.

3345

**

3346

** {F13830} The [sqlite3_column_value(S,N)] interface returns a

3347

** pointer to an [unprotected sqlite3_value] object for the

3348

** Nth column in the current row of the result set for

3349

** [prepared statement] S.

3350

*/

3351

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);

3352

int sqlite3_column_bytes(sqlite3_stmt*, int iCol);

3353

int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);

3354

double sqlite3_column_double(sqlite3_stmt*, int iCol);

3355

int sqlite3_column_int(sqlite3_stmt*, int iCol);

3356

sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);

3357

const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);

3358

const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);

3359

int sqlite3_column_type(sqlite3_stmt*, int iCol);

3360

sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

3361

3362

/*

3363

** CAPI3REF: Destroy A Prepared Statement Object {F13300}

3364

**

3365

** The sqlite3_finalize() function is called to delete a

3366

** [prepared statement]. If the statement was

3367

** executed successfully, or not executed at all, then SQLITE_OK is returned.

3368

** If execution of the statement failed then an

3369

** [error code] or [extended error code]

3370

** is returned.

3371

**

3372

** This routine can be called at any point during the execution of the

3373

** [prepared statement]. If the virtual machine has not

3374

** completed execution when this routine is called, that is like

3375

** encountering an error or an interrupt. (See [sqlite3_interrupt()].)

3376

** Incomplete updates may be rolled back and transactions cancelled,

3377

** depending on the circumstances, and the

3378

** [error code] returned will be [SQLITE_ABORT].

3379

**

3380

** INVARIANTS:

3381

**

3382

** {F11302} The [sqlite3_finalize(S)] interface destroys the

3383

** [prepared statement] S and releases all

3384

** memory and file resources held by that object.

3385

**

3386

** {F11304} If the most recent call to [sqlite3_step(S)] for the

3387

** [prepared statement] S returned an error,

3388

** then [sqlite3_finalize(S)] returns that same error.

3389

*/

3390

int sqlite3_finalize(sqlite3_stmt *pStmt);

3391

3392

/*

3393

** CAPI3REF: Reset A Prepared Statement Object {F13330}

3394

**

3395

** The sqlite3_reset() function is called to reset a

3396

** [prepared statement] object.

3397

** back to its initial state, ready to be re-executed.

3398

** Any SQL statement variables that had values bound to them using

3399

** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.

3400

** Use [sqlite3_clear_bindings()] to reset the bindings.

3401

**

3402

** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S

3403

** back to the beginning of its program.

3404

**

3405

** {F11334} If the most recent call to [sqlite3_step(S)] for

3406

** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],

3407

** or if [sqlite3_step(S)] has never before been called on S,

3408

** then [sqlite3_reset(S)] returns [SQLITE_OK].

3409

**

3410

** {F11336} If the most recent call to [sqlite3_step(S)] for

3411

** [prepared statement] S indicated an error, then

3412

** [sqlite3_reset(S)] returns an appropriate [error code].

3413

**

3414

** {F11338} The [sqlite3_reset(S)] interface does not change the values

3415

** of any [sqlite3_bind_blob|bindings] on [prepared statement] S.

3416

*/

3417

int sqlite3_reset(sqlite3_stmt *pStmt);

3418

3419

/*

3420

** CAPI3REF: Create Or Redefine SQL Functions {F16100}

3421

** KEYWORDS: {function creation routines}

3422

**

3423

** These two functions (collectively known as

3424

** "function creation routines") are used to add SQL functions or aggregates

3425

** or to redefine the behavior of existing SQL functions or aggregates. The

3426

** difference only between the two is that the second parameter, the

3427

** name of the (scalar) function or aggregate, is encoded in UTF-8 for

3428

** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().

3429

**

3430

** The first parameter is the [database connection] to which the SQL

3431

** function is to be added. If a single

3432

** program uses more than one [database connection] internally, then SQL

3433

** functions must be added individually to each [database connection].

3434

**

3435

** The second parameter is the name of the SQL function to be created

3436

** or redefined.

3437

** The length of the name is limited to 255 bytes, exclusive of the

3438

** zero-terminator. Note that the name length limit is in bytes, not

3439

** characters. Any attempt to create a function with a longer name

3440

** will result in an SQLITE_ERROR error.

3441

**

3442

** The third parameter is the number of arguments that the SQL function or

3443

** aggregate takes. If this parameter is negative, then the SQL function or

3444

** aggregate may take any number of arguments.

3445

**

3446

** The fourth parameter, eTextRep, specifies what

3447

** [SQLITE_UTF8 | text encoding] this SQL function prefers for

3448

** its parameters. Any SQL function implementation should be able to work

3449

** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be

3450

** more efficient with one encoding than another. It is allowed to

3451

** invoke sqlite3_create_function() or sqlite3_create_function16() multiple

3452

** times with the same function but with different values of eTextRep.

3453

** When multiple implementations of the same function are available, SQLite

3454

** will pick the one that involves the least amount of data conversion.

3455

** If there is only a single implementation which does not care what

3456

** text encoding is used, then the fourth argument should be

3457

** [SQLITE_ANY].

3458

**

3459

** The fifth parameter is an arbitrary pointer. The implementation

3460

** of the function can gain access to this pointer using

3461

** [sqlite3_user_data()].

3462

**

3463

** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are

3464

** pointers to C-language functions that implement the SQL

3465

** function or aggregate. A scalar SQL function requires an implementation of

3466

** the xFunc callback only, NULL pointers should be passed as the xStep

3467

** and xFinal parameters. An aggregate SQL function requires an implementation

3468

** of xStep and xFinal and NULL should be passed for xFunc. To delete an

3469

** existing SQL function or aggregate, pass NULL for all three function

3470

** callback.

3471

**

3472

** It is permitted to register multiple implementations of the same

3473

** functions with the same name but with either differing numbers of

3474

** arguments or differing perferred text encodings. SQLite will use

3475

** the implementation most closely matches the way in which the

3476

** SQL function is used.

3477

**

3478

** INVARIANTS:

3479

**

3480

** {F16103} The [sqlite3_create_function16()] interface behaves exactly

3481

** like [sqlite3_create_function()] in every way except that it

3482

** interprets the zFunctionName argument as

3483

** zero-terminated UTF-16 native byte order instead of as a

3484

** zero-terminated UTF-8.

3485

**

3486

** {F16106} A successful invocation of

3487

** the [sqlite3_create_function(D,X,N,E,...)] interface registers

3488

** or replaces callback functions in [database connection] D

3489

** used to implement the SQL function named X with N parameters

3490

** and having a perferred text encoding of E.

3491

**

3492

** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]

3493

** replaces the P, F, S, and L values from any prior calls with

3494

** the same D, X, N, and E values.

3495

**

3496

** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with

3497

** a return code of [SQLITE_ERROR] if the SQL function name X is

3498

** longer than 255 bytes exclusive of the zero terminator.

3499

**

3500

** {F16118} Either F must be NULL and S and L are non-NULL or else F

3501

** is non-NULL and S and L are NULL, otherwise

3502

** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].

3503

**

3504

** {F16121} The [sqlite3_create_function(D,...)] interface fails with an

3505

** error code of [SQLITE_BUSY] if there exist [prepared statements]

3506

** associated with the [database connection] D.

3507

**

3508

** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an

3509

** error code of [SQLITE_ERROR] if parameter N (specifying the number

3510

** of arguments to the SQL function being registered) is less

3511

** than -1 or greater than 127.

3512

**

3513

** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]

3514

** interface causes callbacks to be invoked for the SQL function

3515

** named X when the number of arguments to the SQL function is

3516

** exactly N.

3517

**

3518

** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]

3519

** interface causes callbacks to be invoked for the SQL function

3520

** named X with any number of arguments.

3521

**

3522

** {F16133} When calls to [sqlite3_create_function(D,X,N,...)]

3523

** specify multiple implementations of the same function X

3524

** and when one implementation has N>=0 and the other has N=(-1)

3525

** the implementation with a non-zero N is preferred.

3526

**

3527

** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)]

3528

** specify multiple implementations of the same function X with

3529

** the same number of arguments N but with different

3530

** encodings E, then the implementation where E matches the

3531

** database encoding is preferred.

3532

**

3533

** {F16139} For an aggregate SQL function created using

3534

** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer

3535

** function L will always be invoked exactly once if the

3536

** step function S is called one or more times.

3537

**

3538

** {F16142} When SQLite invokes either the xFunc or xStep function of

3539

** an application-defined SQL function or aggregate created

3540

** by [sqlite3_create_function()] or [sqlite3_create_function16()],

3541

** then the array of [sqlite3_value] objects passed as the

3542

** third parameter are always [protected sqlite3_value] objects.

3543

*/

3544

int sqlite3_create_function(

3545

sqlite3 *db,

3546

const char *zFunctionName,

3547

int nArg,

3548

int eTextRep,

3549

void *pApp,

3550

void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

3551

void (*xStep)(sqlite3_context*,int,sqlite3_value**),

3552

void (*xFinal)(sqlite3_context*)

3553

);

3554

int sqlite3_create_function16(

3555

sqlite3 *db,

3556

const void *zFunctionName,

3557

int nArg,

3558

int eTextRep,

3559

void *pApp,

3560

void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

3561

void (*xStep)(sqlite3_context*,int,sqlite3_value**),

3562

void (*xFinal)(sqlite3_context*)

3563

);

3564

3565

/*

3566

** CAPI3REF: Text Encodings {F10267}

3567

**

3568

** These constant define integer codes that represent the various

3569

** text encodings supported by SQLite.

3570

*/

3571

#define SQLITE_UTF8 1

3572

#define SQLITE_UTF16LE 2

3573

#define SQLITE_UTF16BE 3

3574

#define SQLITE_UTF16 4 /* Use native byte order */

3575

#define SQLITE_ANY 5 /* sqlite3_create_function only */

3576

#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */

3577

3578

/*

3579

** CAPI3REF: Obsolete Functions

3580

**

3581

** These functions are all now obsolete. In order to maintain

3582

** backwards compatibility with older code, we continue to support

3583

** these functions. However, new development projects should avoid

3584

** the use of these functions. To help encourage people to avoid

3585

** using these functions, we are not going to tell you want they do.

3586

*/

3587

int sqlite3_aggregate_count(sqlite3_context*);

3588

int sqlite3_expired(sqlite3_stmt*);

3589

int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);

3590

int sqlite3_global_recover(void);

3591

void sqlite3_thread_cleanup(void);

3592

int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);

3593

3594

/*

3595

** CAPI3REF: Obtaining SQL Function Parameter Values {F15100}

3596

**

3597

** The C-language implementation of SQL functions and aggregates uses

3598

** this set of interface routines to access the parameter values on

3599

** the function or aggregate.

3600

**

3601

** The xFunc (for scalar functions) or xStep (for aggregates) parameters

3602

** to [sqlite3_create_function()] and [sqlite3_create_function16()]

3603

** define callbacks that implement the SQL functions and aggregates.

3604

** The 4th parameter to these callbacks is an array of pointers to

3605

** [protected sqlite3_value] objects. There is one [sqlite3_value] object for

3606

** each parameter to the SQL function. These routines are used to

3607

** extract values from the [sqlite3_value] objects.

3608

**

3609

** These routines work only with [protected sqlite3_value] objects.

3610

** Any attempt to use these routines on an [unprotected sqlite3_value]

3611

** object results in undefined behavior.

3612

**

3613

** These routines work just like the corresponding

3614

** [sqlite3_column_blob | sqlite3_column_* routines] except that

3615

** these routines take a single [protected sqlite3_value] object pointer

3616

** instead of an [sqlite3_stmt*] pointer and an integer column number.

3617

**

3618

** The sqlite3_value_text16() interface extracts a UTF16 string

3619

** in the native byte-order of the host machine. The

3620

** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces

3621

** extract UTF16 strings as big-endian and little-endian respectively.

3622

**

3623

** The sqlite3_value_numeric_type() interface attempts to apply

3624

** numeric affinity to the value. This means that an attempt is

3625

** made to convert the value to an integer or floating point. If

3626

** such a conversion is possible without loss of information (in other

3627

** words if the value is a string that looks like a number)

3628

** then the conversion is done. Otherwise no conversion occurs. The

3629

** [SQLITE_INTEGER | datatype] after conversion is returned.

3630

**

3631

** Please pay particular attention to the fact that the pointer that

3632

** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or

3633

** [sqlite3_value_text16()] can be invalidated by a subsequent call to

3634

** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],

3635

** or [sqlite3_value_text16()].

3636

**

3637

** These routines must be called from the same thread as

3638

** the SQL function that supplied the [sqlite3_value*] parameters.

3639

**

3640

**

3641

** INVARIANTS:

3642

**

3643

** {F15103} The [sqlite3_value_blob(V)] interface converts the

3644

** [protected sqlite3_value] object V into a blob and then returns a

3645

** pointer to the converted value.

3646

**

3647

** {F15106} The [sqlite3_value_bytes(V)] interface returns the

3648

** number of bytes in the blob or string (exclusive of the

3649

** zero terminator on the string) that was returned by the

3650

** most recent call to [sqlite3_value_blob(V)] or

3651

** [sqlite3_value_text(V)].

3652

**

3653

** {F15109} The [sqlite3_value_bytes16(V)] interface returns the

3654

** number of bytes in the string (exclusive of the

3655

** zero terminator on the string) that was returned by the

3656

** most recent call to [sqlite3_value_text16(V)],

3657

** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].

3658

**

3659

** {F15112} The [sqlite3_value_double(V)] interface converts the

3660

** [protected sqlite3_value] object V into a floating point value and

3661

** returns a copy of that value.

3662

**

3663

** {F15115} The [sqlite3_value_int(V)] interface converts the

3664

** [protected sqlite3_value] object V into a 64-bit signed integer and

3665

** returns the lower 32 bits of that integer.

3666

**

3667

** {F15118} The [sqlite3_value_int64(V)] interface converts the

3668

** [protected sqlite3_value] object V into a 64-bit signed integer and

3669

** returns a copy of that integer.

3670

**

3671

** {F15121} The [sqlite3_value_text(V)] interface converts the

3672

** [protected sqlite3_value] object V into a zero-terminated UTF-8

3673

** string and returns a pointer to that string.

3674

**

3675

** {F15124} The [sqlite3_value_text16(V)] interface converts the

3676

** [protected sqlite3_value] object V into a zero-terminated 2-byte

3677

** aligned UTF-16 native byte order

3678

** string and returns a pointer to that string.

3679

**

3680

** {F15127} The [sqlite3_value_text16be(V)] interface converts the

3681

** [protected sqlite3_value] object V into a zero-terminated 2-byte

3682

** aligned UTF-16 big-endian

3683

** string and returns a pointer to that string.

3684

**

3685

** {F15130} The [sqlite3_value_text16le(V)] interface converts the

3686

** [protected sqlite3_value] object V into a zero-terminated 2-byte

3687

** aligned UTF-16 little-endian

3688

** string and returns a pointer to that string.

3689

**

3690

** {F15133} The [sqlite3_value_type(V)] interface returns

3691

** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],

3692

** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for

3693

** the [sqlite3_value] object V.

3694

**

3695

** {F15136} The [sqlite3_value_numeric_type(V)] interface converts

3696

** the [protected sqlite3_value] object V into either an integer or

3697

** a floating point value if it can do so without loss of

3698

** information, and returns one of [SQLITE_NULL],

3699

** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or

3700

** [SQLITE_BLOB] as appropriate for

3701

** the [protected sqlite3_value] object V after the conversion attempt.

3702

*/

3703

const void *sqlite3_value_blob(sqlite3_value*);

3704

int sqlite3_value_bytes(sqlite3_value*);

3705

int sqlite3_value_bytes16(sqlite3_value*);

3706

double sqlite3_value_double(sqlite3_value*);

3707

int sqlite3_value_int(sqlite3_value*);

3708

sqlite3_int64 sqlite3_value_int64(sqlite3_value*);

3709

const unsigned char *sqlite3_value_text(sqlite3_value*);

3710

const void *sqlite3_value_text16(sqlite3_value*);

3711

const void *sqlite3_value_text16le(sqlite3_value*);

3712

const void *sqlite3_value_text16be(sqlite3_value*);

3713

int sqlite3_value_type(sqlite3_value*);

3714

int sqlite3_value_numeric_type(sqlite3_value*);

3715

3716

/*

3717

** CAPI3REF: Obtain Aggregate Function Context {F16210}

3718

**

3719

** The implementation of aggregate SQL functions use this routine to allocate

3720

** a structure for storing their state.

3721

** The first time the sqlite3_aggregate_context() routine is

3722

** is called for a particular aggregate, SQLite allocates nBytes of memory

3723

** zeros that memory, and returns a pointer to it.

3724

** On second and subsequent calls to sqlite3_aggregate_context()

3725

** for the same aggregate function index, the same buffer is returned.

3726

** The implementation

3727

** of the aggregate can use the returned buffer to accumulate data.

3728

**

3729

** SQLite automatically frees the allocated buffer when the aggregate

3730

** query concludes.

3731

**

3732

** The first parameter should be a copy of the

3733

** [sqlite3_context | SQL function context] that is the first

3734

** parameter to the callback routine that implements the aggregate

3735

** function.

3736

**

3737

** This routine must be called from the same thread in which

3738

** the aggregate SQL function is running.

3739

**

3740

** INVARIANTS:

3741

**

3742

** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for

3743

** a particular instance of an aggregate function (for a particular

3744

** context C) causes SQLite to allocation N bytes of memory,

3745

** zero that memory, and return a pointer to the allocationed

3746

** memory.

3747

**

3748

** {F16213} If a memory allocation error occurs during

3749

** [sqlite3_aggregate_context(C,N)] then the function returns 0.

3750

**

3751

** {F16215} Second and subsequent invocations of

3752

** [sqlite3_aggregate_context(C,N)] for the same context pointer C

3753

** ignore the N parameter and return a pointer to the same

3754

** block of memory returned by the first invocation.

3755

**

3756

** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is

3757

** automatically freed on the next call to [sqlite3_reset()]

3758

** or [sqlite3_finalize()] for the [prepared statement] containing

3759

** the aggregate function associated with context C.

3760

*/

3761

void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

3762

3763

/*

3764

** CAPI3REF: User Data For Functions {F16240}

3765

**

3766

** The sqlite3_user_data() interface returns a copy of

3767

** the pointer that was the pUserData parameter (the 5th parameter)

3768

** of the the [sqlite3_create_function()]

3769

** and [sqlite3_create_function16()] routines that originally

3770

** registered the application defined function. {END}

3771

**

3772

** This routine must be called from the same thread in which

3773

** the application-defined function is running.

3774

**

3775

** INVARIANTS:

3776

**

3777

** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the

3778

** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]

3779

** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that

3780

** registered the SQL function associated with

3781

** [sqlite3_context] C.

3782

*/

3783

void *sqlite3_user_data(sqlite3_context*);

3784

3785

/*

3786

** CAPI3REF: Database Connection For Functions {F16250}

3787

**

3788

** The sqlite3_context_db_handle() interface returns a copy of

3789

** the pointer to the [database connection] (the 1st parameter)

3790

** of the the [sqlite3_create_function()]

3791

** and [sqlite3_create_function16()] routines that originally

3792

** registered the application defined function.

3793

**

3794

** INVARIANTS:

3795

**

3796

** {F16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the

3797

** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]

3798

** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that

3799

** registered the SQL function associated with

3800

** [sqlite3_context] C.

3801

*/

3802

sqlite3 *sqlite3_context_db_handle(sqlite3_context*);

3803

3804

/*

3805

** CAPI3REF: Function Auxiliary Data {F16270}

3806

**

3807

** The following two functions may be used by scalar SQL functions to

3808

** associate meta-data with argument values. If the same value is passed to

3809

** multiple invocations of the same SQL function during query execution, under

3810

** some circumstances the associated meta-data may be preserved. This may

3811

** be used, for example, to add a regular-expression matching scalar

3812

** function. The compiled version of the regular expression is stored as

3813

** meta-data associated with the SQL value passed as the regular expression

3814

** pattern. The compiled regular expression can be reused on multiple

3815

** invocations of the same function so that the original pattern string

3816

** does not need to be recompiled on each invocation.

3817

**

3818

** The sqlite3_get_auxdata() interface returns a pointer to the meta-data

3819

** associated by the sqlite3_set_auxdata() function with the Nth argument

3820

** value to the application-defined function.

3821

** If no meta-data has been ever been set for the Nth

3822

** argument of the function, or if the cooresponding function parameter

3823

** has changed since the meta-data was set, then sqlite3_get_auxdata()

3824

** returns a NULL pointer.

3825

**

3826

** The sqlite3_set_auxdata() interface saves the meta-data

3827

** pointed to by its 3rd parameter as the meta-data for the N-th

3828

** argument of the application-defined function. Subsequent

3829

** calls to sqlite3_get_auxdata() might return this data, if it has

3830

** not been destroyed.

3831

** If it is not NULL, SQLite will invoke the destructor

3832

** function given by the 4th parameter to sqlite3_set_auxdata() on

3833

** the meta-data when the corresponding function parameter changes

3834

** or when the SQL statement completes, whichever comes first.

3835

**

3836

** SQLite is free to call the destructor and drop meta-data on

3837

** any parameter of any function at any time. The only guarantee

3838

** is that the destructor will be called before the metadata is

3839

** dropped.

3840

**

3841

** In practice, meta-data is preserved between function calls for

3842

** expressions that are constant at compile time. This includes literal

3843

** values and SQL variables.

3844

**

3845

** These routines must be called from the same thread in which

3846

** the SQL function is running.

3847

**

3848

** INVARIANTS:

3849

**

3850

** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer

3851

** to metadata associated with the Nth parameter of the SQL function

3852

** whose context is C, or NULL if there is no metadata associated

3853

** with that parameter.

3854

**

3855

** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata

3856

** pointer P to the Nth parameter of the SQL function with context

3857

** C.

3858

**

3859

** {F16276} SQLite will invoke the destructor D with a single argument

3860

** which is the metadata pointer P following a call to

3861

** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold

3862

** the metadata.

3863

**

3864

** {F16277} SQLite ceases to hold metadata for an SQL function parameter

3865

** when the value of that parameter changes.

3866

**

3867

** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor

3868

** is called for any prior metadata associated with the same function

3869

** context C and parameter N.

3870

**

3871

** {F16279} SQLite will call destructors for any metadata it is holding

3872

** in a particular [prepared statement] S when either

3873

** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.

3874

*/

3875

void *sqlite3_get_auxdata(sqlite3_context*, int N);

3876

void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

3877

3878

3879

/*

3880

** CAPI3REF: Constants Defining Special Destructor Behavior {F10280}

3881

**

3882

** These are special value for the destructor that is passed in as the

3883

** final argument to routines like [sqlite3_result_blob()]. If the destructor

3884

** argument is SQLITE_STATIC, it means that the content pointer is constant

3885

** and will never change. It does not need to be destroyed. The

3886

** SQLITE_TRANSIENT value means that the content will likely change in

3887

** the near future and that SQLite should make its own private copy of

3888

** the content before returning.

3889

**

3890

** The typedef is necessary to work around problems in certain

3891

** C++ compilers. See ticket #2191.

3892

*/

3893

typedef void (*sqlite3_destructor_type)(void*);

3894

#define SQLITE_STATIC ((sqlite3_destructor_type)0)

3895

#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)

3896

3897

/*

3898

** CAPI3REF: Setting The Result Of An SQL Function {F16400}

3899

**

3900

** These routines are used by the xFunc or xFinal callbacks that

3901

** implement SQL functions and aggregates. See

3902

** [sqlite3_create_function()] and [sqlite3_create_function16()]

3903

** for additional information.

3904

**

3905

** These functions work very much like the

3906

** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used

3907

** to bind values to host parameters in prepared statements.

3908

** Refer to the

3909

** [sqlite3_bind_blob | sqlite3_bind_* documentation] for

3910

** additional information.

3911

**

3912

** The sqlite3_result_blob() interface sets the result from

3913

** an application defined function to be the BLOB whose content is pointed

3914

** to by the second parameter and which is N bytes long where N is the

3915

** third parameter.

3916

** The sqlite3_result_zeroblob() inerfaces set the result of

3917

** the application defined function to be a BLOB containing all zero

3918

** bytes and N bytes in size, where N is the value of the 2nd parameter.

3919

**

3920

** The sqlite3_result_double() interface sets the result from

3921

** an application defined function to be a floating point value specified

3922

** by its 2nd argument.

3923

**

3924

** The sqlite3_result_error() and sqlite3_result_error16() functions

3925

** cause the implemented SQL function to throw an exception.

3926

** SQLite uses the string pointed to by the

3927

** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()

3928

** as the text of an error message. SQLite interprets the error

3929

** message string from sqlite3_result_error() as UTF8. SQLite

3930

** interprets the string from sqlite3_result_error16() as UTF16 in native

3931

** byte order. If the third parameter to sqlite3_result_error()

3932

** or sqlite3_result_error16() is negative then SQLite takes as the error

3933

** message all text up through the first zero character.

3934

** If the third parameter to sqlite3_result_error() or

3935

** sqlite3_result_error16() is non-negative then SQLite takes that many

3936

** bytes (not characters) from the 2nd parameter as the error message.

3937

** The sqlite3_result_error() and sqlite3_result_error16()

3938

** routines make a copy private copy of the error message text before

3939

** they return. Hence, the calling function can deallocate or

3940

** modify the text after they return without harm.

3941

** The sqlite3_result_error_code() function changes the error code

3942

** returned by SQLite as a result of an error in a function. By default,

3943

** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()

3944

** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.

3945

**

3946

** The sqlite3_result_toobig() interface causes SQLite

3947

** to throw an error indicating that a string or BLOB is to long

3948

** to represent. The sqlite3_result_nomem() interface

3949

** causes SQLite to throw an exception indicating that the a

3950

** memory allocation failed.

3951

**

3952

** The sqlite3_result_int() interface sets the return value

3953

** of the application-defined function to be the 32-bit signed integer

3954

** value given in the 2nd argument.

3955

** The sqlite3_result_int64() interface sets the return value

3956

** of the application-defined function to be the 64-bit signed integer

3957

** value given in the 2nd argument.

3958

**

3959

** The sqlite3_result_null() interface sets the return value

3960

** of the application-defined function to be NULL.

3961

**

3962

** The sqlite3_result_text(), sqlite3_result_text16(),

3963

** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces

3964

** set the return value of the application-defined function to be

3965

** a text string which is represented as UTF-8, UTF-16 native byte order,

3966

** UTF-16 little endian, or UTF-16 big endian, respectively.

3967

** SQLite takes the text result from the application from

3968

** the 2nd parameter of the sqlite3_result_text* interfaces.

3969

** If the 3rd parameter to the sqlite3_result_text* interfaces

3970

** is negative, then SQLite takes result text from the 2nd parameter

3971

** through the first zero character.

3972

** If the 3rd parameter to the sqlite3_result_text* interfaces

3973

** is non-negative, then as many bytes (not characters) of the text

3974

** pointed to by the 2nd parameter are taken as the application-defined

3975

** function result.

3976

** If the 4th parameter to the sqlite3_result_text* interfaces

3977

** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that

3978

** function as the destructor on the text or blob result when it has

3979

** finished using that result.

3980

** If the 4th parameter to the sqlite3_result_text* interfaces

3981

** or sqlite3_result_blob is the special constant SQLITE_STATIC, then

3982

** SQLite assumes that the text or blob result is constant space and

3983

** does not copy the space or call a destructor when it has

3984

** finished using that result.

3985

** If the 4th parameter to the sqlite3_result_text* interfaces

3986

** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT

3987

** then SQLite makes a copy of the result into space obtained from

3988

** from [sqlite3_malloc()] before it returns.

3989

**

3990

** The sqlite3_result_value() interface sets the result of

3991

** the application-defined function to be a copy the

3992

** [unprotected sqlite3_value] object specified by the 2nd parameter. The

3993

** sqlite3_result_value() interface makes a copy of the [sqlite3_value]

3994

** so that [sqlite3_value] specified in the parameter may change or

3995

** be deallocated after sqlite3_result_value() returns without harm.

3996

** A [protected sqlite3_value] object may always be used where an

3997

** [unprotected sqlite3_value] object is required, so either

3998

** kind of [sqlite3_value] object can be used with this interface.

3999

**

4000

** If these routines are called from within the different thread

4001

** than the one containing the application-defined function that recieved

4002

** the [sqlite3_context] pointer, the results are undefined.

4003

**

4004

** INVARIANTS:

4005

**

4006

** {F16403} The default return value from any SQL function is NULL.

4007

**

4008

** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the

4009

** return value of function C to be a blob that is N bytes

4010

** in length and with content pointed to by V.

4011

**

4012

** {F16409} The [sqlite3_result_double(C,V)] interface changes the

4013

** return value of function C to be the floating point value V.

4014

**

4015

** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return

4016

** value of function C to be an exception with error code

4017

** [SQLITE_ERROR] and a UTF8 error message copied from V up to the

4018

** first zero byte or until N bytes are read if N is positive.

4019

**

4020

** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return

4021

** value of function C to be an exception with error code

4022

** [SQLITE_ERROR] and a UTF16 native byte order error message

4023

** copied from V up to the first zero terminator or until N bytes

4024

** are read if N is positive.

4025

**

4026

** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return

4027

** value of the function C to be an exception with error code

4028

** [SQLITE_TOOBIG] and an appropriate error message.

4029

**

4030

** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return

4031

** value of the function C to be an exception with error code

4032

** [SQLITE_NOMEM] and an appropriate error message.

4033

**

4034

** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return

4035

** value of the function C to be an exception with error code E.

4036

** The error message text is unchanged.

4037

**

4038

** {F16427} The [sqlite3_result_int(C,V)] interface changes the

4039

** return value of function C to be the 32-bit integer value V.

4040

**

4041

** {F16430} The [sqlite3_result_int64(C,V)] interface changes the

4042

** return value of function C to be the 64-bit integer value V.

4043

**

4044

** {F16433} The [sqlite3_result_null(C)] interface changes the

4045

** return value of function C to be NULL.

4046

**

4047

** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the

4048

** return value of function C to be the UTF8 string

4049

** V up to the first zero if N is negative

4050

** or the first N bytes of V if N is non-negative.

4051

**

4052

** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the

4053

** return value of function C to be the UTF16 native byte order

4054

** string V up to the first zero if N is

4055

** negative or the first N bytes of V if N is non-negative.

4056

**

4057

** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the

4058

** return value of function C to be the UTF16 big-endian

4059

** string V up to the first zero if N is

4060

** is negative or the first N bytes or V if N is non-negative.

4061

**

4062

** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the

4063

** return value of function C to be the UTF16 little-endian

4064

** string V up to the first zero if N is

4065

** negative or the first N bytes of V if N is non-negative.

4066

**

4067

** {F16448} The [sqlite3_result_value(C,V)] interface changes the

4068

** return value of function C to be [unprotected sqlite3_value]

4069

** object V.

4070

**

4071

** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the

4072

** return value of function C to be an N-byte blob of all zeros.

4073

**

4074

** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]

4075

** interfaces make a copy of their error message strings before

4076

** returning.

4077

**

4078

** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],

4079

** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],

4080

** [sqlite3_result_text16be(C,V,N,D)], or

4081

** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]

4082

** then no destructor is ever called on the pointer V and SQLite

4083

** assumes that V is immutable.

4084

**

4085

** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],

4086

** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],

4087

** [sqlite3_result_text16be(C,V,N,D)], or

4088

** [sqlite3_result_text16le(C,V,N,D)] is the constant

4089

** [SQLITE_TRANSIENT] then the interfaces makes a copy of the

4090

** content of V and retains the copy.

4091

**

4092

** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],

4093

** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],

4094

** [sqlite3_result_text16be(C,V,N,D)], or

4095

** [sqlite3_result_text16le(C,V,N,D)] is some value other than

4096

** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then

4097

** SQLite will invoke the destructor D with V as its only argument

4098

** when it has finished with the V value.

4099

*/

4100

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));

4101

void sqlite3_result_double(sqlite3_context*, double);

4102

void sqlite3_result_error(sqlite3_context*, const char*, int);

4103

void sqlite3_result_error16(sqlite3_context*, const void*, int);

4104

void sqlite3_result_error_toobig(sqlite3_context*);

4105

void sqlite3_result_error_nomem(sqlite3_context*);

4106

void sqlite3_result_error_code(sqlite3_context*, int);

4107

void sqlite3_result_int(sqlite3_context*, int);

4108

void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);

4109

void sqlite3_result_null(sqlite3_context*);

4110

void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));

4111

void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));

4112

void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));

4113

void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));

4114

void sqlite3_result_value(sqlite3_context*, sqlite3_value*);

4115

void sqlite3_result_zeroblob(sqlite3_context*, int n);

4116

4117

/*

4118

** CAPI3REF: Define New Collating Sequences {F16600}

4119

**

4120

** These functions are used to add new collation sequences to the

4121

** [sqlite3*] handle specified as the first argument.

4122

**

4123

** The name of the new collation sequence is specified as a UTF-8 string

4124

** for sqlite3_create_collation() and sqlite3_create_collation_v2()

4125

** and a UTF-16 string for sqlite3_create_collation16(). In all cases

4126

** the name is passed as the second function argument.

4127

**

4128

** The third argument may be one of the constants [SQLITE_UTF8],

4129

** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied

4130

** routine expects to be passed pointers to strings encoded using UTF-8,

4131

** UTF-16 little-endian or UTF-16 big-endian respectively. The

4132

** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that

4133

** the routine expects pointers to 16-bit word aligned strings

4134

** of UTF16 in the native byte order of the host computer.

4135

**

4136

** A pointer to the user supplied routine must be passed as the fifth

4137

** argument. If it is NULL, this is the same as deleting the collation

4138

** sequence (so that SQLite cannot call it anymore).

4139

** Each time the application

4140

** supplied function is invoked, it is passed a copy of the void* passed as

4141

** the fourth argument to sqlite3_create_collation() or

4142

** sqlite3_create_collation16() as its first parameter.

4143

**

4144

** The remaining arguments to the application-supplied routine are two strings,

4145

** each represented by a (length, data) pair and encoded in the encoding

4146

** that was passed as the third argument when the collation sequence was

4147

** registered. {END} The application defined collation routine should

4148

** return negative, zero or positive if

4149

** the first string is less than, equal to, or greater than the second

4150

** string. i.e. (STRING1 - STRING2).

4151

**

4152

** The sqlite3_create_collation_v2() works like sqlite3_create_collation()

4153

** excapt that it takes an extra argument which is a destructor for

4154

** the collation. The destructor is called when the collation is

4155

** destroyed and is passed a copy of the fourth parameter void* pointer

4156

** of the sqlite3_create_collation_v2().

4157

** Collations are destroyed when

4158

** they are overridden by later calls to the collation creation functions

4159

** or when the [sqlite3*] database handle is closed using [sqlite3_close()].

4160

**

4161

** INVARIANTS:

4162

**

4163

** {F16603} A successful call to the

4164

** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface

4165

** registers function F as the comparison function used to

4166

** implement collation X on [database connection] B for

4167

** databases having encoding E.

4168

**

4169

** {F16604} SQLite understands the X parameter to

4170

** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated

4171

** UTF-8 string in which case is ignored for ASCII characters and

4172

** is significant for non-ASCII characters.

4173

**

4174

** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]

4175

** with the same values for B, X, and E, override prior values

4176

** of P, F, and D.

4177

**

4178

** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]

4179

** is not NULL then it is called with argument P when the

4180

** collating function is dropped by SQLite.

4181

**

4182

** {F16612} A collating function is dropped when it is overloaded.

4183

**

4184

** {F16615} A collating function is dropped when the database connection

4185

** is closed using [sqlite3_close()].

4186

**

4187

** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]

4188

** is passed through as the first parameter to the comparison

4189

** function F for all subsequent invocations of F.

4190

**

4191

** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly

4192

** the same as a call to [sqlite3_create_collation_v2()] with

4193

** the same parameters and a NULL destructor.

4194

**

4195

** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],

4196

** SQLite uses the comparison function F for all text comparison

4197

** operations on [database connection] B on text values that

4198

** use the collating sequence name X.

4199

**

4200

** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same

4201

** as [sqlite3_create_collation(B,X,E,P,F)] except that the

4202

** collation name X is understood as UTF-16 in native byte order

4203

** instead of UTF-8.

4204

**

4205

** {F16630} When multiple comparison functions are available for the same

4206

** collating sequence, SQLite chooses the one whose text encoding

4207

** requires the least amount of conversion from the default

4208

** text encoding of the database.

4209

*/

4210

int sqlite3_create_collation(

4211

sqlite3*,

4212

const char *zName,

4213

int eTextRep,

4214

void*,

4215

int(*xCompare)(void*,int,const void*,int,const void*)

4216

);

4217

int sqlite3_create_collation_v2(

4218

sqlite3*,

4219

const char *zName,

4220

int eTextRep,

4221

void*,

4222

int(*xCompare)(void*,int,const void*,int,const void*),

4223

void(*xDestroy)(void*)

4224

);

4225

int sqlite3_create_collation16(

4226

sqlite3*,

4227

const char *zName,

4228

int eTextRep,

4229

void*,

4230

int(*xCompare)(void*,int,const void*,int,const void*)

4231

);

4232

4233

/*

4234

** CAPI3REF: Collation Needed Callbacks {F16700}

4235

**

4236

** To avoid having to register all collation sequences before a database

4237

** can be used, a single callback function may be registered with the

4238

** database handle to be called whenever an undefined collation sequence is

4239

** required.

4240

**

4241

** If the function is registered using the sqlite3_collation_needed() API,

4242

** then it is passed the names of undefined collation sequences as strings

4243

** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names

4244

** are passed as UTF-16 in machine native byte order. A call to either

4245

** function replaces any existing callback.

4246

**

4247

** When the callback is invoked, the first argument passed is a copy

4248

** of the second argument to sqlite3_collation_needed() or

4249

** sqlite3_collation_needed16(). The second argument is the database

4250

** handle. The third argument is one of [SQLITE_UTF8],

4251

** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most

4252

** desirable form of the collation sequence function required.

4253

** The fourth parameter is the name of the

4254

** required collation sequence.

4255

**

4256

** The callback function should register the desired collation using

4257

** [sqlite3_create_collation()], [sqlite3_create_collation16()], or

4258

** [sqlite3_create_collation_v2()].

4259

**

4260

** INVARIANTS:

4261

**

4262

** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)]

4263

** or [sqlite3_collation_needed16(D,P,F)] causes

4264

** the [database connection] D to invoke callback F with first

4265

** parameter P whenever it needs a comparison function for a

4266

** collating sequence that it does not know about.

4267

**

4268

** {F16704} Each successful call to [sqlite3_collation_needed()] or

4269

** [sqlite3_collation_needed16()] overrides the callback registered

4270

** on the same [database connection] by prior calls to either

4271

** interface.

4272

**

4273

** {F16706} The name of the requested collating function passed in the

4274

** 4th parameter to the callback is in UTF-8 if the callback

4275

** was registered using [sqlite3_collation_needed()] and

4276

** is in UTF-16 native byte order if the callback was

4277

** registered using [sqlite3_collation_needed16()].

4278

**

4279

**

4280

*/

4281

int sqlite3_collation_needed(

4282

sqlite3*,

4283

void*,

4284

void(*)(void*,sqlite3*,int eTextRep,const char*)

4285

);

4286

int sqlite3_collation_needed16(

4287

sqlite3*,

4288

void*,

4289

void(*)(void*,sqlite3*,int eTextRep,const void*)

4290

);

4291

4292

/*

4293

** Specify the key for an encrypted database. This routine should be

4294

** called right after sqlite3_open().

4295

**

4296

** The code to implement this API is not available in the public release

4297

** of SQLite.

4298

*/

4299

int sqlite3_key(

4300

sqlite3 *db, /* Database to be rekeyed */

4301

const void *pKey, int nKey /* The key */

4302

);

4303

4304

/*

4305

** Change the key on an open database. If the current database is not

4306

** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the

4307

** database is decrypted.

4308

**

4309

** The code to implement this API is not available in the public release

4310

** of SQLite.

4311

*/

4312

int sqlite3_rekey(

4313

sqlite3 *db, /* Database to be rekeyed */

4314

const void *pKey, int nKey /* The new key */

4315

);

4316

4317

/*

4318

** CAPI3REF: Suspend Execution For A Short Time {F10530}

4319

**

4320

** The sqlite3_sleep() function

4321

** causes the current thread to suspend execution

4322

** for at least a number of milliseconds specified in its parameter.

4323

**

4324

** If the operating system does not support sleep requests with

4325

** millisecond time resolution, then the time will be rounded up to

4326

** the nearest second. The number of milliseconds of sleep actually

4327

** requested from the operating system is returned.

4328

**

4329

** SQLite implements this interface by calling the xSleep()

4330

** method of the default [sqlite3_vfs] object.

4331

**

4332

** INVARIANTS:

4333

**

4334

** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep

4335

** method of the default [sqlite3_vfs|VFS] in order to

4336

** suspend execution of the current thread for at least

4337

** M milliseconds.

4338

**

4339

** {F10536} The [sqlite3_sleep(M)] interface returns the number of

4340

** milliseconds of sleep actually requested of the operating

4341

** system, which might be larger than the parameter M.

4342

*/

4343

int sqlite3_sleep(int);

4344

4345

/*

4346

** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}

4347

**

4348

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

4349

** the name of a folder (a.ka. directory), then all temporary files

4350

** created by SQLite will be placed in that directory. If this variable

4351

** is NULL pointer, then SQLite does a search for an appropriate temporary

4352

** file directory.

4353

**

4354

** It is not safe to modify this variable once a database connection

4355

** has been opened. It is intended that this variable be set once

4356

** as part of process initialization and before any SQLite interface

4357

** routines have been call and remain unchanged thereafter.

4358

*/

4359

SQLITE_EXTERN char *sqlite3_temp_directory;

4360

4361

/*

4362

** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930}

4363

**

4364

** The sqlite3_get_autocommit() interfaces returns non-zero or

4365

** zero if the given database connection is or is not in autocommit mode,

4366

** respectively. Autocommit mode is on

4367

** by default. Autocommit mode is disabled by a [BEGIN] statement.

4368

** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].

4369

**

4370

** If certain kinds of errors occur on a statement within a multi-statement

4371

** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],

4372

** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the

4373

** transaction might be rolled back automatically. The only way to

4374

** find out if SQLite automatically rolled back the transaction after

4375

** an error is to use this function.

4376

**

4377

** INVARIANTS:

4378

**

4379

** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or

4380

** zero if the [database connection] D is or is not in autocommit

4381

** mode, respectively.

4382

**

4383

** {F12932} Autocommit mode is on by default.

4384

**

4385

** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.

4386

**

4387

** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]

4388

** statement.

4389

**

4390

**

4391

** LIMITATIONS:

4392

***

4393

** {U12936} If another thread changes the autocommit status of the database

4394

** connection while this routine is running, then the return value

4395

** is undefined.

4396

*/

4397

int sqlite3_get_autocommit(sqlite3*);

4398

4399

/*

4400

** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}

4401

**

4402

** The sqlite3_db_handle interface

4403

** returns the [sqlite3*] database handle to which a

4404

** [prepared statement] belongs.

4405

** The database handle returned by sqlite3_db_handle

4406

** is the same database handle that was

4407

** the first argument to the [sqlite3_prepare_v2()] or its variants

4408

** that was used to create the statement in the first place.

4409

**

4410

** INVARIANTS:

4411

**

4412

** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer

4413

** to the [database connection] associated with

4414

** [prepared statement] S.

4415

*/

4416

sqlite3 *sqlite3_db_handle(sqlite3_stmt*);

4417

4418

4419

/*

4420

** CAPI3REF: Commit And Rollback Notification Callbacks {F12950}

4421

**

4422

** The sqlite3_commit_hook() interface registers a callback

4423

** function to be invoked whenever a transaction is committed.

4424

** Any callback set by a previous call to sqlite3_commit_hook()

4425

** for the same database connection is overridden.

4426

** The sqlite3_rollback_hook() interface registers a callback

4427

** function to be invoked whenever a transaction is committed.

4428

** Any callback set by a previous call to sqlite3_commit_hook()

4429

** for the same database connection is overridden.

4430

** The pArg argument is passed through

4431

** to the callback. If the callback on a commit hook function

4432

** returns non-zero, then the commit is converted into a rollback.

4433

**

4434

** If another function was previously registered, its

4435

** pArg value is returned. Otherwise NULL is returned.

4436

**

4437

** Registering a NULL function disables the callback.

4438

**

4439

** For the purposes of this API, a transaction is said to have been

4440

** rolled back if an explicit "ROLLBACK" statement is executed, or

4441

** an error or constraint causes an implicit rollback to occur.

4442

** The rollback callback is not invoked if a transaction is

4443

** automatically rolled back because the database connection is closed.

4444

** The rollback callback is not invoked if a transaction is

4445

** rolled back because a commit callback returned non-zero.

4446

** <todo> Check on this </todo>

4447

**

4448

** These are experimental interfaces and are subject to change.

4449

**

4450

** INVARIANTS:

4451

**

4452

** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the

4453

** callback function F to be invoked with argument P whenever

4454

** a transaction commits on [database connection] D.

4455

**

4456

** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P

4457

** argument from the previous call with the same

4458

** [database connection ] D , or NULL on the first call

4459

** for a particular [database connection] D.

4460

**

4461

** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback

4462

** registered by prior calls.

4463

**

4464

** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL

4465

** then the commit hook callback is cancelled and no callback

4466

** is invoked when a transaction commits.

4467

**

4468

** {F12955} If the commit callback returns non-zero then the commit is

4469

** converted into a rollback.

4470

**

4471

** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the

4472

** callback function F to be invoked with argument P whenever

4473

** a transaction rolls back on [database connection] D.

4474

**

4475

** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P

4476

** argument from the previous call with the same

4477

** [database connection ] D , or NULL on the first call

4478

** for a particular [database connection] D.

4479

**

4480

** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback

4481

** registered by prior calls.

4482

**

4483

** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL

4484

** then the rollback hook callback is cancelled and no callback

4485

** is invoked when a transaction rolls back.

4486

*/

4487

void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);

4488

void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);

4489

4490

/*

4491

** CAPI3REF: Data Change Notification Callbacks {F12970}

4492

**

4493

** The sqlite3_update_hook() interface

4494

** registers a callback function with the database connection identified by the

4495

** first argument to be invoked whenever a row is updated, inserted or deleted.

4496

** Any callback set by a previous call to this function for the same

4497

** database connection is overridden.

4498

**

4499

** The second argument is a pointer to the function to invoke when a

4500

** row is updated, inserted or deleted.

4501

** The first argument to the callback is

4502

** a copy of the third argument to sqlite3_update_hook().

4503

** The second callback

4504

** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],

4505

** depending on the operation that caused the callback to be invoked.

4506

** The third and

4507

** fourth arguments to the callback contain pointers to the database and

4508

** table name containing the affected row.

4509

** The final callback parameter is

4510

** the rowid of the row.

4511

** In the case of an update, this is the rowid after

4512

** the update takes place.

4513

**

4514

** The update hook is not invoked when internal system tables are

4515

** modified (i.e. sqlite_master and sqlite_sequence).

4516

**

4517

** If another function was previously registered, its pArg value

4518

** is returned. Otherwise NULL is returned.

4519

**

4520

** INVARIANTS:

4521

**

4522

** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback

4523

** function F to be invoked with first parameter P whenever

4524

** a table row is modified, inserted, or deleted on

4525

** [database connection] D.

4526

**

4527

** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value

4528

** of P for the previous call on the same [database connection] D,

4529

** or NULL for the first call.

4530

**

4531

** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]

4532

** is NULL then the no update callbacks are made.

4533

**

4534

** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls

4535

** to the same interface on the same [database connection] D.

4536

**

4537

** {F12979} The update hook callback is not invoked when internal system

4538

** tables such as sqlite_master and sqlite_sequence are modified.

4539

**

4540

** {F12981} The second parameter to the update callback

4541

** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],

4542

** depending on the operation that caused the callback to be invoked.

4543

**

4544

** {F12983} The third and fourth arguments to the callback contain pointers

4545

** to zero-terminated UTF-8 strings which are the names of the

4546

** database and table that is being updated.

4547

4548

** {F12985} The final callback parameter is the rowid of the row after

4549

** the change occurs.

4550

*/

4551

void *sqlite3_update_hook(

4552

sqlite3*,

4553

void(*)(void *,int ,char const *,char const *,sqlite3_int64),

4554

void*

4555

);

4556

4557

/*

4558

** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}

4559

**

4560

** This routine enables or disables the sharing of the database cache

4561

** and schema data structures between connections to the same database.

4562

** Sharing is enabled if the argument is true and disabled if the argument

4563

** is false.

4564

**

4565

** Cache sharing is enabled and disabled

4566

** for an entire process. {END} This is a change as of SQLite version 3.5.0.

4567

** In prior versions of SQLite, sharing was

4568

** enabled or disabled for each thread separately.

4569

**

4570

** The cache sharing mode set by this interface effects all subsequent

4571

** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].

4572

** Existing database connections continue use the sharing mode

4573

** that was in effect at the time they were opened.

4574

**

4575

** Virtual tables cannot be used with a shared cache. When shared

4576

** cache is enabled, the [sqlite3_create_module()] API used to register

4577

** virtual tables will always return an error.

4578

**

4579

** This routine returns [SQLITE_OK] if shared cache was

4580

** enabled or disabled successfully. An [error code]

4581

** is returned otherwise.

4582

**

4583

** Shared cache is disabled by default. But this might change in

4584

** future releases of SQLite. Applications that care about shared

4585

** cache setting should set it explicitly.

4586

**

4587

** INVARIANTS:

4588

**

4589

** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)]

4590

** will enable or disable shared cache mode for any subsequently

4591

** created [database connection] in the same process.

4592

**

4593

** {F10336} When shared cache is enabled, the [sqlite3_create_module()]

4594

** interface will always return an error.

4595

**

4596

** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns

4597

** [SQLITE_OK] if shared cache was enabled or disabled successfully.

4598

**

4599

** {F10339} Shared cache is disabled by default.

4600

*/

4601

int sqlite3_enable_shared_cache(int);

4602

4603

/*

4604

** CAPI3REF: Attempt To Free Heap Memory {F17340}

4605

**

4606

** The sqlite3_release_memory() interface attempts to

4607

** free N bytes of heap memory by deallocating non-essential memory

4608

** allocations held by the database labrary. {END} Memory used

4609

** to cache database pages to improve performance is an example of

4610

** non-essential memory. Sqlite3_release_memory() returns

4611

** the number of bytes actually freed, which might be more or less

4612

** than the amount requested.

4613

**

4614

** INVARIANTS:

4615

**

4616

** {F17341} The [sqlite3_release_memory(N)] interface attempts to

4617

** free N bytes of heap memory by deallocating non-essential

4618

** memory allocations held by the database labrary.

4619

**

4620

** {F16342} The [sqlite3_release_memory(N)] returns the number

4621

** of bytes actually freed, which might be more or less

4622

** than the amount requested.

4623

*/

4624

int sqlite3_release_memory(int);

4625

4626

/*

4627

** CAPI3REF: Impose A Limit On Heap Size {F17350}

4628

**

4629

** The sqlite3_soft_heap_limit() interface

4630

** places a "soft" limit on the amount of heap memory that may be allocated

4631

** by SQLite. If an internal allocation is requested

4632

** that would exceed the soft heap limit, [sqlite3_release_memory()] is

4633

** invoked one or more times to free up some space before the allocation

4634

** is made.

4635

**

4636

** The limit is called "soft", because if

4637

** [sqlite3_release_memory()] cannot

4638

** free sufficient memory to prevent the limit from being exceeded,

4639

** the memory is allocated anyway and the current operation proceeds.

4640

**

4641

** A negative or zero value for N means that there is no soft heap limit and

4642

** [sqlite3_release_memory()] will only be called when memory is exhausted.

4643

** The default value for the soft heap limit is zero.

4644

**

4645

** SQLite makes a best effort to honor the soft heap limit.

4646

** But if the soft heap limit cannot honored, execution will

4647

** continue without error or notification. This is why the limit is

4648

** called a "soft" limit. It is advisory only.

4649

**

4650

** Prior to SQLite version 3.5.0, this routine only constrained the memory

4651

** allocated by a single thread - the same thread in which this routine

4652

** runs. Beginning with SQLite version 3.5.0, the soft heap limit is

4653

** applied to all threads. The value specified for the soft heap limit

4654

** is an upper bound on the total memory allocation for all threads. In

4655

** version 3.5.0 there is no mechanism for limiting the heap usage for

4656

** individual threads.

4657

**

4658

** INVARIANTS:

4659

**

4660

** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit

4661

** of N bytes on the amount of heap memory that may be allocated

4662

** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point

4663

** in time.

4664

**

4665

** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would

4666

** cause the total amount of allocated memory to exceed the

4667

** soft heap limit, then [sqlite3_release_memory()] is invoked

4668

** in an attempt to reduce the memory usage prior to proceeding

4669

** with the memory allocation attempt.

4670

**

4671

** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger

4672

** attempts to reduce memory usage through the soft heap limit

4673

** mechanism continue even if the attempt to reduce memory

4674

** usage is unsuccessful.

4675

**

4676

** {F16354} A negative or zero value for N in a call to

4677

** [sqlite3_soft_heap_limit(N)] means that there is no soft

4678

** heap limit and [sqlite3_release_memory()] will only be

4679

** called when memory is completely exhausted.

4680

**

4681

** {F16355} The default value for the soft heap limit is zero.

4682

**

4683

** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the

4684

** values set by all prior calls.

4685

*/

4686

void sqlite3_soft_heap_limit(int);

4687

4688

/*

4689

** CAPI3REF: Extract Metadata About A Column Of A Table {F12850}

4690

**

4691

** This routine

4692

** returns meta-data about a specific column of a specific database

4693

** table accessible using the connection handle passed as the first function

4694

** argument.

4695

**

4696

** The column is identified by the second, third and fourth parameters to

4697

** this function. The second parameter is either the name of the database

4698

** (i.e. "main", "temp" or an attached database) containing the specified

4699

** table or NULL. If it is NULL, then all attached databases are searched

4700

** for the table using the same algorithm as the database engine uses to

4701

** resolve unqualified table references.

4702

**

4703

** The third and fourth parameters to this function are the table and column

4704

** name of the desired column, respectively. Neither of these parameters

4705

** may be NULL.

4706

**

4707

** Meta information is returned by writing to the memory locations passed as

4708

** the 5th and subsequent parameters to this function. Any of these

4709

** arguments may be NULL, in which case the corresponding element of meta

4710

** information is ommitted.

4711

**

4712

** <pre>

4713

** Parameter Output Type Description

4714

** -----------------------------------

4715

**

4716

** 5th const char* Data type

4717

** 6th const char* Name of the default collation sequence

4718

** 7th int True if the column has a NOT NULL constraint

4719

** 8th int True if the column is part of the PRIMARY KEY

4720

** 9th int True if the column is AUTOINCREMENT

4721

** </pre>

4722

**

4723

**

4724

** The memory pointed to by the character pointers returned for the

4725

** declaration type and collation sequence is valid only until the next

4726

** call to any sqlite API function.

4727

**

4728

** If the specified table is actually a view, then an error is returned.

4729

**

4730

** If the specified column is "rowid", "oid" or "_rowid_" and an

4731

** INTEGER PRIMARY KEY column has been explicitly declared, then the output

4732

** parameters are set for the explicitly declared column. If there is no

4733

** explicitly declared IPK column, then the output parameters are set as

4734

** follows:

4735

**

4736

** <pre>

4737

** data type: "INTEGER"

4738

** collation sequence: "BINARY"

4739

** not null: 0

4740

** primary key: 1

4741

** auto increment: 0

4742

** </pre>

4743

**

4744

** This function may load one or more schemas from database files. If an

4745

** error occurs during this process, or if the requested table or column

4746

** cannot be found, an SQLITE error code is returned and an error message

4747

** left in the database handle (to be retrieved using sqlite3_errmsg()).

4748

**

4749

** This API is only available if the library was compiled with the

4750

** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.

4751

*/

4752

int sqlite3_table_column_metadata(

4753

sqlite3 *db, /* Connection handle */

4754

const char *zDbName, /* Database name or NULL */

4755

const char *zTableName, /* Table name */

4756

const char *zColumnName, /* Column name */

4757

char const **pzDataType, /* OUTPUT: Declared data type */

4758

char const **pzCollSeq, /* OUTPUT: Collation sequence name */

4759

int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */

4760

int *pPrimaryKey, /* OUTPUT: True if column part of PK */

4761

int *pAutoinc /* OUTPUT: True if column is auto-increment */

4762

);

4763

4764

/*

4765

** CAPI3REF: Load An Extension {F12600}

4766

**

4767

** {F12601} The sqlite3_load_extension() interface

4768

** attempts to load an SQLite extension library contained in the file

4769

** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0

4770

** in which case the name of the entry point defaults

4771

** to "sqlite3_extension_init".

4772

**

4773

** {F12604} The sqlite3_load_extension() interface shall

4774

** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.

4775

**

4776

** {F12605}

4777

** If an error occurs and pzErrMsg is not 0, then the

4778

** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with

4779

** error message text stored in memory obtained from [sqlite3_malloc()].

4780

** {END} The calling function should free this memory

4781

** by calling [sqlite3_free()].

4782

**

4783

** {F12606}

4784

** Extension loading must be enabled using [sqlite3_enable_load_extension()]

4785

** prior to calling this API or an error will be returned.

4786

*/

4787

int sqlite3_load_extension(

4788

sqlite3 *db, /* Load the extension into this database connection */

4789

const char *zFile, /* Name of the shared library containing extension */

4790

const char *zProc, /* Entry point. Derived from zFile if 0 */

4791

char **pzErrMsg /* Put error message here if not 0 */

4792

);

4793

4794

/*

4795

** CAPI3REF: Enable Or Disable Extension Loading {F12620}

4796

**

4797

** So as not to open security holes in older applications that are

4798

** unprepared to deal with extension loading, and as a means of disabling

4799

** extension loading while evaluating user-entered SQL, the following

4800

** API is provided to turn the [sqlite3_load_extension()] mechanism on and

4801

** off. {F12622} It is off by default. {END} See ticket #1863.

4802

**

4803

** {F12621} Call the sqlite3_enable_load_extension() routine

4804

** with onoff==1 to turn extension loading on

4805

** and call it with onoff==0 to turn it back off again. {END}

4806

*/

4807

int sqlite3_enable_load_extension(sqlite3 *db, int onoff);

4808

4809

/*

4810

** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640}

4811

**

4812

** {F12641} This function

4813

** registers an extension entry point that is automatically invoked

4814

** whenever a new database connection is opened using

4815

** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END}

4816

**

4817

** This API can be invoked at program startup in order to register

4818

** one or more statically linked extensions that will be available

4819

** to all new database connections.

4820

**

4821

** {F12642} Duplicate extensions are detected so calling this routine multiple

4822

** times with the same extension is harmless.

4823

**

4824

** {F12643} This routine stores a pointer to the extension in an array

4825

** that is obtained from sqlite_malloc(). {END} If you run a memory leak

4826

** checker on your program and it reports a leak because of this

4827

** array, then invoke [sqlite3_reset_auto_extension()] prior

4828

** to shutdown to free the memory.

4829

**

4830

** {F12644} Automatic extensions apply across all threads. {END}

4831

**

4832

** This interface is experimental and is subject to change or

4833

** removal in future releases of SQLite.

4834

*/

4835

int sqlite3_auto_extension(void *xEntryPoint);

4836

4837

4838

/*

4839

** CAPI3REF: Reset Automatic Extension Loading {F12660}

4840

**

4841

** {F12661} This function disables all previously registered

4842

** automatic extensions. {END} This

4843

** routine undoes the effect of all prior [sqlite3_auto_extension()]

4844

** calls.

4845

**

4846

** {F12662} This call disabled automatic extensions in all threads. {END}

4847

**

4848

** This interface is experimental and is subject to change or

4849

** removal in future releases of SQLite.

4850

*/

4851

void sqlite3_reset_auto_extension(void);

4852

4853

4854

/*

4855

****** EXPERIMENTAL - subject to change without notice **************

4856

**

4857

** The interface to the virtual-table mechanism is currently considered

4858

** to be experimental. The interface might change in incompatible ways.

4859

** If this is a problem for you, do not use the interface at this time.

4860

**

4861

** When the virtual-table mechanism stablizes, we will declare the

4862

** interface fixed, support it indefinitely, and remove this comment.

4863

*/

4864

4865

/*

4866

** Structures used by the virtual table interface

4867

*/

4868

typedef struct sqlite3_vtab sqlite3_vtab;

4869

typedef struct sqlite3_index_info sqlite3_index_info;

4870

typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;

4871

typedef struct sqlite3_module sqlite3_module;

4872

4873

/*

4874

** CAPI3REF: Virtual Table Object {F18000}

4875

** KEYWORDS: sqlite3_module

4876

**

4877

** A module is a class of virtual tables. Each module is defined

4878

** by an instance of the following structure. This structure consists

4879

** mostly of methods for the module.

4880

*/

4881

struct sqlite3_module {

4882

int iVersion;

4883

int (*xCreate)(sqlite3*, void *pAux,

4884

int argc, const char *const*argv,

4885

sqlite3_vtab **ppVTab, char**);

4886

int (*xConnect)(sqlite3*, void *pAux,

4887

int argc, const char *const*argv,

4888

sqlite3_vtab **ppVTab, char**);

4889

int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);

4890

int (*xDisconnect)(sqlite3_vtab *pVTab);

4891

int (*xDestroy)(sqlite3_vtab *pVTab);

4892

int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);

4893

int (*xClose)(sqlite3_vtab_cursor*);

4894

int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,

4895

int argc, sqlite3_value **argv);

4896

int (*xNext)(sqlite3_vtab_cursor*);

4897

int (*xEof)(sqlite3_vtab_cursor*);

4898

int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);

4899

int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);

4900

int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);

4901

int (*xBegin)(sqlite3_vtab *pVTab);

4902

int (*xSync)(sqlite3_vtab *pVTab);

4903

int (*xCommit)(sqlite3_vtab *pVTab);

4904

int (*xRollback)(sqlite3_vtab *pVTab);

4905

int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,

4906

void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),

4907

void **ppArg);

4908

4909

int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);

4910

};

4911

4912

/*

4913

** CAPI3REF: Virtual Table Indexing Information {F18100}

4914

** KEYWORDS: sqlite3_index_info

4915

**

4916

** The sqlite3_index_info structure and its substructures is used to

4917

** pass information into and receive the reply from the xBestIndex

4918

** method of an sqlite3_module. The fields under **Inputs** are the

4919

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

4920

** results into the **Outputs** fields.

4921

**

4922

** The aConstraint[] array records WHERE clause constraints of the

4923

** form:

4924

**

4925

** column OP expr

4926

**

4927

** Where OP is =, <, <=, >, or >=.

4928

** The particular operator is stored

4929

** in aConstraint[].op. The index of the column is stored in

4930

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

4931

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

4932

** is usable) and false if it cannot.

4933

**

4934

** The optimizer automatically inverts terms of the form "expr OP column"

4935

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

4936

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

4937

** The aConstraint[] array only reports WHERE clause terms in the correct

4938

** form that refer to the particular virtual table being queried.

4939

**

4940

** Information about the ORDER BY clause is stored in aOrderBy[].

4941

** Each term of aOrderBy records a column of the ORDER BY clause.

4942

**

4943

** The xBestIndex method must fill aConstraintUsage[] with information

4944

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

4945

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

4946

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

4947

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

4948

** virtual table and is not checked again by SQLite.

4949

**

4950

** The idxNum and idxPtr values are recorded and passed into xFilter.

4951

** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.

4952

**

4953

** The orderByConsumed means that output from xFilter will occur in

4954

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

4955

** sorting step is required.

4956

**

4957

** The estimatedCost value is an estimate of the cost of doing the

4958

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

4959

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

4960

** cost of approximately log(N).

4961

*/

4962

struct sqlite3_index_info {

4963

/* Inputs */

4964

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

4965

struct sqlite3_index_constraint {

4966

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

4967

unsigned char op; /* Constraint operator */

4968

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

4969

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

4970

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

4971

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

4972

struct sqlite3_index_orderby {

4973

int iColumn; /* Column number */

4974

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

4975

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

4976

4977

/* Outputs */

4978

struct sqlite3_index_constraint_usage {

4979

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

4980

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

4981

} *aConstraintUsage;

4982

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

4983

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

4984

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

4985

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

4986

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

4987

};

4988

#define SQLITE_INDEX_CONSTRAINT_EQ 2

4989

#define SQLITE_INDEX_CONSTRAINT_GT 4

4990

#define SQLITE_INDEX_CONSTRAINT_LE 8

4991

#define SQLITE_INDEX_CONSTRAINT_LT 16

4992

#define SQLITE_INDEX_CONSTRAINT_GE 32

4993

#define SQLITE_INDEX_CONSTRAINT_MATCH 64

4994

4995

/*

4996

** CAPI3REF: Register A Virtual Table Implementation {F18200}

4997

**

4998

** This routine is used to register a new module name with an SQLite

4999

** connection. Module names must be registered before creating new

5000

** virtual tables on the module, or before using preexisting virtual

5001

** tables of the module.

5002

*/

5003

int sqlite3_create_module(

5004

sqlite3 *db, /* SQLite connection to register module with */

5005

const char *zName, /* Name of the module */

5006

const sqlite3_module *, /* Methods for the module */

5007

void * /* Client data for xCreate/xConnect */

5008

);

5009

5010

/*

5011

** CAPI3REF: Register A Virtual Table Implementation {F18210}

5012

**

5013

** This routine is identical to the sqlite3_create_module() method above,

5014

** except that it allows a destructor function to be specified. It is

5015

** even more experimental than the rest of the virtual tables API.

5016

*/

5017

int sqlite3_create_module_v2(

5018

sqlite3 *db, /* SQLite connection to register module with */

5019

const char *zName, /* Name of the module */

5020

const sqlite3_module *, /* Methods for the module */

5021

void *, /* Client data for xCreate/xConnect */

5022

void(*xDestroy)(void*) /* Module destructor function */

5023

);

5024

5025

/*

5026

** CAPI3REF: Virtual Table Instance Object {F18010}

5027

** KEYWORDS: sqlite3_vtab

5028

**

5029

** Every module implementation uses a subclass of the following structure

5030

** to describe a particular instance of the module. Each subclass will

5031

** be tailored to the specific needs of the module implementation. The

5032

** purpose of this superclass is to define certain fields that are common

5033

** to all module implementations.

5034

**

5035

** Virtual tables methods can set an error message by assigning a

5036

** string obtained from sqlite3_mprintf() to zErrMsg. The method should

5037

** take care that any prior string is freed by a call to sqlite3_free()

5038

** prior to assigning a new string to zErrMsg. After the error message

5039

** is delivered up to the client application, the string will be automatically

5040

** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note

5041

** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field

5042

** since virtual tables are commonly implemented in loadable extensions which

5043

** do not have access to sqlite3MPrintf() or sqlite3Free().

5044

*/

5045

struct sqlite3_vtab {

5046

const sqlite3_module *pModule; /* The module for this virtual table */

5047

int nRef; /* Used internally */

5048

char *zErrMsg; /* Error message from sqlite3_mprintf() */

5049

/* Virtual table implementations will typically add additional fields */

5050

};

5051

5052

/*

5053

** CAPI3REF: Virtual Table Cursor Object {F18020}

5054

** KEYWORDS: sqlite3_vtab_cursor

5055

**

5056

** Every module implementation uses a subclass of the following structure

5057

** to describe cursors that point into the virtual table and are used

5058

** to loop through the virtual table. Cursors are created using the

5059

** xOpen method of the module. Each module implementation will define

5060

** the content of a cursor structure to suit its own needs.

5061

**

5062

** This superclass exists in order to define fields of the cursor that

5063

** are common to all implementations.

5064

*/

5065

struct sqlite3_vtab_cursor {

5066

sqlite3_vtab *pVtab; /* Virtual table of this cursor */

5067

/* Virtual table implementations will typically add additional fields */

5068

};

5069

5070

/*

5071

** CAPI3REF: Declare The Schema Of A Virtual Table {F18280}

5072

**

5073

** The xCreate and xConnect methods of a module use the following API

5074

** to declare the format (the names and datatypes of the columns) of

5075

** the virtual tables they implement.

5076

*/

5077

int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);

5078

5079

/*

5080

** CAPI3REF: Overload A Function For A Virtual Table {F18300}

5081

**

5082

** Virtual tables can provide alternative implementations of functions

5083

** using the xFindFunction method. But global versions of those functions

5084

** must exist in order to be overloaded.

5085

**

5086

** This API makes sure a global version of a function with a particular

5087

** name and number of parameters exists. If no such function exists

5088

** before this API is called, a new function is created. The implementation

5089

** of the new function always causes an exception to be thrown. So

5090

** the new function is not good for anything by itself. Its only

5091

** purpose is to be a place-holder function that can be overloaded

5092

** by virtual tables.

5093

**

5094

** This API should be considered part of the virtual table interface,

5095

** which is experimental and subject to change.

5096

*/

5097

int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);

5098

5099

/*

5100

** The interface to the virtual-table mechanism defined above (back up

5101

** to a comment remarkably similar to this one) is currently considered

5102

** to be experimental. The interface might change in incompatible ways.

5103

** If this is a problem for you, do not use the interface at this time.

5104

**

5105

** When the virtual-table mechanism stabilizes, we will declare the

5106

** interface fixed, support it indefinitely, and remove this comment.

5107

**

5108

****** EXPERIMENTAL - subject to change without notice **************

5109

*/

5110

5111

/*

5112

** CAPI3REF: A Handle To An Open BLOB {F17800}

5113

**

5114

** An instance of this object represents an open BLOB on which

5115

** incremental I/O can be preformed.

5116

** Objects of this type are created by

5117

** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].

5118

** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces

5119

** can be used to read or write small subsections of the blob.

5120

** The [sqlite3_blob_bytes()] interface returns the size of the

5121

** blob in bytes.

5122

*/

5123

typedef struct sqlite3_blob sqlite3_blob;

5124

5125

/*

5126

** CAPI3REF: Open A BLOB For Incremental I/O {F17810}

5127

**

5128

** This interfaces opens a handle to the blob located

5129

** in row iRow, column zColumn, table zTable in database zDb;

5130

** in other words, the same blob that would be selected by:

5131

**

5132

** <pre>

5133

** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

5134

** </pre> {END}

5135

**

5136

** If the flags parameter is non-zero, the blob is opened for

5137

** read and write access. If it is zero, the blob is opened for read

5138

** access.

5139

**

5140

** Note that the database name is not the filename that contains

5141

** the database but rather the symbolic name of the database that

5142

** is assigned when the database is connected using [ATTACH].

5143

** For the main database file, the database name is "main". For

5144

** TEMP tables, the database name is "temp".

5145

**

5146

** On success, [SQLITE_OK] is returned and the new

5147

** [sqlite3_blob | blob handle] is written to *ppBlob.

5148

** Otherwise an error code is returned and

5149

** any value written to *ppBlob should not be used by the caller.

5150

** This function sets the database-handle error code and message

5151

** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].

5152

**

5153

** INVARIANTS:

5154

**

5155

** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]

5156

** interface opens an [sqlite3_blob] object P on the blob

5157

** in column C of table T in database B on [database connection] D.

5158

**

5159

** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts

5160

** a new transaction on [database connection] D if that connection

5161

** is not already in a transaction.

5162

**

5163

** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob

5164

** for read and write access if and only if the F parameter

5165

** is non-zero.

5166

**

5167

** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on

5168

** success and an appropriate [error code] on failure.

5169

**

5170

** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]

5171

** then subsequent calls to [sqlite3_errcode(D)],

5172

** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return

5173

** information approprate for that error.

5174

*/

5175

int sqlite3_blob_open(

5176

sqlite3*,

5177

const char *zDb,

5178

const char *zTable,

5179

const char *zColumn,

5180

sqlite3_int64 iRow,

5181

int flags,

5182

sqlite3_blob **ppBlob

5183

);

5184

5185

/*

5186

** CAPI3REF: Close A BLOB Handle {F17830}

5187

**

5188

** Close an open [sqlite3_blob | blob handle].

5189

**

5190

** Closing a BLOB shall cause the current transaction to commit

5191

** if there are no other BLOBs, no pending prepared statements, and the

5192

** database connection is in autocommit mode.

5193

** If any writes were made to the BLOB, they might be held in cache

5194

** until the close operation if they will fit. {END}

5195

** Closing the BLOB often forces the changes

5196

** out to disk and so if any I/O errors occur, they will likely occur

5197

** at the time when the BLOB is closed. {F17833} Any errors that occur during

5198

** closing are reported as a non-zero return value.

5199

**

5200

** The BLOB is closed unconditionally. Even if this routine returns

5201

** an error code, the BLOB is still closed.

5202

**

5203

** INVARIANTS:

5204

**

5205

** {F17833} The [sqlite3_blob_close(P)] interface closes an

5206

** [sqlite3_blob] object P previously opened using

5207

** [sqlite3_blob_open()].

5208

**

5209

** {F17836} Closing an [sqlite3_blob] object using

5210

** [sqlite3_blob_close()] shall cause the current transaction to

5211

** commit if there are no other open [sqlite3_blob] objects

5212

** or [prepared statements] on the same [database connection] and

5213

** the [database connection] is in

5214

** [sqlite3_get_autocommit | autocommit mode].

5215

**

5216

** {F17839} The [sqlite3_blob_close(P)] interfaces closes the

5217

** [sqlite3_blob] object P unconditionally, even if

5218

** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].

5219

**

5220

*/

5221

int sqlite3_blob_close(sqlite3_blob *);

5222

5223

/*

5224

** CAPI3REF: Return The Size Of An Open BLOB {F17840}

5225

**

5226

** Return the size in bytes of the blob accessible via the open

5227

** [sqlite3_blob] object in its only argument.

5228

**

5229

** INVARIANTS:

5230

**

5231

** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size

5232

** in bytes of the BLOB that the [sqlite3_blob] object P

5233

** refers to.

5234

*/

5235

int sqlite3_blob_bytes(sqlite3_blob *);

5236

5237

/*

5238

** CAPI3REF: Read Data From A BLOB Incrementally {F17850}

5239

**

5240

** This function is used to read data from an open

5241

** [sqlite3_blob | blob-handle] into a caller supplied buffer.

5242

** N bytes of data are copied into buffer

5243

** Z from the open blob, starting at offset iOffset.

5244

**

5245

** If offset iOffset is less than N bytes from the end of the blob,

5246

** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is

5247

** less than zero [SQLITE_ERROR] is returned and no data is read.

5248

**

5249

** On success, SQLITE_OK is returned. Otherwise, an

5250

** [error code] or an [extended error code] is returned.

5251

**

5252

** INVARIANTS:

5253

**

5254

** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes

5255

** beginning at offset X from

5256

** the blob that [sqlite3_blob] object P refers to

5257

** and writes those N bytes into buffer Z.

5258

**

5259

** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob

5260

** is less than N+X bytes, then the function returns [SQLITE_ERROR]

5261

** and nothing is read from the blob.

5262

**

5263

** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero

5264

** then the function returns [SQLITE_ERROR]

5265

** and nothing is read from the blob.

5266

**

5267

** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]

5268

** if N bytes where successfully read into buffer Z.

5269

**

5270

** {F17865} If the requested read could not be completed,

5271

** the [sqlite3_blob_read(P,Z,N,X)] interface returns an

5272

** appropriate [error code] or [extended error code].

5273

**

5274

** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]

5275

** then subsequent calls to [sqlite3_errcode(D)],

5276

** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return

5277

** information approprate for that error, where D is the

5278

** database handle that was used to open blob handle P.

5279

*/

5280

int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);

5281

5282

/*

5283

** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}

5284

**

5285

** This function is used to write data into an open

5286

** [sqlite3_blob | blob-handle] from a user supplied buffer.

5287

** n bytes of data are copied from the buffer

5288

** pointed to by z into the open blob, starting at offset iOffset.

5289

**

5290

** If the [sqlite3_blob | blob-handle] passed as the first argument

5291

** was not opened for writing (the flags parameter to [sqlite3_blob_open()]

5292

*** was zero), this function returns [SQLITE_READONLY].

5293

**

5294

** This function may only modify the contents of the blob; it is

5295

** not possible to increase the size of a blob using this API.

5296

** If offset iOffset is less than n bytes from the end of the blob,

5297

** [SQLITE_ERROR] is returned and no data is written. If n is

5298

** less than zero [SQLITE_ERROR] is returned and no data is written.

5299

**

5300

** On success, SQLITE_OK is returned. Otherwise, an

5301

** [error code] or an [extended error code] is returned.

5302

**

5303

** INVARIANTS:

5304

**

5305

** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes

5306

** from buffer Z into

5307

** the blob that [sqlite3_blob] object P refers to

5308

** beginning at an offset of X into the blob.

5309

**

5310

** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns

5311

** [SQLITE_READONLY] if the [sqlite3_blob] object P was

5312

** [sqlite3_blob_open | opened] for reading only.

5313

**

5314

** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob

5315

** is less than N+X bytes, then the function returns [SQLITE_ERROR]

5316

** and nothing is written into the blob.

5317

**

5318

** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero

5319

** then the function returns [SQLITE_ERROR]

5320

** and nothing is written into the blob.

5321

**

5322

** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]

5323

** if N bytes where successfully written into blob.

5324

**

5325

** {F17885} If the requested write could not be completed,

5326

** the [sqlite3_blob_write(P,Z,N,X)] interface returns an

5327

** appropriate [error code] or [extended error code].

5328

**

5329

** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]

5330

** then subsequent calls to [sqlite3_errcode(D)],

5331

** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return

5332

** information approprate for that error.

5333

*/

5334

int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

5335

5336

/*

5337

** CAPI3REF: Virtual File System Objects {F11200}

5338

**

5339

** A virtual filesystem (VFS) is an [sqlite3_vfs] object

5340

** that SQLite uses to interact

5341

** with the underlying operating system. Most SQLite builds come with a

5342

** single default VFS that is appropriate for the host computer.

5343

** New VFSes can be registered and existing VFSes can be unregistered.

5344

** The following interfaces are provided.

5345

**

5346

** The sqlite3_vfs_find() interface returns a pointer to

5347

** a VFS given its name. Names are case sensitive.

5348

** Names are zero-terminated UTF-8 strings.

5349

** If there is no match, a NULL

5350

** pointer is returned. If zVfsName is NULL then the default

5351

** VFS is returned.

5352

**

5353

** New VFSes are registered with sqlite3_vfs_register().

5354

** Each new VFS becomes the default VFS if the makeDflt flag is set.

5355

** The same VFS can be registered multiple times without injury.

5356

** To make an existing VFS into the default VFS, register it again

5357

** with the makeDflt flag set. If two different VFSes with the

5358

** same name are registered, the behavior is undefined. If a

5359

** VFS is registered with a name that is NULL or an empty string,

5360

** then the behavior is undefined.

5361

**

5362

** Unregister a VFS with the sqlite3_vfs_unregister() interface.

5363

** If the default VFS is unregistered, another VFS is chosen as

5364

** the default. The choice for the new VFS is arbitrary.

5365

**

5366

** INVARIANTS:

5367

**

5368

** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the

5369

** registered [sqlite3_vfs] object whose name exactly matches

5370

** the zero-terminated UTF-8 string N, or it returns NULL if

5371

** there is no match.

5372

**

5373

** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then

5374

** the function returns a pointer to the default [sqlite3_vfs]

5375

** object if there is one, or NULL if there is no default

5376

** [sqlite3_vfs] object.

5377

**

5378

** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the

5379

** well-formed [sqlite3_vfs] object P using the name given

5380

** by the zName field of the object.

5381

**

5382

** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register

5383

** the same [sqlite3_vfs] object multiple times is a harmless no-op.

5384

**

5385

** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the

5386

** the [sqlite3_vfs] object P the default [sqlite3_vfs] object

5387

** if F is non-zero.

5388

**

5389

** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the

5390

** [sqlite3_vfs] object P so that it is no longer returned by

5391

** subsequent calls to [sqlite3_vfs_find()].

5392

*/

5393

sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);

5394

int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);

5395

int sqlite3_vfs_unregister(sqlite3_vfs*);

5396

5397

/*

5398

** CAPI3REF: Mutexes {F17000}

5399

**

5400

** The SQLite core uses these routines for thread

5401

** synchronization. Though they are intended for internal

5402

** use by SQLite, code that links against SQLite is

5403

** permitted to use any of these routines.

5404

**

5405

** The SQLite source code contains multiple implementations

5406

** of these mutex routines. An appropriate implementation

5407

** is selected automatically at compile-time. The following

5408

** implementations are available in the SQLite core:

5409

**

5410

** <ul>

5411

** <li> SQLITE_MUTEX_OS2

5412

** <li> SQLITE_MUTEX_PTHREAD

5413

** <li> SQLITE_MUTEX_W32

5414

** <li> SQLITE_MUTEX_NOOP

5415

** </ul>

5416

**

5417

** The SQLITE_MUTEX_NOOP implementation is a set of routines

5418

** that does no real locking and is appropriate for use in

5419

** a single-threaded application. The SQLITE_MUTEX_OS2,

5420

** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations

5421

** are appropriate for use on os/2, unix, and windows.

5422

**

5423

** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor

5424

** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex

5425

** implementation is included with the library. The

5426

** mutex interface routines defined here become external

5427

** references in the SQLite library for which implementations

5428

** must be provided by the application. This facility allows an

5429

** application that links against SQLite to provide its own mutex

5430

** implementation without having to modify the SQLite core.

5431

**

5432

** {F17011} The sqlite3_mutex_alloc() routine allocates a new

5433

** mutex and returns a pointer to it. {F17012} If it returns NULL

5434

** that means that a mutex could not be allocated. {F17013} SQLite

5435

** will unwind its stack and return an error. {F17014} The argument

5436

** to sqlite3_mutex_alloc() is one of these integer constants:

5437

**

5438

** <ul>

5439

** <li> SQLITE_MUTEX_FAST

5440

** <li> SQLITE_MUTEX_RECURSIVE

5441

** <li> SQLITE_MUTEX_STATIC_MASTER

5442

** <li> SQLITE_MUTEX_STATIC_MEM

5443

** <li> SQLITE_MUTEX_STATIC_MEM2

5444

** <li> SQLITE_MUTEX_STATIC_PRNG

5445

** <li> SQLITE_MUTEX_STATIC_LRU

5446

** <li> SQLITE_MUTEX_STATIC_LRU2

5447

** </ul> {END}

5448

**

5449

** {F17015} The first two constants cause sqlite3_mutex_alloc() to create

5450

** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE

5451

** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}

5452

** The mutex implementation does not need to make a distinction

5453

** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does

5454

** not want to. {F17016} But SQLite will only request a recursive mutex in

5455

** cases where it really needs one. {END} If a faster non-recursive mutex

5456

** implementation is available on the host platform, the mutex subsystem

5457

** might return such a mutex in response to SQLITE_MUTEX_FAST.

5458

**

5459

** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return

5460

** a pointer to a static preexisting mutex. {END} Four static mutexes are

5461

** used by the current version of SQLite. Future versions of SQLite

5462

** may add additional static mutexes. Static mutexes are for internal

5463

** use by SQLite only. Applications that use SQLite mutexes should

5464

** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or

5465

** SQLITE_MUTEX_RECURSIVE.

5466

**

5467

** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST

5468

** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()

5469

** returns a different mutex on every call. {F17034} But for the static

5470

** mutex types, the same mutex is returned on every call that has

5471

** the same type number. {END}

5472

**

5473

** {F17019} The sqlite3_mutex_free() routine deallocates a previously

5474

** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every

5475

** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in

5476

** use when they are deallocated. {U17022} Attempting to deallocate a static

5477

** mutex results in undefined behavior. {F17023} SQLite never deallocates

5478

** a static mutex. {END}

5479

**

5480

** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt

5481

** to enter a mutex. {F17024} If another thread is already within the mutex,

5482

** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return

5483

** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK

5484

** upon successful entry. {F17026} Mutexes created using

5485

** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.

5486

** {F17027} In such cases the,

5487

** mutex must be exited an equal number of times before another thread

5488

** can enter. {U17028} If the same thread tries to enter any other

5489

** kind of mutex more than once, the behavior is undefined.

5490

** {F17029} SQLite will never exhibit

5491

** such behavior in its own use of mutexes. {END}

5492

**

5493

** Some systems (ex: windows95) do not the operation implemented by

5494

** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will

5495

** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses

5496

** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}

5497

**

5498

** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was

5499

** previously entered by the same thread. {U17032} The behavior

5500

** is undefined if the mutex is not currently entered by the

5501

** calling thread or is not currently allocated. {F17033} SQLite will

5502

** never do either. {END}

5503

**

5504

** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].

5505

*/

5506

sqlite3_mutex *sqlite3_mutex_alloc(int);

5507

void sqlite3_mutex_free(sqlite3_mutex*);

5508

void sqlite3_mutex_enter(sqlite3_mutex*);

5509

int sqlite3_mutex_try(sqlite3_mutex*);

5510

void sqlite3_mutex_leave(sqlite3_mutex*);

5511

5512

/*

5513

** CAPI3REF: Mutex Verifcation Routines {F17080}

5514

**

5515

** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines

5516

** are intended for use inside assert() statements. {F17081} The SQLite core

5517

** never uses these routines except inside an assert() and applications

5518

** are advised to follow the lead of the core. {F17082} The core only

5519

** provides implementations for these routines when it is compiled

5520

** with the SQLITE_DEBUG flag. {U17087} External mutex implementations

5521

** are only required to provide these routines if SQLITE_DEBUG is

5522

** defined and if NDEBUG is not defined.

5523

**

5524

** {F17083} These routines should return true if the mutex in their argument

5525

** is held or not held, respectively, by the calling thread. {END}

5526

**

5527

** {X17084} The implementation is not required to provided versions of these

5528

** routines that actually work.

5529

** If the implementation does not provide working

5530

** versions of these routines, it should at least provide stubs

5531

** that always return true so that one does not get spurious

5532

** assertion failures. {END}

5533

**

5534

** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then

5535

** the routine should return 1. {END} This seems counter-intuitive since

5536

** clearly the mutex cannot be held if it does not exist. But the

5537

** the reason the mutex does not exist is because the build is not

5538

** using mutexes. And we do not want the assert() containing the

5539

** call to sqlite3_mutex_held() to fail, so a non-zero return is

5540

** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld()

5541

** interface should also return 1 when given a NULL pointer.

5542

*/

5543

int sqlite3_mutex_held(sqlite3_mutex*);

5544

int sqlite3_mutex_notheld(sqlite3_mutex*);

5545

5546

/*

5547

** CAPI3REF: Mutex Types {F17001}

5548

**

5549

** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument

5550

** which is one of these integer constants. {END}

5551

*/

5552

#define SQLITE_MUTEX_FAST 0

5553

#define SQLITE_MUTEX_RECURSIVE 1

5554

#define SQLITE_MUTEX_STATIC_MASTER 2

5555

#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */

5556

#define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */

5557

#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */

5558

#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */

5559

#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */

5560

5561

/*

5562

** CAPI3REF: Low-Level Control Of Database Files {F11300}

5563

**

5564

** {F11301} The [sqlite3_file_control()] interface makes a direct call to the

5565

** xFileControl method for the [sqlite3_io_methods] object associated

5566

** with a particular database identified by the second argument. {F11302} The

5567

** name of the database is the name assigned to the database by the

5568

** <a href="lang_attach.html">ATTACH</a> SQL command that opened the

5569

** database. {F11303} To control the main database file, use the name "main"

5570

** or a NULL pointer. {F11304} The third and fourth parameters to this routine

5571

** are passed directly through to the second and third parameters of

5572

** the xFileControl method. {F11305} The return value of the xFileControl

5573

** method becomes the return value of this routine.

5574

**

5575

** {F11306} If the second parameter (zDbName) does not match the name of any

5576

** open database file, then SQLITE_ERROR is returned. {F11307} This error

5577

** code is not remembered and will not be recalled by [sqlite3_errcode()]

5578

** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might

5579

** also return SQLITE_ERROR. {U11309} There is no way to distinguish between

5580

** an incorrect zDbName and an SQLITE_ERROR return from the underlying

5581

** xFileControl method. {END}

5582

**

5583

** See also: [SQLITE_FCNTL_LOCKSTATE]

5584

*/

5585

int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);

5586

5587

/*

5588

** CAPI3REF: Testing Interface {F11400}

5589

**

5590

** The sqlite3_test_control() interface is used to read out internal

5591

** state of SQLite and to inject faults into SQLite for testing

5592

** purposes. The first parameter a operation code that determines

5593

** the number, meaning, and operation of all subsequent parameters.

5594

**

5595

** This interface is not for use by applications. It exists solely

5596

** for verifying the correct operation of the SQLite library. Depending

5597

** on how the SQLite library is compiled, this interface might not exist.

5598

**

5599

** The details of the operation codes, their meanings, the parameters

5600

** they take, and what they do are all subject to change without notice.

5601

** Unlike most of the SQLite API, this function is not guaranteed to

5602

** operate consistently from one release to the next.

5603

*/

5604

int sqlite3_test_control(int op, ...);

5605

5606

/*

5607

** CAPI3REF: Testing Interface Operation Codes {F11410}

5608

**

5609

** These constants are the valid operation code parameters used

5610

** as the first argument to [sqlite3_test_control()].

5611

**

5612

** These parameters and their meansing are subject to change

5613

** without notice. These values are for testing purposes only.

5614

** Applications should not use any of these parameters or the

5615

** [sqlite3_test_control()] interface.

5616

*/

5617

#define SQLITE_TESTCTRL_FAULT_CONFIG 1

5618

#define SQLITE_TESTCTRL_FAULT_FAILURES 2

5619

#define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3

5620

#define SQLITE_TESTCTRL_FAULT_PENDING 4

5621

#define SQLITE_TESTCTRL_PRNG_SAVE 5

5622

#define SQLITE_TESTCTRL_PRNG_RESTORE 6

5623

#define SQLITE_TESTCTRL_PRNG_RESET 7

5624

#define SQLITE_TESTCTRL_BITVEC_TEST 8

5625

5626

5627

/*

5628

** Undo the hack that converts floating point types to integer for

5629

** builds on processors without floating point support.

5630

*/

5631

#ifdef SQLITE_OMIT_FLOATING_POINT

5632

# undef double

5633

#endif

5634

5635

#ifdef __cplusplus

5636

} /* End of the 'extern "C"' block */

5637

#endif

5638

#endif