System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 8a7fc7d96d291df4c41c437abb645d3a5b031c01:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 33 2e 68 2c   $Id: sqlite3.h,
05e0: 76 20 31 2e 33 39 20 32 30 30 39 2f 30 34 2f 32  v 1.39 2009/04/2
05f0: 38 20 31 36 3a 31 37 3a 34 35 20 72 6d 73 69 6d  8 16:17:45 rmsim
0600: 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 69  pson Exp $.*/.#i
0610: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
0620: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
0630: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
0640: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
0650: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
0660: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
0670: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
0680: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
0690: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
06a0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
06b0: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
06c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
06d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
06e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
06f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
0700: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
0710: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0720: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0730: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0740: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0750: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0760: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0770: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
0780: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
0790: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
07a0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
07b0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
07c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
07d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
07e0: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 72 66  deprecated intrf
07f0: 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20  aces - they are 
0800: 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b  support for back
0810: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
0820: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70  bility only.  Ap
0830: 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72  plication writer
0840: 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72  s should be awar
0850: 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69  e that.** experi
0860: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
0870: 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f  s are subject to
0880: 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74   change in point
0890: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
08a0: 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73   These macros us
08b0: 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f  ed to resolve to
08c0: 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f   various kinds o
08d0: 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63  f compiler magic
08e0: 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67   that.** would g
08f0: 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20  enerate warning 
0900: 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68  messages when th
0910: 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42  ey were used.  B
0920: 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69  ut that.** compi
0930: 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20  ler magic ended 
0940: 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75  up generating su
0950: 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62  ch a flurry of b
0960: 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68  ug reports.** th
0970: 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e  at we have taken
0980: 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20   it all out and 
0990: 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69  gone back to usi
09a0: 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f  ng simple.** noo
09b0: 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65  p macros..*/.#de
09c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52  fine SQLITE_DEPR
09d0: 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53  ECATED.#define S
09e0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
09f0: 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65  AL../*.** Ensure
0a00: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77   these symbols w
0a10: 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20  ere not defined 
0a20: 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73  by some previous
0a30: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f   header file..*/
0a40: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
0a50: 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53  ERSION.# undef S
0a60: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65  QLITE_VERSION.#e
0a70: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49  ndif.#ifdef SQLI
0a80: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0a90: 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  R.# undef SQLITE
0aa0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
0ab0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
0ac0: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
0ad0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0ae0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31  sion Numbers {H1
0af0: 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0010} <S60100>.*
0b00: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
0b10: 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49  VERSION and SQLI
0b20: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0b30: 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a  R #defines in.**
0b40: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66   the sqlite3.h f
0b50: 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65 20  ile specify the 
0b60: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
0b70: 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20  e with which.** 
0b80: 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c 65  that header file
0b90: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a   is associated..
0ba0: 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69  **.** The "versi
0bb0: 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73  on" of SQLite is
0bc0: 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65   a string of the
0bd0: 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a   form "X.Y.Z"..*
0be0: 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61 6c  * The phrase "al
0bf0: 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d  pha" or "beta" m
0c00: 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65 64  ight be appended
0c10: 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a   after the Z..**
0c20: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
0c30: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  major version nu
0c40: 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e  mber always 3 in
0c50: 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65   SQLite3..** The
0c60: 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68   X value only ch
0c70: 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b 77  anges when backw
0c80: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
0c90: 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20  ty is.** broken 
0ca0: 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f  and we intend to
0cb0: 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61 63   never break bac
0cc0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
0cd0: 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76  lity..** The Y v
0ce0: 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f  alue is the mino
0cf0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
0d00: 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65   and only change
0d10: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  s when.** there 
0d20: 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72  are major featur
0d30: 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74  e enhancements t
0d40: 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 73  hat are forwards
0d50: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62   compatible.** b
0d60: 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73  ut not backwards
0d70: 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20   compatible..** 
0d80: 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 74  The Z value is t
0d90: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0da0: 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65  r and is increme
0db0: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63  nted with.** eac
0dc0: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65  h release but re
0dd0: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77  sets back to 0 w
0de0: 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e 63  henever Y is inc
0df0: 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  remented..**.** 
0e00: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
0e10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
0e20: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69   and [sqlite3_li
0e30: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0e40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
0e50: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d  ements: [H10011]
0e60: 20 5b 48 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65   [H10014].*/.#de
0e70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0e80: 49 4f 4e 20 20 20 20 20 20 20 20 20 22 33 2e 36  ION         "3.6
0e90: 2e 31 33 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  .13".#define SQL
0ea0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0eb0: 45 52 20 20 33 30 30 36 30 31 33 0a 0a 2f 2a 0a  ER  3006013../*.
0ec0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
0ed0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
0ee0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
0ef0: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
0f00: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
0f10: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
0f20: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65  ** These feature
0f30: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
0f40: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0f50: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
0f60: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53  RSION].** and [S
0f70: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0f80: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69  MBER] #defines i
0f90: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75  n the header, bu
0fa0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
0fb0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62  .** with the lib
0fc0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
0fd0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
0fe0: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72    Cautious progr
0ff0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20  ammers might.** 
1000: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20  include a check 
1010: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1020: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74  tion to verify t
1030: 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  hat.** sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1050: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  () always return
1060: 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b  s the value.** [
1070: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1080: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
1090: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
10a0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
10b0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
10c0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10d0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
10e0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
10f0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
1100: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
1110: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
1120: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1130: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1140: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1150: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1160: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1170: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1180: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75   DLL..**.** Requ
1190: 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32  irements: [H1002
11a0: 31 5d 20 5b 48 31 30 30 32 32 5d 20 5b 48 31 30  1] [H10022] [H10
11b0: 30 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  023].*/.SQLITE_E
11c0: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
11d0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
11e0: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
11f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1200: 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  on(void);.int sq
1210: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1220: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1230: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1240: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1250: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1260: 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30  readsafe {H10100
1270: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60100>.**.**
1280: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
1290: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
12a0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
12b0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53    When.** the [S
12c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
12e0: 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d   macro 1 or 2, m
12f0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1300: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1310: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1320: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1330: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1340: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1350: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1360: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1370: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1380: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1390: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
13a0: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
13b0: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
13c0: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
13d0: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
13e0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
13f0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1400: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1410: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1420: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1430: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1440: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1450: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1460: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1470: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1480: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1490: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68   The default beh
14a0: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
14b0: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
14c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
14d0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
14e0: 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61  used by a progra
14f0: 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  m to make sure t
1500: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
1510: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
1520: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
1530: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
1540: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
1550: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
1560: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
1570: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
1580: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
1590: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
15a0: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
15b0: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
15c0: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
15d0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
15e0: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
15f0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1600: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
1610: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68  _THREADSAFE=1 th
1620: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
1630: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
1640: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
1650: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
1660: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
1670: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
1680: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
1690: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
16a0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
16b0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
16c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16d0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
16e0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
16f0: 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65  _MUTEX].  The re
1700: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1710: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77  is function show
1720: 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65  s.** only the de
1730: 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69  fault compile-ti
1740: 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20  me setting, not 
1750: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
1760: 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20  nges.** to that 
1770: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53  setting..**.** S
1780: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
1790: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
17a0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
17b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
17c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
17d0: 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b  ents: [H10101] [
17e0: 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H10102].*/.int s
17f0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1800: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  e(void);../*.** 
1810: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
1820: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
1830: 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53  ndle {H12000} <S
1840: 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  40200>.** KEYWOR
1850: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
1860: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
1870: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
1880: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
1890: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
18a0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
18b0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
18c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
18d0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
18e0: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
18f0: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
1900: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
1910: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
1920: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
1930: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
1940: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1950: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1960: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1970: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1980: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
1990: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
19a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
19b0: 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73  )].** is its des
19c0: 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20  tructor.  There 
19d0: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69  are many other i
19e0: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20  nterfaces (such 
19f0: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  as.** [sqlite3_p
1a00: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
1a10: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1a20: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
1a30: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1a40: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
1a50: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
1a60: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
1a70: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20  n an.** sqlite3 
1a80: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
1a90: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1aa0: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a  3 sqlite3;../*.*
1ab0: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42  * CAPI3REF: 64-B
1ac0: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73  it Integer Types
1ad0: 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31   {H10200} <S1011
1ae0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1af0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
1b00: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
1b10: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
1b20: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
1b30: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
1b40: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
1b50: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
1b60: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
1b70: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
1b80: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
1b90: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
1ba0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
1bb0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
1bc0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
1bd0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
1be0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
1bf0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
1c00: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
1c10: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
1c20: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
1c30: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
1c40: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
1c50: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1c60: 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32 5d  H10201] [H10202]
1c70: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1c80: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
1c90: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
1ca0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1cb0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1cc0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
1cd0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1ce0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
1cf0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1d00: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
1d10: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
1d20: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
1d30: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1d40: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
1d50: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1d60: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
1d70: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
1d80: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
1d90: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
1da0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
1db0: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
1dc0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
1dd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1de0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
1df0: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
1e00: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
1e10: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
1e20: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
1e30: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
1e40: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
1e50: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
1e60: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
1e70: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
1e80: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
1e90: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
1ea0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
1eb0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
1ec0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
1ed0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1ee0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
1ef0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e Connection {H1
1f00: 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53  2010} <S30100><S
1f10: 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40200>.**.** Thi
1f20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  s routine is the
1f30: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
1f40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1f50: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ject..**.** Appl
1f60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1f70: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f80: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
1f90: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
1fa0: 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b  ements].** and [
1fb0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
1fc0: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
1fd0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61  [BLOB handles] a
1fe0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1ff0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
2000: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20  object prior to 
2010: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
2020: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a  ose the object..
2030: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2040: 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74  next_stmt()] int
2050: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2060: 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ed to locate all
2070: 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2080: 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69  atements] associ
2090: 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
20a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20b0: 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a  ] if desired..**
20c0: 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69   Typical code mi
20d0: 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68  ght look like th
20e0: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
20f0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73  quote><pre>.** s
2100: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2110: 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70  mt;.** while( (p
2120: 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e  Stmt = sqlite3_n
2130: 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29  ext_stmt(db, 0))
2140: 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b  !=0 ){.** &nbsp;
2150: 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c     sqlite3_final
2160: 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d  ize(pStmt);.** }
2170: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2180: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66  kquote>.**.** If
2190: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
21a0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  )] is invoked wh
21b0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
21c0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
21d0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
21e0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
21f0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
2200: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
2210: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2220: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20  ose(C)] must be 
2230: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
2240: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
2250: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2260: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
2270: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2280: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2290: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
22a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
22b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
22c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
22d0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  sed..**.** Requi
22e0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
22f0: 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48  011] [H12012] [H
2300: 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20  12013] [H12014] 
2310: 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39  [H12015] [H12019
2320: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2330: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2340: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2350: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2360: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2370: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2380: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2390: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
23a0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
23b0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
23c0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
23d0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
23e0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
23f0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2400: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2410: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2420: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2430: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2440: 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20  erface {H12100} 
2450: 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10000>.**.** T
2460: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
2470: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
2480: 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20   convenient way 
2490: 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f  of running one o
24a0: 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74  r more.** SQL st
24b0: 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74  atements without
24c0: 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65   having to write
24d0: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
24e0: 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63  .  The UTF-8 enc
24f0: 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  oded.** SQL stat
2500: 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65  ements are passe
2510: 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f  d in as the seco
2520: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
2530: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a  sqlite3_exec()..
2540: 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74  ** The statement
2550: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
2560: 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c  one by one until
2570: 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72   either an error
2580: 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72   or.** an interr
2590: 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72  upt is encounter
25a0: 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ed, or until the
25b0: 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20  y are all done. 
25c0: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
25d0: 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69  er.** is an opti
25e0: 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68  onal callback th
25f0: 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  at is invoked on
2600: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ce for each row 
2610: 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20  of any query.** 
2620: 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64  results produced
2630: 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74   by the SQL stat
2640: 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68  ements.  The 5th
2650: 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73   parameter tells
2660: 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69   where.** to wri
2670: 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73  te any error mes
2680: 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  sages..**.** The
2690: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70   error message p
26a0: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75  assed back throu
26b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
26c0: 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20  eter is held.** 
26d0: 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
26e0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
26f0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20  _malloc()].  To 
2700: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
2710: 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  eak,.** the call
2720: 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ing application 
2730: 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c  should call [sql
2740: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
2750: 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  any error.** mes
2760: 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68  sage returned th
2770: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
2780: 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20  rameter when it 
2790: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
27a0: 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  ng.** the error 
27b0: 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49  message..**.** I
27c0: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
27d0: 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ent in the 2nd p
27e0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
27f0: 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
2800: 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69  ing.** or a stri
2810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e  ng containing on
2820: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
2830: 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  d comments, then
2840: 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   no SQL.** state
2850: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
2860: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
2870: 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e  base is not chan
2880: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ged..**.** The s
2890: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
28a0: 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
28b0: 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20  mented in terms 
28c0: 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  of.** [sqlite3_p
28d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
28e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
28f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
2900: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  alize()]..** The
2910: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2920: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
2930: 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61  hing to the data
2940: 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74  base that cannot
2950: 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b   be done.** by [
2960: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2970: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2980: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
2990: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
29b0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
29c0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
29d0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69   must be an vali
29e0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64  d and open.** [d
29f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a00: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  on]..**.** The d
2a10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
2a30: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b  losed while.** [
2a40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2a50: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2a60: 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  * The calling fu
2a70: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  nction should us
2a80: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
2a90: 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68  )] to free.** th
2aa0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
2ab0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
2ac0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
2ad0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2ae0: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
2af0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   needed..**.** T
2b00: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2b10: 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64   text in the 2nd
2b20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2b30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
2b40: 2a 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e  * must remain un
2b50: 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73  changed while [s
2b60: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
2b70: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2b80: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
2b90: 2a 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32 31  * [H12101] [H121
2ba0: 30 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48 31  02] [H12104] [H1
2bb0: 32 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b  2105] [H12107] [
2bc0: 48 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33 5d  H12110] [H12113]
2bd0: 20 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31   [H12116].** [H1
2be0: 32 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b  2119] [H12122] [
2bf0: 48 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31 5d  H12125] [H12131]
2c00: 20 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31 33   [H12134] [H1213
2c10: 37 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69  7] [H12138].*/.i
2c20: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
2c30: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c60: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
2c70: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c80: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
2c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ca0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2cb0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
2cc0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
2cd0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
2ce0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
2cf0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
2d00: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
2d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2d30: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
2d40: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
2d50: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
2d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
2d80: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
2d90: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
2da0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2db0: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d  t Codes {H10210}
2dc0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
2dd0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
2de0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
2df0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
2e00: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
2e10: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
2e20: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
2e30: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
2e40: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
2e50: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
2e60: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
2e70: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
2e80: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
2e90: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
2ea0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
2eb0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
2ec0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2ed0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
2ee0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
2ef0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
2f00: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
2f10: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2f20: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
2f30: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
2f40: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
2f50: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
2f60: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
2f70: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
2f80: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
2f90: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
2fa0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
2fb0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
2fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2fd0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
2fe0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
2ff0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
3000: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3010: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
3020: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
3030: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
3040: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3050: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
3060: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
3070: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
3080: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
3090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
30a0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
30b0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
30c0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
30d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
30e0: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
30f0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
3100: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
3110: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
3120: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
3130: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
3140: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
3150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3160: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
3170: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
3180: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
3190: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
31a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
31b0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
31c0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
31d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
31e0: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
31f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3200: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
3210: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
3220: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
3230: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
3240: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
3250: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
3260: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
3270: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
3280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3290: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
32a0: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54    /* NOT USED. T
32b0: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e  able or record n
32c0: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66  ot found */.#def
32d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
32e0: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
32f0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
3300: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
3310: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
3320: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
3330: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
3340: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
3350: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3370: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
3380: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
3390: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
33a0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
33b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
33c0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
33d0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
33e0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
33f0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
3400: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
3410: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
3420: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
3430: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
3440: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
3450: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
3460: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
3470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3480: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
3490: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
34a0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
34b0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
34c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
34d0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
34e0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
34f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3500: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
3510: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
3520: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
3530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3540: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
3550: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
3560: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
3570: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
3580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
3590: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
35a0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
35b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
35c0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
35d0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
35e0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
35f0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
3600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3610: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
3620: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
3630: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
3640: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
3650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3660: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
3670: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
3680: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
3690: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
36a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
36b0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
36c0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
36d0: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
36e0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
36f0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
3700: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
3710: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
3720: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
3730: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
3740: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
3750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3760: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
3770: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c  Codes {H10220} <
3780: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
3790: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65  RDS: {extended e
37a0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65  rror code} {exte
37b0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
37c0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
37d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
37e0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
37f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a  result codes}.**
3800: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
3810: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
3820: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
3830: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
3840: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
3850: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
3860: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
3870: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
3880: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
3890: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
38a0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
38b0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
38c0: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
38d0: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
38e0: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
38f0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
3900: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
3910: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
3920: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
3930: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
3940: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
3950: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
3960: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
3970: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
3980: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
3990: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
39a0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
39b0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
39c0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
39d0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78  t errors. The ex
39e0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
39f0: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
3a00: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
3a10: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
3a20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
3a30: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
3a40: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3a50: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
3a60: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65   API..**.** Some
3a70: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c   of the availabl
3a80: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
3a90: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74  t codes are list
3aa0: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20  ed here..** One 
3ab0: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e  may expect the n
3ac0: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65  umber of extende
3ad0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77  d result codes w
3ae0: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a  ill be expand.**
3af0: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66   over time.  Sof
3b00: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20  tware that uses 
3b10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3b20: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70  codes should exp
3b30: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65  ect.** to see ne
3b40: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69  w result codes i
3b50: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
3b60: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
3b70: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
3b80: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
3b90: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
3ba0: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
3bb0: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
3bc0: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66  ly zero..*/.#def
3bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3be0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
3bf0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3c00: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
3c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3c20: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
3c30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3c40: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
3c50: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
3c60: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
3c70: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3c80: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
3c90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
3ca0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
3cb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3cc0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
3cd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
3ce0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
3cf0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3d00: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
3d10: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
3d20: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
3d30: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
3d40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3d50: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3d70: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
3d80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3d90: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
3db0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
3dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3dd0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
3de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
3e00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3e10: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
3e20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3e30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
3e40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3e50: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
3e60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3e70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
3e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3e90: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
3ea0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3eb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
3ec0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ed0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
3ee0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3ef0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
3f00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f10: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
3f20: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
3f30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
3f40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f50: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
3f60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3f70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
3f80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3f90: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
3fa0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3fb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
3fc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3fd0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
3fe0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
3ff0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
4000: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4010: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
4020: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
4030: 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38  E_LOCKED | (1<<8
4040: 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ) )../*.** CAPI3
4050: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
4060: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
4070: 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31  ons {H10230} <H1
4080: 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a  1120> <H12700>.*
4090: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
40a0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
40b0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
40c0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
40d0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
40e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
40f0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4100: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
4110: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
4120: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
4130: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
4140: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
4150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
4160: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
4170: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
4180: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
4190: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
41a0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
41c0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
41d0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
41e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
41f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
4200: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
4210: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
4220: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
4230: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
4240: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
4250: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
4260: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
4270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
4280: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
4290: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
42a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
42b0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
42c0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
42d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
42e0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
42f0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
4310: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
4320: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
4330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
4340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
4350: 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69  0x00002000.#defi
4360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
4370: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
4380: 30 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69  0x00004000.#defi
4390: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
43a0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
43b0: 30 78 30 30 30 30 38 30 30 30 0a 23 64 65 66 69  0x00008000.#defi
43c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
43d0: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
43e0: 30 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a  0x00010000../*.*
43f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
4400: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
4410: 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31  cs {H10240} <H11
4420: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  120>.**.** The x
4430: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69  DeviceCapabiliti
4440: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  es method of the
4450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4460: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
4470: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
4480: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
4490: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73  ctor of the thes
44a0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
44b0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
44c0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
44d0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
44e0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
44f0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
4500: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
4510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
4520: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
4530: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
4540: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
4550: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
4560: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
4570: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
4580: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
4590: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
45a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
45b0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
45c0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
45d0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
45e0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
45f0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
4600: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
4610: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
4620: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
4630: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
4640: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
4650: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
4660: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
4670: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
4680: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
4690: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
46a0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
46b0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
46c0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
46d0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
46e0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
46f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
4700: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
4710: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
4720: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
4730: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
4740: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
4750: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
4760: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65  xWrite()..*/.#de
4770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4780: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
4790: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
47a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
47b0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
47c0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
47e0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
47f0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
4800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4810: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
4820: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4840: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
4850: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
4860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4870: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
4880: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
48a0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
48b0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
48c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
48d0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
48e0: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
48f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4900: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
4910: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4930: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
4940: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
4960: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
4970: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a    0x00000400../*
4980: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
4990: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
49a0: 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31  s {H10250} <H111
49b0: 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a  20> <H11310>.**.
49c0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
49d0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
49e0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
49f0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
4a00: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
4a10: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
4a20: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
4a30: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
4a40: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
4a50: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
4a60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4a70: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
4a80: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
4a90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
4aa0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4ac0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
4ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ae0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
4af0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
4b00: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
4b10: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
4b20: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
4b30: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
4b40: 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48  lags {H10260} <H
4b50: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65  11120>.**.** Whe
4b60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
4b70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
4b80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
4b90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4ba0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
4bb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
4bc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
4bd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
4be0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
4bf0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
4c00: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
4c10: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
4c20: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
4c30: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
4c40: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
4c50: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
4c60: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
4c70: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
4c80: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
4c90: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
4ca0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
4cb0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
4cc0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
4cd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
4ce0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
4cf0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
4d00: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
4d10: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
4d20: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
4d30: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
4d40: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
4d50: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
4d60: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
4d70: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
4d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
4d90: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
4da0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
4db0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
4dc0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
4dd0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
4de0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4df0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
4e00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
4e10: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
4e20: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31  File Handle {H11
4e30: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a  110} <S20110>.**
4e40: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
4e50: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
4e60: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
4e70: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
4e80: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
4e90: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
4ea0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
4eb0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
4ec0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
4ed0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
4ee0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
4ef0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
4f00: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
4f10: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
4f20: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
4f30: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
4f40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4f50: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
4f60: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
4f70: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
4f80: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
4f90: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
4fa0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
4fb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
4fc0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
4fd0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
4fe0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
4ff0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
5000: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
5010: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
5020: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
5030: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
5040: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5050: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
5060: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
5070: 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31   {H11120} <S2011
5080: 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  0>.**.** Every f
5090: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
50a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
50b0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70  xOpen method pop
50c0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
50d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
50e0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
50f0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
5100: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
5110: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5120: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
5130: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
5140: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
5150: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
5160: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
5170: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
5180: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
5190: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
51a0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
51b0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
51c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
51d0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
51e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
51f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
5200: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
5210: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
5220: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
5230: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
5240: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
5250: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
5260: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
5270: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
5280: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
5290: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
52a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
52b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
52c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
52d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
52e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
52f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
5300: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
5310: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
5320: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
5330: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
5340: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
5350: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
5360: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5370: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
5380: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5390: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
53a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
53b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
53c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
53d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
53e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
53f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5400: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5410: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5420: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5430: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5440: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
5450: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
5460: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
5470: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
5480: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
5490: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
54a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
54b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
54c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
54d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
54e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
54f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
5500: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
5510: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
5520: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
5530: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
5540: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
5550: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
5560: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
5570: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
5580: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
5590: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
55a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
55b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
55c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
55d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
55e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
55f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
5600: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
5610: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
5620: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
5630: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
5640: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
5650: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
5660: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
5670: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
5680: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
5690: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
56a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
56b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
56c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
56d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
56e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
56f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
5700: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
5710: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
5720: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
5730: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
5740: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
5750: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
5760: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
5770: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
5780: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
5790: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
57a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
57b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
57c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
57d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
57e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
57f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
5800: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
5810: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
5820: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
5830: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
5840: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
5850: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
5860: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
5870: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
5880: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
5890: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
58a0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
58b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
58c0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
58d0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
58e0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
58f0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
5900: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
5910: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
5920: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
5930: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
5940: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
5950: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
5960: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
5970: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
5980: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
5990: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
59a0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
59b0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
59c0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
59d0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
59e0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
59f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
5a00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5a10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
5a20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
5a30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
5a40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5a50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
5a60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5a70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
5a80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5a90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
5aa0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5ab0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
5ac0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5ad0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
5ae0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5af0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
5b00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
5b10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
5b20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
5b30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
5b40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5b50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5b60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
5b70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5b80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5b90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5ba0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5bb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5bc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5bd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5be0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
5bf0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
5c00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
5c10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
5c20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
5c30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
5c40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5c50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5c60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5c70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5c80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5c90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5ca0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5cb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5cc0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5cd0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5ce0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
5cf0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
5d00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
5d10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
5d20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
5d30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5d40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5d50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5d60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5d70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5d80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5d90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5da0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
5db0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
5dc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5dd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
5de0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
5df0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
5e00: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
5e10: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
5e20: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
5e30: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
5e40: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
5e50: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
5e60: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
5e70: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
5e80: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
5e90: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
5ea0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
5eb0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
5ec0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5ed0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
5ee0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
5ef0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
5f00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5f10: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
5f20: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
5f30: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
5f40: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
5f50: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
5f60: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
5f70: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
5f80: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
5f90: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
5fa0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
5fb0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
5fc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
5fd0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
5fe0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
5ff0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6000: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6010: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6020: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
6030: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
6040: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
6050: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6060: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
6070: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
6080: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6090: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
60a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
60b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
60c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
60d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
60e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
60f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6100: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6110: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6120: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6130: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6140: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6150: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6160: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6170: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6180: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6190: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
61a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
61b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
61c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
61d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
61e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
61f0: 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e  H11310} <S30800>
6200: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
6210: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
6220: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
6230: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
6240: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
6250: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6260: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
6270: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
6280: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6290: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
62a0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
62b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
62c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
62d0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
62e0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
62f0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
6300: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
6310: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
6320: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
6330: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
6340: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
6350: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
6360: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
6370: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6380: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
6390: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
63a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
63b0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
63c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
63d0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
63e0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
63f0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
6400: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
6410: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
6420: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
6430: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
6440: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
6450: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69  efined..*/.#defi
6460: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
6470: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
6480: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6490: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
64a0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
64b0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
64c0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
64d0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
64e0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
64f0: 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a           4../*.*
6500: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
6510: 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30  x Handle {H17110
6520: 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a  } <S20130>.**.**
6530: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
6540: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
6550: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
6560: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
6570: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
6580: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
6590: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
65a0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
65b0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
65c0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
65d0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
65e0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
65f0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
6600: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
6610: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
6620: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
6630: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
6640: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
6650: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
6660: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
6670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
6680: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
6690: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
66a0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
66b0: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d   Object {H11140}
66c0: 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20100>.**.** 
66d0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
66e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
66f0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
6700: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
6710: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
6720: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
6730: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
6740: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
6750: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
6760: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
6770: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
6780: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
6790: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
67a0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
67b0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
67c0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
67d0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
67e0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
67f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
6800: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
6810: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
6820: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
6830: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
6840: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
6850: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
6860: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
6870: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
6880: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
6890: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
68a0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
68b0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
68c0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
68d0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
68e0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
68f0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
6900: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
6910: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
6920: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6930: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
6940: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
6950: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
6960: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
6970: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
6980: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
6990: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
69a0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
69b0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
69c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
69d0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
69e0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
69f0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
6a00: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
6a10: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
6a20: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
6a30: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
6a40: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
6a50: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
6a60: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
6a70: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
6a80: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
6a90: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
6aa0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
6ab0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
6ac0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6ad0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
6ae0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
6af0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
6b00: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
6b10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
6b20: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
6b30: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
6b40: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
6b50: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
6b60: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
6b70: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
6b80: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
6b90: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
6ba0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
6bb0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
6bc0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
6bd0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
6be0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
6bf0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
6c00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
6c10: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
6c20: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
6c30: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
6c40: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
6c50: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
6c60: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
6c70: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
6c80: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
6c90: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
6ca0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
6cb0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
6cc0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
6cd0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
6ce0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
6cf0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
6d00: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
6d10: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
6d20: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
6d30: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
6d40: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
6d50: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
6d60: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
6d70: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
6d80: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
6d90: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
6da0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
6db0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
6dc0: 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ense,.** the [sq
6dd0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
6de0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
6df0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
6e00: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
6e10: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
6e20: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
6e30: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
6e40: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
6e50: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
6e60: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
6e70: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
6e80: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69  pen.** must invi
6e90: 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  te its own tempo
6ea0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
6eb0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
6ec0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
6ed0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
6ee0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
6ef0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
6f00: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
6f10: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
6f20: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
6f30: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6f40: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
6f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6f60: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
6f70: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
6f80: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
6f90: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
6fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
6fb0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
6fc0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
6fd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
6fe0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
6ff0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
7000: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
7010: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7020: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
7030: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
7040: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
7050: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
7060: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
7070: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
7080: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
7090: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
70a0: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
70b0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
70c0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  et..**.** SQLite
70d0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
70e0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
70f0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7100: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
7110: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
7120: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
7130: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
7140: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
7150: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
7160: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7170: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
7180: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
71a0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
71b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
71c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
71d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
71e0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
71f0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7200: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
7210: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7220: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
7230: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
7240: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
7250: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7260: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
7270: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
7280: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
7290: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
72a0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
72b0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
72c0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
72d0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
72e0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
72f0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
7300: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
7310: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
7320: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
7330: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
7340: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
7350: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
7360: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
7370: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
7380: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
7390: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
73a0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
73b0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
73c0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
73d0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
73e0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
73f0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
7400: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
7410: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
7420: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
7430: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
7440: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
7450: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
7460: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
7470: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
7480: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
7490: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
74a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
74b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
74c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
74d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
74e0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
74f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7500: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
7510: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
7520: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
7530: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
7540: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
7550: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51  closed.  The [SQ
7560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7570: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
7580: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
7590: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
75a0: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
75b0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
75c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
75d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
75e0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
75f0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7600: 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69  d.** for exclusi
7610: 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73  ve access.  This
7620: 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72   flag is set for
7630: 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70   all files excep
7640: 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69  t.** for the mai
7650: 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
7660: 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20  .**.** At least 
7670: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
7680: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
7690: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
76a0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
76b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
76c0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
76d0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
76e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
76f0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
7700: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
7710: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
7720: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
7730: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
7740: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a   fill it in..**.
7750: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7760: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
7770: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
7780: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
7790: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
77a0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
77b0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
77c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
77d0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
77e0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
77f0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
7800: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
7810: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7820: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
7830: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
7840: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
7850: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
7860: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
7870: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ry..**.** SQLite
7880: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
7890: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
78a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
78b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
78c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
78d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
78e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
78f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
7900: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
7910: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
7920: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
7930: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
7940: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
7950: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
7960: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
7970: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
7980: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
7990: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
79a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
79b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
79c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
79d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
79e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
79f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
7a00: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
7a10: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
7a20: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
7a30: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
7a40: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
7a50: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
7a60: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
7a70: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
7a80: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
7a90: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
7aa0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
7ab0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
7ac0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
7ad0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
7ae0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
7af0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
7b00: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
7b10: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
7b20: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
7b30: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
7b40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
7b50: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
7b60: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
7b70: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
7b80: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
7b90: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
7ba0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
7bb0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
7bc0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
7bd0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
7be0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
7bf0: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
7c00: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
7c10: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
7c20: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
7c30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
7c40: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  e and time..**.*
7c50: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7c60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
7c70: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
7c80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
7c90: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
7ca0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
7cb0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
7cc0: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73  umber */.  int s
7cd0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
7ce0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
7cf0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
7d00: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
7d10: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
7d20: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
7d30: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
7d40: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
7d50: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
7d60: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
7d70: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
7d80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
7d90: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
7da0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
7db0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
7dc0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
7dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
7de0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
7df0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
7e00: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
7e10: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
7e20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
7e30: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
7e40: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
7e50: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
7e60: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
7e70: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
7e80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
7e90: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
7ea0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
7eb0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
7ec0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
7ed0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
7ee0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
7ef0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
7f00: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
7f10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
7f20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
7f30: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
7f40: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
7f50: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
7f60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
7f70: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
7f80: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
7f90: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
7fa0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
7fb0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
7fc0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
7fd0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
7fe0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
7ff0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
8000: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8010: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8020: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8030: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8040: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8050: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8060: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8070: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
8080: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
8090: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
80a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
80b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
80c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
80d0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
80e0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
80f0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
8100: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
8110: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
8120: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
8130: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
8140: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
8150: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
8160: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
8170: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8180: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
8190: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
81a0: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31  hod {H11190} <H1
81b0: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1140>.**.** Thes
81c0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
81d0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
81e0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
81f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
8200: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8210: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
8220: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
8230: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
8240: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
8250: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
8260: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8270: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
8280: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
8290: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
82a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
82b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
82c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
82d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
82e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
82f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8300: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8310: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
8320: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  r the file is bo
8330: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
8340: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74  writable..** Wit
8350: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8360: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
8370: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8380: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8390: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
83a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
83b0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
83c0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
83d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
83e0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
83f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8400: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
8410: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
8420: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
8430: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30   Library {H10130
8440: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30  } <S20000><S3010
8450: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
8460: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8470: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
8480: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
8490: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
84a0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
84b0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
84c0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
84d0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
84e0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
84f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8500: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
8510: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
8520: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
8530: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8540: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
8550: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
8560: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8570: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
8580: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
8590: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
85a0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
85b0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
85c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
85d0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
85e0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
85f0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
8600: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
8610: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
8620: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
8630: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
8640: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
8650: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
8660: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
8670: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a  armless no-ops..
8680: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
8690: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65  r things, sqlite
86a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
86b0: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  hall invoke.** s
86c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
86d0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71  .  Similarly, sq
86e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
86f0: 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  .** shall invoke
8700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
8710: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
8720: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8730: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
8740: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
8750: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20   success..** If 
8760: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
8770: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8780: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
8790: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
87a0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
87b0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
87c0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
87d0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
87e0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
87f0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
8800: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
8810: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
8820: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  TE_OK]..**.** Th
8830: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
8840: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
8850: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
8860: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
8870: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
8880: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
8890: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
88a0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
88b0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
88c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
88d0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
88e0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
88f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
8900: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
8910: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
8920: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
8930: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
8940: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
8950: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
8960: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
8970: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
8980: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
8990: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
89a0: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51    However, if SQ
89b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
89c0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
89d0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
89e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
89f0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
8a00: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
8a10: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
8a20: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
8a30: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
8a40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8a50: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
8a60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
8a70: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
8a80: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
8a90: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
8aa0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
8ab0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
8ac0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
8ad0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
8ae0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
8af0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
8b00: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
8b10: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
8b20: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
8b30: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
8b40: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
8b50: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
8b60: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
8b70: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
8b80: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
8b90: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
8ba0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
8bb0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
8bc0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
8bd0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
8be0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
8bf0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
8c00: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
8c10: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
8c20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
8c30: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
8c40: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
8c50: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
8c60: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
8c70: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
8c80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
8c90: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
8ca0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
8cb0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
8cc0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
8cd0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
8ce0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
8cf0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
8d00: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
8d10: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
8d20: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
8d30: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
8d40: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
8d50: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
8d60: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
8d70: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
8d80: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
8d90: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
8da0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
8db0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
8dc0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
8dd0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
8de0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
8df0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
8e00: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
8e10: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
8e20: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
8e30: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
8e40: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
8e50: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
8e60: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
8e70: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
8e80: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
8e90: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
8ea0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
8eb0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
8ec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8ed0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
8ee0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
8ef0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
8f00: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
8f10: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
8f20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
8f30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
8f40: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
8f50: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
8f60: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
8f70: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
8f80: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69  led for unix, wi
8f90: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a  ndows, or os/2..
8fa0: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f  ** When built fo
8fb0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
8fc0: 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  s (using the [SQ
8fd0: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
8fe0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
8ff0: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
9000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
9010: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
9020: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
9030: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
9040: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
9050: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
9060: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
9070: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
9080: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
9090: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
90a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
90b0: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
90c0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
90d0: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
90e0: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
90f0: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
9100: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
9110: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
9120: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
9130: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
9140: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
9150: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
9160: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9170: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
9180: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
9190: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
91a0: 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20  ibrary {H14100} 
91b0: 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e  <S20000><S30200>
91c0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
91d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
91e0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
91f0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
9200: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
9210: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
9220: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
9230: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
9240: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
9250: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
9260: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
9270: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
9280: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
9290: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
92a0: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
92b0: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
92c0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
92d0: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
92e0: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
92f0: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
9300: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
9310: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
9320: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
9330: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
9340: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
9350: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
9360: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
9370: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
9380: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
9390: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
93a0: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
93b0: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
93c0: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
93d0: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
93e0: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
93f0: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
9400: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
9410: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
9420: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
9430: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
9440: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
9450: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
9460: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
9470: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
9480: 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  n()]..** Note, h
9490: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c  owever, that sql
94a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
94b0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
94c0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
94d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
94e0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
94f0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
9500: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
9510: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
9520: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
9530: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
9540: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
9550: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
9560: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
9570: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
9580: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
9590: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
95a0: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
95b0: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
95c0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
95d0: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
95e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
95f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
9600: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
9610: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
9620: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
9630: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
9640: 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72   When a configur
9650: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
9660: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
9670: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
9680: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66  QLITE_OK]..** If
9690: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
96a0: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
96b0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
96c0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
96d0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
96e0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
96f0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
9700: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
9710: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30  ments:.** [H1410
9720: 33 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34  3] [H14106] [H14
9730: 31 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48  120] [H14123] [H
9740: 31 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20  14126] [H14129] 
9750: 5b 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35  [H14132] [H14135
9760: 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48  ].** [H14138] [H
9770: 31 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20  14141] [H14144] 
9780: 5b 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30  [H14147] [H14150
9790: 5d 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31  ] [H14153] [H141
97a0: 35 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20  56] [H14159].** 
97b0: 5b 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35  [H14162] [H14165
97c0: 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51  ] [H14168].*/.SQ
97d0: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
97e0: 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  L int sqlite3_co
97f0: 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
9800: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9810: 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
9820: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
9830: 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30   {H14200} <S2000
9840: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
9850: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  AL.**.** The sql
9860: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
9870: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
9880: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
9890: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
98a0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
98b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
98c0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
98d0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
98e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
98f0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
9900: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
9910: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
9920: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
9930: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
9940: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
9950: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
9960: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
9970: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
9980: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  an only be used 
9990: 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
99a0: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
99b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
99c0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
99d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a  qlite3_open()],.
99e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
99f0: 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
9a00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
9a10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
9a20: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
9a30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
9a40: 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
9a50: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
9a60: 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65  n verb - an inte
9a70: 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e  ger code that in
9a80: 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20  dicates what.** 
9a90: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
9aa0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9ab0: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
9ac0: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20  figured..** The 
9ad0: 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20  only choice for 
9ae0: 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53  this value is [S
9af0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
9b00: 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65  OOKASIDE]..** Ne
9b10: 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65  w verbs are like
9b20: 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69  ly to be added i
9b30: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
9b40: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
9b50: 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  Additional argum
9b60: 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74  ents depend on t
9b70: 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52  he verb..**.** R
9b80: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
9b90: 5b 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36  [H14203] [H14206
9ba0: 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32  ] [H14209] [H142
9bb0: 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a  12] [H14215].*/.
9bc0: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
9bd0: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
9be0: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
9bf0: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
9c00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9c10: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
9c20: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48  tion Routines {H
9c30: 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a  10155} <S20120>.
9c40: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
9c50: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
9c60: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
9c70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
9c80: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
9c90: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
9ca0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
9cb0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
9cc0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
9cd0: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
9ce0: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
9cf0: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
9d00: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
9d10: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
9d20: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
9d30: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
9d40: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
9d50: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
9d60: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
9d70: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
9d80: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
9d90: 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61  ALLOC].  By crea
9da0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
9db0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
9dc0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
9dd0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
9de0: 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63  nfig()] during c
9df0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
9e00: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
9e10: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
9e20: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
9e30: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
9e40: 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51  system.** for SQ
9e50: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
9e60: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
9e70: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
9e80: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
9e90: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
9ea0: 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65  th a built-in me
9eb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
9ec0: 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63  hat is.** perfec
9ed0: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
9ee0: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
9ef0: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
9f00: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
9f10: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
9f20: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
9f30: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
9f40: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
9f50: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
9f60: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
9f70: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
9f80: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
9f90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
9fa0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
9fb0: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
9fc0: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
9fd0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
9fe0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
9ff0: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
a000: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
a010: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
a020: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
a030: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
a040: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
a050: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
a060: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
a070: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
a080: 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e  alloc, xFree, an
a090: 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  d xRealloc metho
a0a0: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
a0b0: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
a0c0: 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72  ), free(), and r
a0d0: 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f  ealloc() functio
a0e0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
a0f0: 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  dard library..**
a100: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
a110: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
a120: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
a130: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a140: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
a150: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
a160: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
a170: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
a180: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
a190: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
a1a0: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
a1b0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
a1c0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
a1d0: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
a1e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
a1f0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
a200: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
a210: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
a220: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
a230: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
a240: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
a250: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
a260: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
a270: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
a280: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
a290: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
a2a0: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
a2b0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
a2c0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
a2d0: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
a2e0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
a2f0: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
a300: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
a310: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
a320: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
a330: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
a340: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
a350: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
a360: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
a370: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
a380: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
a390: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
a3a0: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
a3b0: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
a3c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a3d0: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
a3e0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
a3f0: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
a400: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
a410: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
a420: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
a430: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
a440: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
a450: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74   xShutdown..*/.t
a460: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
a470: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
a480: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
a490: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
a4a0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
a4b0: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
a4c0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
a4d0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
a4e0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
a4f0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
a500: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
a510: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
a520: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
a530: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
a540: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
a550: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
a560: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
a570: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
a580: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
a590: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
a5a0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
a5b0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
a5c0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
a5d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
a5e0: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
a5f0: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
a600: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
a610: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
a620: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
a630: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
a640: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
a650: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
a660: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
a670: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
a680: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
a690: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
a6a0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
a6b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
a6c0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
a6d0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
a6e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
a6f0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
a700: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
a710: 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10160} <S20000>.
a720: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
a730: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
a740: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
a750: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
a760: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a770: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
a780: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
a790: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a7a0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
a7b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
a7c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
a7d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a7e0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
a7f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
a800: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
a810: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
a820: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a830: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
a840: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
a850: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
a860: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
a870: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
a880: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
a890: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
a8a0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
a8b0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
a8c0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
a8d0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
a8e0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
a8f0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
a900: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
a910: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
a920: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a930: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
a940: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
a950: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
a960: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
a970: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
a980: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
a990: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
a9a0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
a9b0: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  n disables.** al
a9c0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
a9d0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
a9e0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
a9f0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
aa00: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
aa10: 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  thread.</dd>.**.
aa20: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
aa30: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
aa40: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
aa50: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
aa60: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
aa70: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
aa80: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
aa90: 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
aaa0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
aab0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
aac0: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
aad0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
aae0: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
aaf0: 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
ab00: 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
ab10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ab20: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
ab30: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
ab40: 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
ab50: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
ab60: 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
ab70: 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
ab80: 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
ab90: 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
aba0: 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
abb0: 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
abc0: 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
abd0: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
abe0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
abf0: 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
ac00: 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20   time.  See the 
ac10: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
ac20: 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  .** documentatio
ac30: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
ac40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64   information.</d
ac50: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ac60: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
ac70: 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
ac80: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
ac90: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
aca0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
acb0: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
acc0: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
acd0: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
ace0: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
acf0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
ad00: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
ad10: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ad20: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
ad30: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
ad40: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
ad50: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ad60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ad70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
ad80: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
ad90: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
ada0: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
adb0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
adc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
add0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
ade0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
adf0: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
ae00: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
ae10: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
ae20: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ae30: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
ae40: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
ae50: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
ae60: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
ae70: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
ae80: 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  e..** See the [t
ae90: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
aea0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
aeb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
aec0: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  rmation.</dd>.**
aed0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
aee0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
aef0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
af00: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
af10: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
af20: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
af30: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
af40: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
af50: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
af60: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
af70: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
af80: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
af90: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
afa0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
afb0: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
afc0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
afd0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
afe0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
aff0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
b000: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b010: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
b020: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
b030: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b040: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
b050: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
b060: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b070: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
b080: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
b090: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
b0a0: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
b0b0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
b0c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
b0d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b0e0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
b0f0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
b100: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
b110: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
b120: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
b130: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
b140: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
b150: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
b160: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
b170: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
b180: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b190: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
b1a0: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
b1b0: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
b1c0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b1d0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
b1e0: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
b1f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b200: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
b210: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
b220: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
b230: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
b240: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
b250: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
b260: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
b270: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b280: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
b290: 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74  When disabled, t
b2a0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
b2b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
b2c0: 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70  ecome .** non-op
b2d0: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
b2e0: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
b2f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
b300: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
b310: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
b320: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
b330: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
b340: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
b350: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
b360: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
b370: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
b380: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
b390: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b3a0: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
b3b0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
b3c0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
b3d0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
b3e0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
b3f0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
b400: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
b410: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
b420: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
b430: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
b440: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
b450: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
b460: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
b470: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
b480: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
b490: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
b4a0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
b4b0: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61   16. The sz para
b4c0: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
b4d0: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c  a few bytes.** l
b4e0: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61  arger than the a
b4f0: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70  ctual scratch sp
b500: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65  ace required due
b510: 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65   internal overhe
b520: 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ad..** The first
b530: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
b540: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
b550: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
b560: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
b570: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
b580: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
b590: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  no more than one
b5a0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
b5b0: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65  at once per thre
b5c0: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75  ad, so.** N shou
b5d0: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
b5e0: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
b5f0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
b600: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  ads.  The sz.** 
b610: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b620: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
b630: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
b640: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
b650: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
b660: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
b670: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
b680: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
b690: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
b6a0: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
b6b0: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
b6c0: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
b6d0: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
b6e0: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
b6f0: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
b700: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
b710: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
b720: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
b730: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
b740: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b750: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
b760: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
b770: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b780: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
b790: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
b7a0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b7b0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
b7c0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
b7d0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
b7e0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
b7f0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
b800: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
b810: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
b820: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20  implemenation.  
b830: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
b840: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
b850: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
b860: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
b870: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
b880: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b890: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
b8a0: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
b8b0: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e  G_PCACHE option.
b8c0: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
b8d0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
b8e0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
b8f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
b900: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
b910: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
b920: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
b930: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
b940: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
b950: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73   sz argument mus
b960: 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20  t be a power of 
b970: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
b980: 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20  and 32768.  The 
b990: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
b9a0: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
b9b0: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
b9c0: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
b9d0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
b9e0: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ..** SQLite will
b9f0: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
ba00: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
ba10: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
ba20: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
ba30: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
ba40: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
ba50: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
ba60: 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61   to cache.  If a
ba70: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
ba80: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
ba90: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
baa0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
bab0: 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
bac0: 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
bad0: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
bae0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
baf0: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
bb00: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
bb10: 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
bb20: 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65  on might use one
bb30: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
bb40: 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c  N buffers to hol
bb50: 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63  d .** memory acc
bb60: 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74  ounting informat
bb70: 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ion. </dd>.**.**
bb80: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
bb90: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
bba0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bbb0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
bbc0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
bbd0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
bbe0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
bbf0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
bc00: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
bc10: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
bc20: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
bc30: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
bc40: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
bc50: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
bc60: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
bc70: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
bc80: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
bc90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
bca0: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72  mory, the number
bcb0: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
bcc0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
bcd0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
bce0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
bcf0: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66  ze.  If.** the f
bd00: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
bd10: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
bd20: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
bd30: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
bd40: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
bd50: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
bd60: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
bd70: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
bd80: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
bd90: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
bda0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
bdb0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bdc0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65  MALLOC].  If the
bdd0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
bde0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
bdf0: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
be00: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
be10: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
be20: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
be30: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
be40: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
be50: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
be60: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
be70: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
be80: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
be90: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
bea0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
beb0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
bec0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
bed0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
bee0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
bef0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
bf00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
bf10: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
bf20: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
bf30: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
bf40: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
bf50: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
bf60: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
bf70: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
bf80: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
bf90: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
bfa0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
bfb0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
bfc0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
bfd0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
bfe0: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
bff0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c000: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
c010: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
c020: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c030: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
c040: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
c050: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
c060: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
c070: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
c080: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
c090: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
c0a0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
c0b0: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
c0c0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c0d0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c0e0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c0f0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
c100: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
c110: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c120: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
c130: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
c140: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
c150: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
c160: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
c170: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  xample.</dd>.**.
c180: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c190: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
c1a0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c1b0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
c1c0: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
c1d0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
c1e0: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
c1f0: 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73  allcation lookas
c200: 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ide optimization
c210: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
c220: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
c230: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
c240: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
c250: 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
c260: 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
c270: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
c280: 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
c290: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c2a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
c2b0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c2c0: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
c2d0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c2e0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c2f0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c300: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
c310: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
c320: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
c330: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
c340: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
c350: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
c360: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
c370: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
c380: 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  n.  SQLite makes
c390: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
c3a0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
c3b0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
c3c0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
c3d0: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
c3e0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c3f0: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
c400: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c410: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
c420: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
c430: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
c440: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
c450: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
c460: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
c470: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
c480: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
c490: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
c4a0: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
c4b0: 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
c4c0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
c4d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c4e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
c4f0: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
c500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c510: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
c520: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
c530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c540: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
c550: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
c560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c570: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
c580: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
c590: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
c5a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c5b0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
c5c0: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
c5d0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
c5e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c5f0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
c600: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
c610: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
c620: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
c630: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
c640: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
c650: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
c660: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
c670: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
c680: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
c690: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
c6a0: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
c6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c6c0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
c6d0: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
c6e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c6f0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
c700: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
c710: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c720: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c730: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
c740: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
c750: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
c760: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
c770: 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
c780: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
c790: 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
c7a0: 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
c7b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c7c0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
c7d0: 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
c7e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c7f0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
c800: 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
c810: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
c820: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
c830: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
c840: 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
c850: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
c860: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f  e_methods* */../
c870: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
c880: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
c890: 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53  ions {H10170} <S
c8a0: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
c8b0: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
c8c0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
c8d0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
c8e0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
c8f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
c900: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
c910: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
c920: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
c930: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c940: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
c950: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
c960: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c970: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
c980: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
c990: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
c9a0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
c9b0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
c9c0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
c9d0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
c9e0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
c9f0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
ca00: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ca10: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
ca20: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
ca30: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
ca40: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
ca50: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
ca60: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
ca70: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
ca80: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
ca90: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
caa0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
cab0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
cac0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
cad0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
cae0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
caf0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
cb00: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
cb10: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
cb20: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
cb30: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
cb40: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
cb50: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
cb60: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
cb70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
cb80: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
cb90: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
cba0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
cbb0: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
cbc0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
cbd0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
cbe0: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
cbf0: 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
cc00: 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
cc10: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20  okaside memory. 
cc20: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
cc30: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55  gument may be NU
cc40: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
cc50: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
cc60: 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73  ocate the lookas
cc70: 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74  ide.** buffer it
cc80: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
cc90: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
cca0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
ccb0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
ccc0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
ccd0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
cce0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61   and the third a
ccf0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
cd00: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
cd10: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
cd20: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
cd30: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
cd40: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
cd50: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
cd60: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
cd70: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
cd80: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
cd90: 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ts.</dd>.**.** <
cda0: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
cdb0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cdc0: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30  LOOKASIDE    100
cdd0: 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
cde0: 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  int */.../*.** C
cdf0: 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
ce00: 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
ce10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
ce20: 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30   {H12200} <S1070
ce30: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
ce40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
ce50: 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
ce60: 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
ce70: 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
ce80: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
ce90: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
cea0: 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65  of SQLite. The e
ceb0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
cec0: 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
ced0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
cee0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
cef0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e  ompatibility con
cf00: 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  siderations..**.
cf10: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
cf20: 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 5b 48 31  .** [H12201] [H1
cf30: 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2202].*/.int sql
cf40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
cf50: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
cf60: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
cf70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cf80: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
cf90: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31  wid {H12220} <S1
cfa0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68  0700>.**.** Each
cfb0: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
cfc0: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
cfd0: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
cfe0: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
cff0: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
d000: 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
d010: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61  . The rowid is a
d020: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
d030: 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
d040: 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
d050: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
d060: 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
d070: 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
d080: 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
d090: 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
d0a0: 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
d0b0: 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61  ns. If.** the ta
d0c0: 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
d0d0: 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
d0e0: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
d0f0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
d100: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
d110: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
d120: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
d130: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
d140: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
d150: 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
d160: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
d170: 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
d180: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
d190: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d1a0: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
d1b0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
d1c0: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
d1d0: 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
d1e0: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
d1f0: 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
d200: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
d210: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
d220: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53  **.** If an [INS
d230: 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
d240: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
d250: 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  en the [rowid] o
d260: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
d270: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  * row is returne
d280: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
d290: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
d2a0: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e   trigger is runn
d2b0: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
d2c0: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
d2d0: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
d2e0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
d2f0: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
d300: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
d310: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
d320: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  d before the tri
d330: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
d340: 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68  * An [INSERT] th
d350: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
d360: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
d370: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
d380: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
d390: 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
d3a0: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
d3b0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
d3c0: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
d3d0: 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f  .  Thus INSERT O
d3e0: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
d3f0: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
d400: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
d410: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
d420: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
d430: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
d440: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
d450: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
d460: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
d470: 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e   fails.  When IN
d480: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
d490: 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
d4a0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
d4b0: 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
d4c0: 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
d4d0: 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
d4e0: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
d4f0: 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
d500: 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
d510: 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
d520: 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
d530: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
d540: 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
d550: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
d560: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
d570: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  erface..**.** Fo
d580: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
d590: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
d5a0: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
d5b0: 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
d5c0: 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
d5d0: 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
d5e0: 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
d5f0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  back..**.** Requ
d600: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
d610: 32 32 32 31 5d 20 5b 48 31 32 32 32 33 5d 0a 2a  2221] [H12223].*
d620: 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
d630: 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
d640: 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
d650: 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
d660: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d670: 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
d680: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
d690: 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
d6a0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
d6b0: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
d6c0: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
d6d0: 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
d6e0: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
d6f0: 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
d700: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
d710: 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
d720: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
d730: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
d740: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
d750: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
d760: 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
d770: 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
d780: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
d790: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
d7a0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
d7b0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
d7c0: 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
d7d0: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31  ows Modified {H1
d7e0: 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a  2240} <S10600>.*
d7f0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
d800: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
d810: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
d820: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
d830: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
d840: 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
d850: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
d860: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
d870: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
d880: 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
d890: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d8a0: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
d8b0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
d8c0: 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ..** Only change
d8d0: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
d8e0: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
d8f0: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
d900: 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
d910: 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
d920: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
d930: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
d940: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
d950: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
d960: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65  counted. Use the
d970: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
d980: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
d990: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  ion.** to find t
d9a0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
d9b0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75  of changes inclu
d9c0: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
d9d0: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e  sed by triggers.
d9e0: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68  .**.** A "row ch
d9f0: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
da00: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
da10: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
da20: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
da30: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
da40: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
da50: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
da60: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
da70: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
da80: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  ts of REPLACE co
da90: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
daa0: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
dab0: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
dac0: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20  ng, DROP TABLE, 
dad0: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
dae0: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
daf0: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
db00: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
db10: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
db20: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
db30: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
db40: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
db50: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
db60: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
db70: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20   trigger.  Most 
db80: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
db90: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
dba0: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
dbb0: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
dbc0: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
dbd0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
dbe0: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
dbf0: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
dc00: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
dc10: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
dc20: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
dc30: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
dc40: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
dc50: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
dc60: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
dc70: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
dc80: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
dc90: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** Calling [sql
dca0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
dcb0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
dcc0: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
dcd0: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
dce0: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
dcf0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ntext..**.** Thi
dd00: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
dd10: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
dd20: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
dd30: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
dd40: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
dd50: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
dd60: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
dd70: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
dd80: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
dd90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68  ..**.** Thus, wh
dda0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
ddb0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
ddc0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
ddd0: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
dde0: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
ddf0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
de00: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
de10: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
de20: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
de30: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
de40: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  .  Within the bo
de50: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
de60: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
de70: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
de80: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
de90: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
dea0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
deb0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
dec0: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
ded0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
dee0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
def0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
df00: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
df10: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
df20: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
df30: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
df40: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
df50: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
df60: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
df70: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
df80: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
df90: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
dfa0: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
dfb0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
dfc0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
dfd0: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
dfe0: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
dff0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
e000: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 44 6f 69   the table.  Doi
e010: 6e 67 20 73 6f 20 69 73 20 6d 75 63 68 20 66 61  ng so is much fa
e020: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
e030: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
e040: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
e050: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
e060: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 42 65 63   the table.  Bec
e070: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
e080: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
e090: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22  e deletions in "
e0a0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
e0b0: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
e0c0: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69  hanges and.** wi
e0d0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
e0e0: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
e0f0: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
e100: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e110: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  nges()].** funct
e120: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73  ions, regardless
e130: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e140: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
e150: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  were originally.
e160: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ** in the table.
e170: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75    To get an accu
e180: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
e190: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
e1a0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
e1b0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
e1c0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
e1d0: 74 65 61 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70  tead.  Or recomp
e1e0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
e1f0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
e200: 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54  UNCATE_OPTIMIZAT
e210: 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ION] compile-tim
e220: 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61  e option to disa
e230: 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d  ble the.** optim
e240: 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71  ization on all q
e250: 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ueries..**.** Re
e260: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
e270: 48 31 32 32 34 31 5d 20 5b 48 31 32 32 34 33 5d  H12241] [H12243]
e280: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
e290: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
e2a0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
e2b0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
e2c0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
e2d0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
e2e0: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
e2f0: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
e300: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
e310: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
e320: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
e330: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
e340: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
e350: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
e360: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
e370: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
e380: 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30  ed {H12260} <S10
e390: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
e3a0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e3b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
e3c0: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
e3d0: 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20  d by INSERT,.** 
e3e0: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
e3f0: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
e400: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
e410: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
e420: 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63  opened..** The c
e430: 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c  ount includes al
e440: 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61  l changes from a
e450: 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ll trigger conte
e460: 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  xts.  However,.*
e470: 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
e480: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
e490: 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
e4a0: 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63  lement REPLACE c
e4b0: 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
e4c0: 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
e4d0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
e4e0: 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70   or DROP table p
e4f0: 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68  rocessing..** Th
e500: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
e510: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
e520: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
e530: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
e540: 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28  s.** completed (
e550: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
e560: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73  nt handle is pas
e570: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
e580: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
e590: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
e5a0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ()])..**.** SQLi
e5b0: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
e5c0: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
e5d0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
e5e0: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
e5f0: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
e600: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
e610: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
e620: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
e630: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
e640: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
e650: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
e660: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
e670: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
e680: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
e690: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
e6a0: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22  e deletions in "
e6b0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
e6c0: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
e6d0: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69  hanges and.** wi
e6e0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
e6f0: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
e700: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
e710: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e720: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  nges()].** funct
e730: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73  ions, regardless
e740: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e750: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
e760: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  were originally.
e770: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ** in the table.
e780: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75    To get an accu
e790: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
e7a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
e7b0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
e7c0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
e7d0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
e7e0: 74 65 61 64 2e 20 20 20 4f 72 20 72 65 63 6f 6d  tead.   Or recom
e7f0: 70 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  pile using the.*
e800: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  * [SQLITE_OMIT_T
e810: 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41  RUNCATE_OPTIMIZA
e820: 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TION] compile-ti
e830: 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73  me option to dis
e840: 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69  able the.** opti
e850: 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20  mization on all 
e860: 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 53  queries..**.** S
e870: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
e880: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
e890: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
e8a0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
e8b0: 2a 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32  * [H12261] [H122
e8c0: 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  63].**.** If a s
e8d0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
e8e0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
e8f0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
e900: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
e910: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
e920: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
e930: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
e940: 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
e950: 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
e960: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
e970: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
e980: 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
e990: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
e9a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e9b0: 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
e9c0: 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
e9d0: 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30  ry {H12270} <S30
e9e0: 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
e9f0: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
ea00: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
ea10: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
ea20: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
ea30: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
ea40: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
ea50: 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
ea60: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
ea70: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
ea80: 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
ea90: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
eaa0: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
eab0: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
eac0: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
ead0: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
eae0: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
eaf0: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
eb00: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20  *.** It is safe 
eb10: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
eb20: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
eb30: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
eb40: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
eb50: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
eb60: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
eb70: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
eb80: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
eb90: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
eba0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
ebb0: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
ebc0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
ebd0: 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
ebe0: 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
ebf0: 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
ec00: 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
ec10: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20  **.** If an SQL 
ec20: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
ec30: 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
ec40: 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
ec50: 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
ec60: 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
ec70: 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
ec80: 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
ec90: 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
eca0: 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
ecb0: 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
ecc0: 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
ecd0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f  ..**.** An SQL o
ece0: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
ecf0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
ed00: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
ed10: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
ed20: 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
ed30: 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
ed40: 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
ed50: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
ed60: 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
ed70: 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
ed80: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
ed90: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
eda0: 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
edb0: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
edc0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
edd0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ede0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
edf0: 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  ) has no effect 
ee00: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
ee10: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
ee20: 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  arted after sqli
ee30: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
ee40: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52  returns..**.** R
ee50: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
ee60: 5b 48 31 32 32 37 31 5d 20 5b 48 31 32 32 37 32  [H12271] [H12272
ee70: 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ].**.** If the d
ee80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ee90: 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
eea0: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
eeb0: 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
eec0: 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
eed0: 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
eee0: 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
eef0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ef00: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
ef10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
ef20: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
ef30: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
ef40: 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d  omplete {H10510}
ef50: 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70200>.**.** 
ef60: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
ef70: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
ef80: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
ef90: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
efa0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
efb0: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
efc0: 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d  eems to form com
efd0: 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74  plete a SQL stat
efe0: 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
eff0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
f000: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
f010: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
f020: 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
f030: 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54   for parsing.  T
f040: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
f050: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
f060: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
f070: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
f080: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
f090: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
f0a0: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
f0b0: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
f0c0: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
f0d0: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
f0e0: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
f0f0: 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a   fragment of a.*
f100: 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  * CREATE TRIGGER
f110: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
f120: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
f130: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
f140: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
f150: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
f160: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
f170: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
f180: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
f190: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
f1a0: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
f1b0: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
f1c0: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
f1d0: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
f1e0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
f1f0: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
f200: 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tor..**.** These
f210: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
f220: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
f230: 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
f240: 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
f250: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
f260: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
f270: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
f280: 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30  s: [H10511] [H10
f290: 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  512].**.** The i
f2a0: 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
f2b0: 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
f2c0: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
f2d0: 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
f2e0: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
f2f0: 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
f300: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
f310: 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
f320: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
f330: 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
f340: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
f350: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
f360: 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
f370: 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
f380: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f390: 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
f3a0: 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
f3b0: 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
f3c0: 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
f3d0: 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
f3e0: 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d   Errors {H12310}
f3f0: 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40400>.**.** 
f400: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
f410: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
f420: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
f430: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
f440: 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
f450: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
f460: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
f470: 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
f480: 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
f490: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
f4a0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62  ..**.** If the b
f4b0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
f4c0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
f4d0: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
f4e0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
f4f0: 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
f500: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
f510: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
f520: 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65  the lock. If the
f530: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
f540: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
f550: 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
f560: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
f570: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
f580: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nts..**.** The f
f590: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
f5a0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
f5b0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
f5c0: 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
f5d0: 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
f5e0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
f5f0: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
f600: 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  er().  The secon
f610: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
f620: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c   the handler cal
f630: 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
f640: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
f650: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
f660: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
f670: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
f680: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
f690: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
f6a0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
f6b0: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
f6c0: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
f6d0: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
f6e0: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
f6f0: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
f700: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
f710: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
f720: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
f730: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
f740: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
f750: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
f760: 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
f770: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
f780: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
f790: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
f7a0: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
f7b0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
f7c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
f7d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
f7e0: 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
f7f0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
f800: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
f810: 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c  ntention. If SQL
f820: 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
f830: 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
f840: 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
f850: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
f860: 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
f870: 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
f880: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
f890: 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
f8a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
f8b0: 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
f8c0: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
f8d0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
f8e0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
f8f0: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
f900: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
f910: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
f920: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
f930: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
f940: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
f950: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
f960: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
f970: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
f980: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
f990: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
f9a0: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
f9b0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
f9c0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
f9d0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
f9e0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
f9f0: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
fa00: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
fa10: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
fa20: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
fa30: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
fa40: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
fa50: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
fa60: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
fa70: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
fa80: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
fa90: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
faa0: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
fab0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
fac0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
fad0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
fae0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
faf0: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
fb00: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
fb10: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
fb20: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
fb30: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
fb40: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
fb50: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
fb60: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
fb70: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
fb80: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
fb90: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
fba0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
fbb0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
fbc0: 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
fbd0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
fbe0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
fbf0: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
fc00: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
fc10: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
fc20: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
fc30: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
fc40: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
fc50: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
fc60: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
fc70: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
fc80: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
fc90: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
fca0: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
fcb0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
fcc0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
fcd0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
fce0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
fcf0: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
fd00: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
fd10: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
fd20: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
fd30: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
fd40: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
fd50: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
fd60: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
fd70: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
fd80: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
fd90: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
fda0: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
fdb0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
fdc0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
fdd0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
fde0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
fdf0: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
fe00: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
fe10: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
fe20: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
fe30: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
fe40: 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
fe50: 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
fe60: 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
fe70: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
fe80: 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
fe90: 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
fea0: 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
feb0: 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
fec0: 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
fed0: 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
fee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
fef0: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
ff00: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
ff10: 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
ff20: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
ff30: 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
ff40: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
ff50: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
ff60: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
ff70: 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74  et handler.  Not
ff80: 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
ff90: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
ffa0: 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
ffb0: 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
ffc0: 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
ffd0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
ffe0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
fff0: 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
10000 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
10010 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
10020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
10030 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
10040 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
10050 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
10060 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
10070 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
10080 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65  ..** .** Require
10090 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31  ments:.** [H1231
100a0 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32  1] [H12312] [H12
100b0 33 31 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48  314] [H12316] [H
100c0 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62  12318].**.** A b
100d0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
100e0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
100f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10100 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
10110 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
10120 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
10130 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
10140 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
10150 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
10160 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
10170 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
10180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
10190 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
101a0 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
101b0 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
101c0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
101d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
101e0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
101f0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
10200 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
10210 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
10220 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
10230 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
10240 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
10250 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
10260 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
10270 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
10280 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
10290 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
102a0 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
102b0 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
102c0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
102d0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
102e0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
102f0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
10300 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
10310 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
10320 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
10330 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
10340 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
10350 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
10360 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
10370 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
10380 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
10390 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
103a0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
103b0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
103c0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
103d0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
103e0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
103f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10400 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
10410 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
10420 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
10430 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
10440 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
10450 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
10460 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
10470 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
10480 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
10490 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
104a0 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ared..**.** Requ
104b0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
104c0 32 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b  2341] [H12343] [
104d0 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H12344].*/.int s
104e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
104f0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
10500 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
10510 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
10520 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
10530 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
10540 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30   {H12370} <S1000
10550 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0>.**.** Definit
10560 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
10570 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
10580 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
10590 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
105a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
105b0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
105c0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
105d0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
105e0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
105f0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
10600 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
10610 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
10620 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
10630 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
10640 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
10650 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
10660 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
10670 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
10680 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
10690 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
106a0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
106b0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
106c0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
106d0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
106e0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
106f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
10700 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
10710 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
10720 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
10730 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
10740 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
10750 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
10760 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
10770 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
10780 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
10790 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
107a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
107b0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
107c0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
107d0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
107e0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
107f0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
10800 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
10810 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
10820 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
10830 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
10840 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
10850 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
10860 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
10870 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
10880 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
10890 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
108a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
108b0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
108c0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
108d0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
108e0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
108f0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
10900 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
10910 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
10920 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
10930 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
10940 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10950 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
10960 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
10970 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
10980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
10990 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
109a0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
109b0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
109c0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
109d0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
109e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
109f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
10a00 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
10a10 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
10a20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
10a30 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
10a40 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
10a50 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
10a60 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
10a70 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
10a80 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
10a90 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
10aa0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
10ab0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
10ac0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
10ad0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
10ae0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
10af0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
10b00 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
10b10 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
10b20 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
10b30 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
10b40 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
10b50 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
10b60 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
10b70 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
10b80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10b90 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
10ba0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10bb0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
10bc0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
10bd0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
10be0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
10bf0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
10c00 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
10c10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
10c20 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
10c30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
10c40 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
10c50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
10c60 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
10c70 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
10c80 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
10c90 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
10ca0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
10cb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
10cc0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
10cd0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
10ce0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
10cf0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
10d00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
10d10 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
10d20 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
10d30 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
10d40 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
10d50 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
10d60 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
10d70 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
10d80 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
10d90 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
10da0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
10db0 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
10dc0 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
10dd0 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
10de0 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
10df0 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
10e00 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
10e10 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
10e20 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
10e30 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
10e40 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
10e50 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
10e60 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
10e70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10e80 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
10e90 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
10ea0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
10eb0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
10ec0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
10ed0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
10ee0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
10ef0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
10f00 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
10f10 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
10f20 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
10f30 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
10f40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10f50 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
10f60 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
10f70 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
10f80 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
10f90 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
10fa0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
10fb0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
10fc0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
10fd0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
10fe0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
10ff0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
11000 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
11010 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
11020 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
11030 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
11040 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
11050 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
11060 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
11070 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
11080 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
11090 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
110a0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
110b0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
110c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
110d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
110e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
110f0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
11100 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
11110 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 33  * [H12371] [H123
11120 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 31  73] [H12374] [H1
11130 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b  2376] [H12379] [
11140 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12382].*/.int s
11150 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11160 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
11170 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
11180 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
11190 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
111a0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
111b0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
111c0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
111d0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
111e0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
111f0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
11200 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
11210 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
11220 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
11230 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
11240 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
11250 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
11260 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
11270 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
11280 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
11290 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
112a0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
112b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
112c0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
112d0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
112e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
112f0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
11300 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
11310 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30  {H17400} <S70000
11320 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20000>.**.** 
11330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11340 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
11350 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
11360 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
11370 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
11380 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11390 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
113a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
113b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
113c0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
113d0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
113e0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
113f0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
11400 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11410 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
11420 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
11430 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
11440 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
11450 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
11460 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42  ite3_free()].  B
11470 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
11480 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
11490 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
114a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
114b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
114c0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
114d0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
114e0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
114f0 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65  .**.** In sqlite
11500 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
11510 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
11520 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
11530 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
11540 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
11550 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
11560 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
11570 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
11580 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
11590 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
115a0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
115b0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
115c0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
115d0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
115e0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
115f0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
11600 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
11610 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
11620 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
11630 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
11640 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
11650 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
11660 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
11670 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
11680 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
11690 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
116a0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
116b0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
116c0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
116d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
116e0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
116f0 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
11700 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
11710 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
11720 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
11730 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
11740 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
11750 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
11760 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
11770 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
11780 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11790 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
117a0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
117b0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
117c0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
117d0 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
117e0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
117f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
11800 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
11810 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
11820 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
11830 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
11840 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
11850 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
11860 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
11870 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
11880 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
11890 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
118a0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
118b0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
118c0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
118d0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
118e0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
118f0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
11900 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
11910 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11920 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
11930 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
11940 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
11950 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
11960 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
11970 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
11980 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
11990 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
119a0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
119b0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
119c0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
119d0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
119e0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
119f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11a00 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
11a10 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
11a20 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
11a30 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
11a40 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
11a50 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
11a60 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
11a70 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
11a80 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
11a90 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
11aa0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
11ab0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
11ac0 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
11ad0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
11ae0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
11af0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
11b00 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
11b10 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
11b20 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
11b30 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
11b40 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
11b50 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
11b60 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
11b70 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
11b80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
11b90 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
11ba0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
11bb0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
11bc0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11bd0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
11be0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
11bf0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
11c00 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
11c10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
11c20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
11c30 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
11c40 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
11c50 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
11c60 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
11c70 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
11c80 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
11c90 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
11ca0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
11cb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
11cc0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
11cd0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
11ce0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
11cf0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
11d00 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
11d10 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
11d20 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
11d30 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
11d40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
11d50 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
11d60 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
11d70 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
11d80 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
11d90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
11da0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
11db0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
11dc0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
11dd0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
11de0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
11df0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
11e00 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
11e10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
11e20 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
11e30 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
11e40 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
11e50 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
11e60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11e70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
11e80 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
11e90 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
11ea0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
11eb0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
11ec0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
11ed0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
11ee0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
11ef0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
11f00 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
11f10 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77   The %Q option w
11f20 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
11f30 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
11f40 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
11f50 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
11f60 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
11f70 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
11f80 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
11f90 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
11fa0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
11fb0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
11fc0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
11fd0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
11fe0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
11ff0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69  single quotes) i
12000 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
12010 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66  Q option.  So, f
12020 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
12030 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
12040 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12050 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
12060 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
12070 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
12080 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
12090 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
120a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
120b0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
120c0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
120d0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
120e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
120f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
12100 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
12110 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
12120 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
12130 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
12140 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
12150 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
12160 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
12170 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f  *.** The "%z" fo
12180 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
12190 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69  works exactly li
121a0 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65  ke "%s" with the
121b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
121c0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
121d0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
121e0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
121f0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
12200 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12210 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
12220 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20  e input string. 
12230 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75  {END}.**.** Requ
12240 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
12250 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b  7403] [H17406] [
12260 48 31 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72 20  H17407].*/.char 
12270 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
12280 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
12290 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
122a0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
122b0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
122c0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
122d0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
122e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
122f0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
12300 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
12310 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
12320 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30  m {H17300} <S200
12330 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00>.**.** The SQ
12340 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20  Lite core  uses 
12350 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
12360 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
12370 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
12380 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
12390 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
123a0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
123b0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
123c0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
123d0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
123e0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
123f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
12400 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
12410 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
12420 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
12430 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
12440 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ations..**.** Th
12450 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
12460 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
12470 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
12480 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
12490 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
124a0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
124b0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
124c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66  parameter..** If
124d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
124e0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
124f0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
12500 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
12510 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
12520 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
12530 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
12540 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
12550 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
12560 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
12570 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12580 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
12590 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
125a0 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  * Calling sqlite
125b0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
125c0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
125d0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
125e0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
125f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
12600 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
12610 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
12620 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
12630 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65   be reused.  The
12640 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
12650 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
12660 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
12670 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
12680 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
12690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
126a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
126b0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
126c0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
126d0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
126e0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
126f0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
12700 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
12710 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
12720 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
12730 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
12740 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
12750 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
12760 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
12770 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
12780 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
12790 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
127a0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
127b0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
127c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
127d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
127e0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
127f0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
12800 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
12810 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
12820 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
12830 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ()..**.** The sq
12840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
12850 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
12860 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
12870 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
12880 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
12890 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
128a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
128b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
128c0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
128d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
128e0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
128f0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
12900 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69  eter.  If the fi
12910 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
12920 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
12930 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
12940 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
12950 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
12960 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
12970 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
12980 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
12990 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
129a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
129b0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
129c0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
129d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
129e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
129f0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
12a00 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
12a10 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
12a20 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
12a30 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
12a40 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
12a50 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
12a60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
12a70 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
12a80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12a90 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
12aa0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
12ab0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
12ac0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
12ad0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
12ae0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
12af0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
12b00 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69  lable..** If M i
12b10 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
12b20 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
12b30 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
12b40 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
12b50 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
12b60 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
12b70 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
12b80 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
12b90 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
12ba0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
12bb0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
12bc0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
12bd0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61  * If sqlite3_rea
12be0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
12bf0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
12c00 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
12c10 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
12c20 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
12c30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
12c40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
12c50 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
12c60 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
12c70 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
12c80 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
12c90 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a  oundary. {END}.*
12ca0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
12cb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12cc0 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  of the memory al
12cd0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
12ce0 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d  em uses.** the m
12cf0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
12d00 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72  () and free() pr
12d10 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74  ovided by the st
12d20 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
12d30 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f  ..** {H17382} Ho
12d40 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
12d50 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12d60 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12d70 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e  MEMORY_SIZE=<i>N
12d80 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63  NN</i> C preproc
12d90 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65  essor macro (whe
12da0 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a  re <i>NNN</i>.**
12db0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c   is an integer),
12dc0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65   then SQLite cre
12dd0 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72  ate a static arr
12de0 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a  ay of at least.*
12df0 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74  * <i>NNN</i> byt
12e00 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75  es in size and u
12e10 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66  ses that array f
12e20 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
12e30 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20  namic.** memory 
12e40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
12e50 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f  . {END}  Additio
12e60 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
12e70 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20  ator options.** 
12e80 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
12e90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
12ea0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
12eb0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
12ec0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
12ed0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
12ee0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
12ef0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
12f00 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
12f10 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
12f20 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
12f30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
12f40 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
12f50 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
12f60 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
12f70 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
12f80 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
12f90 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
12fa0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
12fb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69  ed..**.** The Wi
12fc0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
12fd0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
12fe0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
12ff0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
13000 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
13010 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
13020 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
13030 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
13040 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
13050 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
13060 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
13070 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
13080 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
13090 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
130a0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
130b0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
130c0 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
130d0 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
130e0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
130f0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
13100 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
13110 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
13120 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
13130 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13140 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30 33  ents:.** [H17303
13150 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 37 33  ] [H17304] [H173
13160 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48 31  05] [H17306] [H1
13170 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d 20 5b  7310] [H17312] [
13180 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 38 5d  H17315] [H17318]
13190 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48 31  .** [H17321] [H1
131a0 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a 2a  7322] [H17323].*
131b0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
131c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
131d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
131e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
131f0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
13200 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
13210 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
13220 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
13230 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
13240 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
13250 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
13260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
13270 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
13280 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
13290 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
132a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
132b0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
132c0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
132d0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
132e0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
132f0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
13300 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
13310 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
13320 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
13330 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
13340 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
13350 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
13360 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
13370 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
13380 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
13390 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
133a0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
133b0 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
133c0 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
133d0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
133e0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
133f0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
13400 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
13410 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
13420 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
13430 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
13440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
13450 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
13460 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
13470 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
13480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13490 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
134a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
134b0 20 5b 48 31 37 33 37 31 5d 20 5b 48 31 37 33 37   [H17371] [H1737
134c0 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b 48 31 37  3] [H17374] [H17
134d0 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  375].*/.sqlite3_
134e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
134f0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
13500 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
13510 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
13520 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
13530 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
13540 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
13550 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
13560 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d  nerator {H17390}
13570 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
13580 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
13590 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
135a0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
135b0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
135c0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
135d0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
135e0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
135f0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
13600 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
13610 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
13620 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
13630 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
13640 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
13650 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
13660 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
13670 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
13680 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
13690 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
136a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
136b0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
136c0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
136d0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
136e0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
136f0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
13700 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
13710 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
13720 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
13730 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
13740 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
13750 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
13760 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
13770 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
13780 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
13790 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
137a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
137b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
137c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
137d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
137e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
137f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
13800 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73  ect..** On all s
13810 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
13820 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
13830 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
13840 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
13850 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
13860 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
13870 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
13880 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
13890 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52   method..**.** R
138a0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
138b0 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64  [H17392].*/.void
138c0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
138d0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
138e0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
138f0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
13900 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
13910 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35   Callbacks {H125
13920 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a  00} <S70100>.**.
13930 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
13940 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68  registers a auth
13950 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
13960 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
13970 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
13980 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
13990 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
139a0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  t argument..** T
139b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
139c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
139d0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
139e0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
139f0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
13a00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
13a10 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
13a20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13a30 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
13a40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
13a50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
13a60 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
13a70 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
13a80 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
13a90 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
13aa0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
13ab0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
13ac0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
13ad0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
13ae0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
13af0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
13b00 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
13b10 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
13b20 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
13b30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
13b40 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
13b50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
13b60 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
13b70 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
13b80 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
13b90 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
13ba0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
13bb0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
13bc0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
13bd0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
13be0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
13bf0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
13c00 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
13c10 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
13c20 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
13c30 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61  error.  If the a
13c40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
13c50 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
13c60 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
13c70 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
13c80 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
13c90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
13ca0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
13cb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
13cc0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
13cd0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
13ce0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
13cf0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
13d00 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
13d10 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
13d20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
13d30 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
13d40 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
13d50 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
13d60 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
13d70 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61  ok.  When the ca
13d80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
13d90 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
13da0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
13db0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
13dc0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
13dd0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
13de0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
13df0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
13e00 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
13e10 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
13e20 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
13e30 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74  ied.  If the aut
13e40 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20  horizer code is 
13e50 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
13e60 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
13e70 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
13e80 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
13e90 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
13ea0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
13eb0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
13ec0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
13ed0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
13ee0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
13ef0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
13f00 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
13f10 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
13f20 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
13f30 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
13f40 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
13f50 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
13f60 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
13f70 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
13f80 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
13f90 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
13fa0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
13fb0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
13fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
13fd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
13fe0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
13ff0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
14000 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
14010 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
14020 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
14030 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  e. The second pa
14040 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
14050 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
14060 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
14070 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
14080 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
14090 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
140a0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
140b0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54  be authorized. T
140c0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
140d0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
140e0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
140f0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
14100 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
14110 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
14120 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
14130 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
14140 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
14150 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  rized..**.** An 
14160 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
14170 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
14180 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
14190 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
141a0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
141b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
141c0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
141d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
141e0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
141f0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
14200 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
14210 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
14220 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
14230 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
14240 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
14250 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
14260 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
14270 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
14280 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
14290 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
142a0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
142b0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
142c0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
142d0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
142e0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
142f0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
14300 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
14310 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
14320 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
14330 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
14340 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
14350 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
14360 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
14370 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
14380 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
14390 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
143a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
143b0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
143c0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
143d0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
143e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
143f0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
14400 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
14410 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
14420 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
14430 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
14440 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
14450 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
14460 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
14470 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
14480 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
14490 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
144a0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
144b0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
144c0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
144d0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
144e0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c  rizer..**.** Onl
144f0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
14500 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
14510 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
14520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14530 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
14540 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
14550 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
14560 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
14570 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
14580 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61  .  Disable the a
14590 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
145a0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
145b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
145c0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
145d0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
145e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
145f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14600 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
14610 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
14620 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
14630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14640 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
14650 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
14660 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
14670 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
14680 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
14690 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
146a0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
146b0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
146c0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
146d0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
146e0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
146f0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
14700 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
14710 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
14720 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
14730 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
14740 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
14750 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65 64  ht be reprepared
14760 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
14770 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
14780 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
14790 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
147a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
147b0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
147c0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
147d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
147e0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
147f0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
14800 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
14810 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
14820 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14830 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
14840 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
14850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
14860 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
14870 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
14880 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
14890 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
148a0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
148b0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
148c0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
148d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
148e0 2a 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48 31 32  ** [H12501] [H12
148f0 35 30 32 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48  502] [H12503] [H
14900 31 32 35 30 34 5d 20 5b 48 31 32 35 30 35 5d 20  12504] [H12505] 
14910 5b 48 31 32 35 30 36 5d 20 5b 48 31 32 35 30 37  [H12506] [H12507
14920 5d 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48  ] [H12510].** [H
14930 31 32 35 31 31 5d 20 5b 48 31 32 35 31 32 5d 20  12511] [H12512] 
14940 5b 48 31 32 35 32 30 5d 20 5b 48 31 32 35 32 31  [H12520] [H12521
14950 5d 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e  ] [H12522].*/.in
14960 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
14970 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
14980 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
14990 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
149a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
149b0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
149c0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
149d0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
149e0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
149f0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
14a00 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
14a10 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e  H12590} <H12500>
14a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
14a30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
14a40 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
14a50 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14a60 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
14a70 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
14a80 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
14a90 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
14aa0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
14ab0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
14ac0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
14ad0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
14ae0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
14af0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
14b00 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
14b10 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
14b20 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
14b30 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
14b40 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
14b50 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
14b60 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
14b70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
14b80 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
14b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
14ba0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
14bb0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
14bc0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
14bd0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
14be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14bf0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
14c00 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30  on Codes {H12550
14c10 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
14c20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
14c30 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
14c40 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
14c50 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
14c60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
14c70 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
14c80 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
14c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
14ca0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
14cb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14cc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
14cd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
14ce0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
14cf0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
14d00 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
14d10 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
14d20 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
14d30 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
14d40 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
14d50 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
14d60 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
14d70 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
14d80 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
14d90 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
14da0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
14db0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
14dc0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
14dd0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
14de0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
14df0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
14e00 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
14e10 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
14e20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
14e30 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
14e40 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
14e50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14e60 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
14e70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
14e80 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
14e90 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
14ea0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
14eb0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
14ec0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
14ed0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
14ee0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
14ef0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
14f00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
14f10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
14f20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
14f30 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
14f40 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
14f50 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
14f60 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
14f70 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
14f80 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
14f90 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
14fa0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
14fb0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
14fc0 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20  ts:.** [H12551] 
14fd0 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35 35 33  [H12552] [H12553
14fe0 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a  ] [H12554].*/./*
14ff0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
15020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
15030 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
15040 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
15050 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
15060 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
15070 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
15080 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15090 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
150a0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
150b0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
150c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
150d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
150e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
150f0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
15100 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
15110 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
15120 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
15130 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
15140 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
15150 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15160 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15170 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15180 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
15190 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
151a0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
151b0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
151c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
151d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
151e0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
151f0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
15200 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15210 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15220 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
15230 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
15240 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
15250 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15260 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15270 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
15280 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
15290 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
152a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
152b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
152c0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
152d0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
152e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
152f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15310 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
15320 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
15330 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
15340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15360 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
15370 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
15380 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
15390 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
153a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
153b0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
153c0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
153d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
153e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
153f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15400 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
15410 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
15420 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
15430 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15450 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
15460 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
15470 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
15480 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
154a0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
154b0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
154c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
154d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
154e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
154f0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
15500 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
15510 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
15520 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15530 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
15540 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
15550 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
15560 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
15570 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15580 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
15590 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
155a0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
155b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
155c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
155d0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
155e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
155f0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
15600 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
15610 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
15620 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
15630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
15640 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15650 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
15660 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15670 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
15680 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
15690 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
156a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
156b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
156c0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
156d0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
156e0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
156f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15700 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15710 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
15720 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
15730 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
15740 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
15750 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15760 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
15770 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
15780 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
15790 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
157a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
157b0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
157c0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
157d0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
157e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
157f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15800 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
15810 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
15820 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
15830 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15850 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
15860 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
15870 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
15880 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
158a0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
158b0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
158c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
158d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
158e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
158f0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
15900 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
15910 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
15920 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
15930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15940 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
15950 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
15960 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
15970 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
15980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
15990 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
159a0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
159b0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
159c0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
159d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
159e0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
159f0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
15a00 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
15a10 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
15a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
15a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15a40 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
15a50 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
15a60 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
15a70 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
15a80 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32  g Functions {H12
15a90 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  280} <S60400>.**
15aa0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
15ab0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15ac0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
15ad0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
15ae0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
15af0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
15b00 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
15b10 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
15b20 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15b30 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
15b40 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
15b50 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
15b60 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
15b70 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
15b80 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
15b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
15ba0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
15bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
15bc0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  * The callback r
15bd0 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72  eturns a UTF-8 r
15be0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
15bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
15c00 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61  xt.** as the sta
15c10 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
15c20 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20  ins executing.  
15c30 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  Additional callb
15c40 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73  acks occur.** as
15c50 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
15c60 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
15c70 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
15c80 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
15c90 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
15ca0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
15cb0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
15cc0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  s the trigger..*
15cd0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
15ce0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
15cf0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
15d00 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
15d10 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
15d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
15d30 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72  inishes.  The pr
15d40 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
15d50 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
15d60 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
15d70 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
15d80 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
15d90 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
15da0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
15db0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
15dc0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  run..**.** Requi
15dd0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
15de0 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48  281] [H12282] [H
15df0 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34 5d 20  12283] [H12284] 
15e00 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32 38 37  [H12285] [H12287
15e10 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 32  ] [H12288] [H122
15e20 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a  89].** [H12290].
15e30 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
15e40 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
15e50 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
15e60 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
15e70 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
15e80 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
15e90 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
15ea0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
15eb0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
15ec0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
15ed0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
15ee0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
15ef0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
15f00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15f10 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
15f20 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
15f30 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  10} <S60400>.**.
15f40 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
15f50 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c  configures a cal
15f60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d  lback function -
15f70 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73   the.** progress
15f80 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74   callback - that
15f90 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
15fa0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
15fb0 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  long.** running 
15fc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
15fd0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
15fe0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a  te3_step()] and.
15ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
16000 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78  table()].  An ex
16010 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
16020 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
16030 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
16040 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
16050 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
16060 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67  *.** If the prog
16070 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
16080 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
16090 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
160a0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
160b0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
160c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
160d0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
160e0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
160f0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
16100 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
16110 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
16120 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64  ndler must not d
16130 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
16140 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
16150 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16160 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
16170 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
16180 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
16190 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
161a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
161b0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
161c0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
161d0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
161e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
161f0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
16200 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
16210 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
16220 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
16230 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32  ** [H12911] [H12
16240 39 31 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48  912] [H12913] [H
16250 31 32 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20  12914] [H12915] 
16260 5b 48 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37  [H12916] [H12917
16270 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f  ] [H12918].**.*/
16280 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
16290 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
162a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
162b0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
162c0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
162d0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
162e0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
162f0 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d  nection {H12700}
16300 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40200>.**.** 
16310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
16320 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
16330 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
16340 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
16350 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
16360 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
16370 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
16380 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
16390 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
163a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
163b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
163c0 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
163d0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
163e0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
163f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
16400 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
16410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
16420 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
16430 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
16440 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
16450 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
16460 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
16470 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
16480 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
16490 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
164a0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
164b0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
164c0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
164d0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
164e0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
164f0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
16500 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
16510 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
16520 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
16530 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
16540 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
16550 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
16560 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
16570 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
16580 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
16590 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
165a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
165b0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
165c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
165d0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
165e0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
165f0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
16600 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
16610 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
16620 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
16630 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
16640 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
16650 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
16660 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
16670 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16680 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
16690 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
166a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
166b0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
166c0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
166d0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
166e0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
166f0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
16700 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
16710 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
16720 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
16730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
16740 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
16750 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
16760 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
16770 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
16780 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
16790 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
167a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
167b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
167c0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
167d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
167e0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
167f0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
16800 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
16810 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
16820 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
16830 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
16840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
16850 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
16860 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  ter can take one
16870 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
16880 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
16890 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
168a0 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
168b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
168c0 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51  _NOMUTEX] or [SQ
168d0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
168e0 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a  TEX] flags:.**.*
168f0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
16900 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
16910 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
16920 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
16930 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
16940 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
16950 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
16960 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
16970 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
16980 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
16990 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
169a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
169b0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
169c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
169d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
169e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
169f0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
16a00 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
16a10 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
16a20 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
16a30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
16a40 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
16a50 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
16a60 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
16a70 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
16a80 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
16a90 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
16aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
16ab0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
16ac0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
16ad0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
16ae0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
16af0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
16b00 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
16b10 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
16b20 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
16b30 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
16b40 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
16b50 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
16b60 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
16b70 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
16b80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
16b90 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
16ba0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
16bb0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
16bc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16bd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
16be0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
16bf0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
16c00 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
16c10 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
16c20 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
16c30 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
16c40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
16c50 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53  N_NOMUTEX] or [S
16c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
16c70 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  UTEX] flags,.** 
16c80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
16c90 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
16ca0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  **.** If the [SQ
16cb0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
16cc0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
16cd0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
16ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
16cf0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
16d00 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
16d10 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
16d20 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
16d30 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
16d40 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
16d50 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
16d60 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
16d70 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   If the.** [SQLI
16d80 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
16d90 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
16da0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
16db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
16dc0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
16dd0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
16de0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
16df0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
16e00 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
16e10 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
16e20 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
16e30 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  -time..**.** If 
16e40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
16e50 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
16e60 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
16e70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
16e80 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
16e90 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
16ea0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
16eb0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
16ec0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
16ed0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
16ee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16ef0 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
16f00 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
16f10 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
16f20 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
16f30 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
16f40 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
16f50 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
16f60 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
16f70 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
16f80 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
16f90 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
16fa0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
16fb0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
16fc0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
16fd0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
16fe0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
16ff0 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
17000 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
17010 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
17020 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
17030 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
17040 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
17050 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
17060 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
17070 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
17080 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
17090 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
170a0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
170b0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
170c0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
170d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
170e0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
170f0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
17100 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17110 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
17120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
17130 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
17140 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
17150 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
17160 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
17170 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
17180 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
17190 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
171a0 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74  e.  If the fourt
171b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
171c0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
171d0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
171e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
171f0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
17200 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
17210 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
17220 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
17230 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
17240 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
17250 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
17260 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
17270 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
17280 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
17290 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
172a0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
172b0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
172c0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
172d0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
172e0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
172f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
17300 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
17310 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
17320 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
17330 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
17340 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
17350 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
17360 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37 30   [H12701] [H1270
17370 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31 32  2] [H12703] [H12
17380 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b 48  704] [H12706] [H
17390 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d 20  12707] [H12709] 
173a0 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 32  [H12711].** [H12
173b0 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b 48  712] [H12713] [H
173c0 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d 20  12714] [H12717] 
173d0 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32 31  [H12719] [H12721
173e0 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e  ] [H12723].*/.in
173f0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
17400 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
17410 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
17420 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
17430 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
17440 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
17450 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
17460 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
17470 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
17480 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
17490 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
174a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
174b0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
174c0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
174d0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
174e0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
174f0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
17500 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
17510 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
17520 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
17530 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
17540 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
17550 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
17560 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
17570 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
17580 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
17590 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
175a0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
175b0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
175c0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
175d0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
175e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
175f0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
17600 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31  And Messages {H1
17610 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a  2800} <S60200>.*
17620 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
17630 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
17640 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
17650 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
17660 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
17670 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
17680 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
17690 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
176a0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
176b0 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
176c0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
176d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
176e0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
176f0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
17700 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17710 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
17720 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
17730 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
17740 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
17750 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68  s undefined.  Th
17760 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
17770 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
17780 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
17790 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
177a0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
177b0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
177c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
177d0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
177e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
177f0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
17800 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
17810 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
17820 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
17830 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
17840 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
17850 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
17860 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
17870 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
17880 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
17890 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72  tively..** Memor
178a0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
178b0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
178c0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
178d0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
178e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
178f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
17900 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
17910 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
17920 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
17930 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
17940 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
17950 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
17960 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
17970 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
17980 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
17990 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
179a0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
179b0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
179c0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
179d0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
179e0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
179f0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
17a00 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
17a10 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
17a20 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
17a30 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
17a40 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
17a50 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
17a60 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
17a70 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
17a80 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
17a90 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
17aa0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
17ab0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
17ac0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
17ad0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
17ae0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
17af0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
17b00 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
17b10 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
17b20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17b30 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
17b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
17b50 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
17b60 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
17b70 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
17b80 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
17b90 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
17ba0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
17bb0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
17bc0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
17bd0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
17be0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
17bf0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
17c00 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
17c10 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
17c20 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
17c30 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
17c40 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
17c50 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
17c60 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
17c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
17c80 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
17c90 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
17ca0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
17cb0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
17cc0 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  t..**.** Require
17cd0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30  ments:.** [H1280
17ce0 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 31 32  1] [H12802] [H12
17cf0 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48  803] [H12807] [H
17d00 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a  12808] [H12809].
17d10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
17d20 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
17d30 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
17d40 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
17d50 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
17d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
17d70 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
17d80 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
17d90 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
17da0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
17db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
17dc0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
17dd0 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31  ect {H13000} <H1
17de0 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  3010>.** KEYWORD
17df0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
17e00 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
17e10 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
17e20 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
17e30 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
17e40 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
17e50 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
17e60 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
17e70 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
17e80 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
17e90 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
17ea0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
17eb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
17ec0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
17ed0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
17ee0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
17ef0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
17f00 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
17f10 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
17f20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
17f30 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
17f40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
17f50 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
17f60 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
17f70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
17f80 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
17f90 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
17fa0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
17fb0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
17fc0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
17fd0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
17fe0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
17ff0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
18000 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
18010 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
18020 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
18030 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
18040 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
18050 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
18060 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
18070 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
18080 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
18090 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
180a0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
180b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
180c0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
180d0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
180e0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
180f0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
18100 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
18110 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
18120 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
18130 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
18140 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
18150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
18160 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31  -time Limits {H1
18170 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a  2760} <S20600>.*
18180 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
18190 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
181a0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
181b0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
181c0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
181d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
181e0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
181f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
18200 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
18210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18220 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
18230 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
18240 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
18250 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
18260 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
18270 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
18280 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
18290 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
182a0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
182b0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
182c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
182d0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
182e0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
182f0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
18300 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18310 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
18320 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
18330 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
18340 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
18350 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
18360 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
18370 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
18380 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
18390 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  Z there is a .**
183a0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
183b0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
183c0 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
183d0 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65  -time C preproce
183e0 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64  ssor macro named
183f0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53   .** [limits | S
18400 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a  QLITE_MAX_XYZ]..
18410 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
18420 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
18430 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
18440 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
18450 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
18460 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
18470 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
18480 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
18490 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
184a0 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
184b0 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
184c0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
184d0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
184e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
184f0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
18500 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
18510 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
18520 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
18530 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
18540 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
18550 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
18560 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
18570 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
18580 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
18590 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
185a0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
185b0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
185c0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
185d0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
185e0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
185f0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
18600 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
18610 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
18620 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
18630 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
18640 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
18650 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
18660 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
18670 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
18680 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
18690 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
186a0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
186b0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
186c0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
186d0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
186e0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
186f0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
18700 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
18710 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18720 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
18730 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
18740 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
18750 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
18760 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
18770 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
18780 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
18790 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
187a0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
187b0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
187c0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
187d0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
187e0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
187f0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
18800 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
18810 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ses..**.** Requi
18820 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
18830 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48  762] [H12766] [H
18840 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71  12769].*/.int sq
18850 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
18860 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
18870 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
18880 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
18890 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
188a0 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c  ories {H12790} <
188b0 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f  H12760>.** KEYWO
188c0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
188d0 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74  gory} {limit cat
188e0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
188f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
18900 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
18910 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
18920 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
18930 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
18940 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
18950 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
18960 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
18970 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
18980 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
18990 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
189a0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
189b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
189c0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
189d0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
189e0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
189f0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
18a00 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
18a10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18a20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
18a30 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
18a40 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  OB or table row.
18a50 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
18a60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
18a70 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
18a80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
18a90 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
18aa0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
18ab0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18ac0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
18ad0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
18ae0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
18af0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
18b00 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
18b10 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
18b20 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
18b30 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
18b40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
18b50 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
18b60 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
18b70 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
18b80 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
18b90 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18ba0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
18bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18bc0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
18bd0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
18be0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
18bf0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
18c00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18c10 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
18c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18c30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18c40 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
18c50 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
18c60 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
18c70 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18c80 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
18c90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18ca0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
18cb0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
18cc0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
18cd0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
18ce0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
18cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
18d00 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
18d20 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
18d30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18d40 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
18d50 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
18d60 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
18d70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
18d80 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
18d90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18da0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
18db0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
18dc0 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a  abases].</dd>.**
18dd0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18de0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
18df0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
18e00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
18e10 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
18e20 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
18e30 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
18e40 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
18e50 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tors.</dd>.**.**
18e60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18e70 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
18e80 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
18e90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18ea0 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
18eb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18ec0 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
18ed0 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20   bound.</dd>.** 
18ee0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18ef0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
18f00 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
18f10 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
18f20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
18f30 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
18f40 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
18f50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18f60 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
18f70 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
18f80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
18f90 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
18fa0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
18fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
18fc0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
18fd0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
18fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
18ff0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
19000 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
19010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
19020 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
19030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
19040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
19050 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
19060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
19070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19080 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
19090 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
190a0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
190b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
190c0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
190d0 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   9../*.** CAPI3R
190e0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
190f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
19100 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e  H13010} <S10000>
19110 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
19120 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
19130 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
19140 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
19150 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
19160 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
19170 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
19180 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
19190 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
191a0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
191b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
191c0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
191d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
191e0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
191f0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
19200 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
19210 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
19220 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
19230 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
19240 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
19250 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
19260 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
19270 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
19280 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
19290 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
192a0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
192b0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
192c0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
192d0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
192e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
192f0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
19300 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
19310 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
19320 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
19330 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
19340 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
19350 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
19360 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
19370 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49   UTF-16..**.** I
19380 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
19390 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
193a0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
193b0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
193c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
193d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66  o terminator. If
193e0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
193f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
19400 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
19410 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
19420 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
19430 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
19440 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
19450 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
19460 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
19470 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
19480 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
19490 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
194a0 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
194b0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
194c0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
194d0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
194e0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
194f0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
19500 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
19510 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
19520 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
19530 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
19540 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
19550 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
19560 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
19570 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
19580 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
19590 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
195a0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
195b0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
195c0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
195d0 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20  **.** If pzTail 
195e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
195f0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
19600 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
19610 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
19620 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
19630 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
19640 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
19650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19660 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
19670 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
19680 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
19690 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
196a0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
196b0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
196c0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70  mpiled..**.** *p
196d0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
196e0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
196f0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
19700 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
19710 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
19720 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
19730 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68  _step()].  If th
19740 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
19750 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
19760 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20  ** to NULL.  If 
19770 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
19780 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
19790 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
197a0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
197b0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
197c0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
197d0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
197e0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
197f0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
19800 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
19810 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
19820 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19830 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19840 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
19850 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
19860 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
19870 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
19880 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  NULL..**.** On s
19890 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
198a0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c  OK] is returned,
198b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
198c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
198d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
198e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
198f0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
19900 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19910 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
19920 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
19930 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
19940 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
19950 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
19960 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
19970 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
19980 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
19990 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
199a0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20  couraged..** In 
199b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
199c0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
199d0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
199e0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
199f0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
19a00 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
19a10 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
19a20 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
19a30 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
19a40 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
19a50 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
19a60 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
19a70 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69   a differently i
19a80 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a  n two ways:.**.*
19a90 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
19aa0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
19ab0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
19ac0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
19ad0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
19ae0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
19af0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
19b00 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
19b10 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
19b20 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
19b30 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
19b40 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
19b50 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20   run it again.  
19b60 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
19b70 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
19b80 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
19b90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
19ba0 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
19bb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19bc0 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
19bd0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
19be0 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69  HEMA].  But unli
19bf0 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ke the legacy be
19c00 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f  havior, [SQLITE_
19c10 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f  SCHEMA] is.** no
19c20 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e  w a fatal error.
19c30 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74    Calling [sqlit
19c40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19c50 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
19c60 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
19c70 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
19c80 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
19c90 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
19ca0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
19cb0 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
19cc0 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
19cd0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
19ce0 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20  EMA] return..** 
19cf0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
19d00 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  .** When an erro
19d10 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
19d20 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
19d30 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
19d40 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
19d50 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
19d60 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
19d70 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61  odes].  The lega
19d80 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
19d90 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
19da0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
19db0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
19dc0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
19dd0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
19de0 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64  ** and you would
19df0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
19e00 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
19e10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
19e20 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
19e30 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
19e40 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
19e50 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
19e60 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
19e70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
19e80 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
19e90 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
19ea0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
19eb0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
19ec0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
19ed0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
19ee0 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48  :.** [H13011] [H
19ef0 31 33 30 31 32 5d 20 5b 48 31 33 30 31 33 5d 20  13012] [H13013] 
19f00 5b 48 31 33 30 31 34 5d 20 5b 48 31 33 30 31 35  [H13014] [H13015
19f10 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48 31 33 30  ] [H13016] [H130
19f20 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a  19] [H13021].**.
19f30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
19f40 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
19f50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
19f60 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
19f70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
19f80 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
19f90 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
19fa0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
19fb0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
19fc0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
19fd0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
19fe0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
19ff0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1a000 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1a010 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1a020 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1a030 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1a040 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1a050 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1a060 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1a070 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1a080 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1a090 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a0a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1a0b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1a0c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1a0d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1a0e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1a0f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1a100 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1a110 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1a120 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1a130 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1a140 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1a150 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1a160 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1a170 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a180 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1a190 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1a1a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1a1b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1a1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1a1d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1a1e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1a1f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1a200 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a210 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1a220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1a230 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1a240 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a250 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a260 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a270 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a280 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a290 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a2a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a2b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a2c0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1a2d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a2e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a2f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a300 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1a310 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1a320 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a330 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a340 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a350 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1a360 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a370 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1a380 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1a390 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1a3a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1a3b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1a3c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1a3d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1a3e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1a3f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1a400 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1a410 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1a420 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1a430 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1a440 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1a450 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1a460 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1a470 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48   SQL {H13100} <H
1a480 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13000>.**.** Thi
1a490 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1a4a0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1a4b0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1a4c0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1a4d0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1a4e0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1a4f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a500 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1a510 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1a520 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1a530 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1a540 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1a550 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a560 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  2()]..**.** Requ
1a570 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1a580 33 31 30 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b  3101] [H13102] [
1a590 48 31 33 31 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13103].*/.const
1a5a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1a5b0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1a5c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1a5d0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
1a5e0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
1a5f0 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30  e Object {H15000
1a600 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
1a610 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1a620 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1a630 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1a640 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1a650 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1a660 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1a670 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1a680 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1a690 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1a6a0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1a6b0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1a6c0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1a6d0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1a6e0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1a6f0 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
1a700 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1a710 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1a720 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1a730 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1a740 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1a750 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1a760 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1a770 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1a780 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1a790 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1a7a0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1a7b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1a7c0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1a7d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1a7e0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1a7f0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1a800 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1a810 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1a820 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1a830 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1a840 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1a850 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1a860 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1a870 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1a880 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1a890 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1a8a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1a8b0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1a8c0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1a8d0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1a8e0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1a8f0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1a900 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1a910 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1a920 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1a930 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1a940 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1a950 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1a960 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1a970 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1a980 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1a990 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1a9a0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1a9b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1a9c0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
1a9d0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
1a9e0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1a9f0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1aa00 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
1aa10 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
1aa20 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
1aa30 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
1aa40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1aa50 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
1aa60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
1aa70 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
1aa80 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1aa90 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1aaa0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1aab0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1aac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1aad0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1aae0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
1aaf0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
1ab00 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
1ab10 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
1ab20 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
1ab30 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
1ab40 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
1ab50 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
1ab60 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62  nction between b
1ab70 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1ab80 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1ab90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1aba0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
1abb0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
1abc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1abd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1abe0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1abf0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1ac00 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1ac10 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1ac20 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1ac30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1ac40 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1ac50 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65  rotected..** The
1ac60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ac70 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
1ac80 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
1ac90 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
1aca0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
1acb0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
1acc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1acd0 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
1ace0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
1acf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
1ad00 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1ad10 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
1ad20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1ad30 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
1ad40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
1ad50 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
1ad60 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1ad70 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1ad80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ad90 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1ada0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1adb0 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1adc0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
1add0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
1ade0 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20  Object {H16001} 
1adf0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
1ae00 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
1ae10 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
1ae20 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
1ae30 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
1ae40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1ae50 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
1ae60 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1ae70 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
1ae80 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
1ae90 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1aea0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1aeb0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1aec0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
1aed0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1aee0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
1aef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
1af00 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
1af10 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
1af20 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
1af30 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
1af40 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
1af50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1af60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
1af70 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
1af80 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
1af90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
1afa0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
1afb0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
1afc0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
1afd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
1afe0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
1aff0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1b000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
1b010 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
1b020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b030 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1b040 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1b050 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c  ments {H13500} <
1b060 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S70300>.** KEYWO
1b070 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1b080 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1b090 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1b0a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1b0b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1b0c0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1b0d0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1b0e0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1b0f0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
1b100 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
1b110 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1b120 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
1b130 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
1b140 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
1b150 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
1b160 61 6d 65 74 65 72 5d 20 69 6e 20 6f 6e 65 20 6f  ameter] in one o
1b170 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a  f these forms:.*
1b180 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1b190 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1b1a0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1b1b0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1b1c0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1b1d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1b1e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
1b1f0 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
1b200 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
1b210 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1b220 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61   VVV is an alpha
1b230 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1b240 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c  er name. The val
1b250 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1b260 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1b270 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1b280 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1b290 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1b2a0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1b2b0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1b2c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1b2d0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1b2e0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1b2f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1b300 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b310 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1b320 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1b330 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1b340 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1b350 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1b360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1b370 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1b380 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1b390 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1b3a0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1b3b0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1b3c0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1b3d0 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1b3e0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1b3f0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1b400 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1b410 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1b420 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1b430 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1b440 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1b450 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1b460 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1b470 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1b480 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1b490 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1b4a0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1b4b0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1b4c0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1b4d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1b4e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1b4f0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1b500 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
1b510 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
1b520 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
1b530 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
1b540 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1b550 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1b560 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1b570 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1b580 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1b590 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1b5a0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1b5b0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1b5c0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1b5d0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1b5e0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1b5f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b600 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  * In those routi
1b610 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1b620 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1b630 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1b640 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1b650 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1b660 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1b670 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1b680 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1b690 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1b6a0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1b6b0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1b6c0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49  characters..** I
1b6d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1b6e0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1b6f0 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1b700 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1b710 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1b720 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1b730 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1b740 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1b750 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1b760 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1b770 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1b780 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1b790 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1b7a0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1b7b0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1b7c0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1b7d0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1b7e0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1b7f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1b800 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1b810 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1b820 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1b830 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1b840 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1b850 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1b860 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1b870 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1b880 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1b890 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1b8a0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1b8b0 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1b8c0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1b8d0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1b8e0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1b8f0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1b900 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1b910 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1b920 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1b930 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1b940 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1b950 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1b960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1b970 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1b980 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1b990 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1b9a0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1b9b0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1b9c0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1b9d0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1b9e0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1b9f0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1ba00 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1ba10 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1ba20 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1ba30 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1ba40 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1ba50 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1ba60 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1ba70 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1ba80 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1ba90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1baa0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1bab0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1bac0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65  outines..** A ne
1bad0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
1bae0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
1baf0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
1bb00 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
1bb10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1bb20 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1bb30 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1bb40 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
1bb50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1bb60 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
1bb70 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
1bb80 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
1bb90 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
1bba0 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
1bbb0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1bbc0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1bbd0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1bbe0 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
1bbf0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1bc00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1bc10 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
1bc20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1bc30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1bc40 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
1bc50 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
1bc60 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1bc70 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
1bc80 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
1bc90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1bca0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
1bcb0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
1bcc0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
1bcd0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
1bce0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  () fails..** [SQ
1bcf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67  LITE_MISUSE] mig
1bd00 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
1bd10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1bd20 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61   are called on a
1bd30 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68  .** virtual mach
1bd40 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20  ine that is the 
1bd50 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77  wrong state or w
1bd60 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79  hich has already
1bd70 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
1bd80 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66  .** Detection of
1bd90 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c   misuse is unrel
1bda0 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74  iable.  Applicat
1bdb0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
1bdc0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c  depend.** on SQL
1bdd0 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72  ITE_MISUSE retur
1bde0 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55  ns.  SQLITE_MISU
1bdf0 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  SE is intended t
1be00 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20  o indicate a.** 
1be10 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  a logic error in
1be20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1be30 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1be40 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1be50 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68  ht.** panic rath
1be60 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53  er than return S
1be70 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
1be80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1be90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1bea0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1beb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1bec0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1bed0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1bee0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1bef0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1bf00 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1bf10 20 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30   [H13506] [H1350
1bf20 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33  9] [H13512] [H13
1bf30 35 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48  515] [H13518] [H
1bf40 31 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20  13521] [H13524] 
1bf50 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33  [H13527].** [H13
1bf60 35 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48  530] [H13533] [H
1bf70 31 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20  13536] [H13539] 
1bf80 5b 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35  [H13542] [H13545
1bf90 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35  ] [H13548] [H135
1bfa0 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  51].**.*/.int sq
1bfb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1bfc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1bfd0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1bfe0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1bff0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1c000 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
1c010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c020 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
1c030 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1c040 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1c050 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
1c060 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
1c070 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
1c080 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
1c090 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
1c0a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
1c0b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c0c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c0d0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
1c0e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1c0f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
1c100 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1c110 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c120 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
1c130 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1c140 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1c150 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1c160 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c170 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
1c180 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1c190 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
1c1a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c1b0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
1c1c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c1d0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1c1e0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1c1f0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
1c200 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
1c210 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
1c220 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1c230 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1c240 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
1c250 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
1c260 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1c270 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
1c280 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1c290 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1c2a0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1c2b0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1c2c0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1c2d0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1c2e0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1c2f0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1c300 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1c310 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1c320 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1c330 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1c340 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c350 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
1c360 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1c370 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
1c380 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
1c390 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
1c3a0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
1c3b0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
1c3c0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
1c3d0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
1c3e0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
1c3f0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
1c400 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
1c410 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
1c420 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
1c430 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
1c440 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1c450 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1c460 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1c470 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1c480 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
1c490 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1c4a0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1c4b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1c4c0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1c4d0 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  01].*/.int sqlit
1c4e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1c4f0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
1c500 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1c510 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
1c520 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
1c530 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33  r {H13620} <S703
1c540 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
1c550 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1c560 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1c570 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1c580 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  .** [SQL paramet
1c590 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72  er] in a [prepar
1c5a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1c5b0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
1c5c0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1c5d0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1c5e0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1c5f0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1c600 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1c610 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1c620 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1c630 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1c640 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1c650 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1c660 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1c670 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1c680 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1c690 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1c6a0 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
1c6b0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1c6c0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
1c6d0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
1c6e0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
1c6f0 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65   and are also re
1c700 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e  ferred to as "an
1c710 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
1c720 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  rs"..**.** The f
1c730 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
1c740 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1c750 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
1c760 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
1c770 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
1c780 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
1c790 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1c7a0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
1c7b0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1c7c0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
1c7d0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
1c7e0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
1c7f0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
1c800 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
1c810 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
1c820 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
1c830 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
1c840 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1c850 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1c860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1c870 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1c880 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1c890 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1c8a0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1c8b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1c8c0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1c8d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1c8e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1c8f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1c900 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1c910 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  21].*/.const cha
1c920 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1c930 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1c940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1c950 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1c960 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1c970 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1c980 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
1c990 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
1c9a0 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
1c9b0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
1c9c0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
1c9d0 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
1c9e0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
1c9f0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
1ca00 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
1ca10 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
1ca20 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1ca30 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1ca40 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
1ca50 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
1ca60 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
1ca70 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
1ca80 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
1ca90 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
1caa0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
1cab0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
1cac0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1cad0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
1cae0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
1caf0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
1cb00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1cb10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1cb20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1cb30 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1cb40 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1cb50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1cb60 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1cb70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1cb80 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1cb90 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  x()]..**.** Requ
1cba0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1cbb0 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3641].*/.int sql
1cbc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1cbd0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
1cbe0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
1cbf0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
1cc00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1cc10 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
1cc20 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
1cc30 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30  tatement {H13660
1cc40 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1cc50 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
1cc60 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
1cc70 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
1cc80 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
1cc90 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
1cca0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1ccb0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
1ccc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ccd0 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
1cce0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
1ccf0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
1cd00 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
1cd10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1cd20 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a  ts:.** [H13661].
1cd30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1cd40 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
1cd50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1cd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1cd70 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
1cd80 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1cd90 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30   {H13710} <S1070
1cda0 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
1cdb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1cdc0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1cdd0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
1cde0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
1cdf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1ce00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1ce10 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
1ce20 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
1ce30 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
1ce40 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
1ce50 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
1ce60 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
1ce70 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1ce80 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a  .** [H13711].*/.
1ce90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1cea0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
1ceb0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1cec0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ced0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
1cee0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31  A Result Set {H1
1cef0 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3720} <S10700>.*
1cf00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1cf10 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
1cf20 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
1cf30 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
1cf40 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
1cf50 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1cf60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1cf70 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
1cf80 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
1cf90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1cfa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1cfb0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1cfc0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
1cfd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
1cfe0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
1cff0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d000 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
1d010 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1d020 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74  ring.  The first
1d030 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1d040 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1d050 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1d060 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1d070 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1d080 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
1d090 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1d0a0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1d0b0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
1d0c0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
1d0d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
1d0e0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
1d0f0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
1d100 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
1d110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d120 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
1d130 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1d140 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1d150 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
1d160 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
1d170 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
1d180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d190 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
1d1a0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
1d1b0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
1d1c0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
1d1d0 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
1d1e0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
1d1f0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
1d200 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
1d210 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
1d220 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
1d230 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
1d240 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1d250 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
1d260 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
1d270 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
1d280 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
1d290 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
1d2a0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
1d2b0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
1d2c0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
1d2d0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
1d2e0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
1d2f0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
1d300 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
1d310 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
1d320 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
1d330 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
1d340 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ext..**.** Requi
1d350 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1d360 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48  721] [H13723] [H
1d370 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20  13724] [H13725] 
1d380 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37  [H13726] [H13727
1d390 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1d3a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1d3b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1d3c0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
1d3d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1d3e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
1d3f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d400 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
1d410 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
1d420 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
1d430 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20  Result {H13740} 
1d440 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1d450 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
1d460 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
1d470 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
1d480 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
1d490 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
1d4a0 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
1d4b0 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  lt of a [SELECT]
1d4c0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
1d4d0 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
1d4e0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1d4f0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1d500 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1d510 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1d520 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1d530 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1d540 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
1d550 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
1d560 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
1d570 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
1d580 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1d590 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
1d5a0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
1d5b0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1d5c0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
1d5d0 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
1d5e0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
1d5f0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
1d600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d610 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
1d620 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
1d630 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
1d640 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
1d650 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
1d660 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
1d670 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
1d680 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
1d690 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
1d6a0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
1d6b0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
1d6c0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
1d6d0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
1d6e0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
1d6f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1d700 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
1d710 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
1d720 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d730 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
1d740 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1d750 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
1d760 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
1d770 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
1d780 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
1d790 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1d7a0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
1d7b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
1d7c0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1d7d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1d7e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
1d7f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
1d800 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
1d810 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
1d820 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
1d830 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
1d840 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
1d850 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1d860 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
1d870 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
1d880 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1d890 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
1d8a0 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
1d8b0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
1d8c0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
1d8d0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
1d8e0 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
1d8f0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1d900 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
1d910 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
1d920 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
1d930 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
1d940 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
1d950 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
1d960 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
1d970 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
1d980 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
1d990 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
1d9a0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
1d9b0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
1d9c0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
1d9d0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
1d9e0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
1d9f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
1da00 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
1da10 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
1da20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1da30 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a  **.** {A13751}.*
1da40 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1da50 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1da60 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1da70 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1da80 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1da90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1daa0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1dab0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1dac0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1dad0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1dae0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1daf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31  ents:.** [H13741
1db00 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37  ] [H13742] [H137
1db10 34 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31  43] [H13744] [H1
1db20 33 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b  3745] [H13746] [
1db30 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66  H13748].**.** If
1db40 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1db50 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1db60 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
1db70 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1db80 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
1db90 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
1dba0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
1dbb0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
1dbc0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
1dbd0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
1dbe0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1dbf0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1dc00 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1dc10 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1dc20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1dc30 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
1dc40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1dc50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1dc60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1dc70 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
1dc80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1dc90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1dca0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1dcb0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1dcc0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1dcd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1dce0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
1dcf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1dd00 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1dd10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1dd20 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
1dd30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1dd40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1dd50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1dd60 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1dd70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
1dd80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1dd90 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
1dda0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
1ddb0 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37  t {H13760} <S107
1ddc0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  00>.**.** The fi
1ddd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1dde0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1ddf0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
1de00 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1de10 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1de20 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
1de30 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
1de40 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
1de50 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
1de60 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
1de70 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
1de80 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
1de90 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
1dea0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
1deb0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
1dec0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
1ded0 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
1dee0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
1def0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
1df00 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
1df10 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
1df20 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
1df30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1df40 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1df50 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
1df60 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
1df70 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
1df80 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
1df90 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1dfa0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1dfb0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1dfc0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
1dfd0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1dfe0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1dff0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
1e000 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
1e010 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
1e020 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
1e030 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
1e040 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
1e050 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
1e060 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
1e070 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
1e080 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
1e090 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
1e0a0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
1e0b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
1e0c0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
1e0d0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
1e0e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
1e0f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
1e100 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
1e110 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
1e120 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
1e130 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
1e140 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
1e150 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
1e160 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
1e170 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
1e180 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
1e190 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
1e1a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
1e1b0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
1e1c0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
1e1d0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
1e1e0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
1e1f0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
1e200 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
1e210 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ues..**.** Requi
1e220 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1e230 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48  761] [H13762] [H
1e240 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13763].*/.const 
1e250 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1e260 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
1e270 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e280 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1e2a0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
1e2b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1e2c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
1e2d0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
1e2e0 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
1e2f0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
1e300 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
1e310 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
1e320 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
1e330 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
1e340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e350 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1e360 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1e370 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
1e380 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
1e390 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
1e3a0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
1e3b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1e3c0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
1e3d0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
1e3e0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
1e3f0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
1e400 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
1e410 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
1e420 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
1e430 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1e440 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
1e450 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
1e460 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
1e470 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
1e480 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
1e490 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
1e4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e4b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1e4c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e4d0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
1e4e0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
1e4f0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
1e500 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1e510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e520 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
1e530 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
1e540 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
1e550 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1e560 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
1e570 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
1e580 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
1e590 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
1e5a0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
1e5b0 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
1e5c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
1e5d0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
1e5e0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
1e5f0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
1e600 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
1e610 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
1e620 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
1e630 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
1e640 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
1e650 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
1e660 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
1e670 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
1e680 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1e690 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
1e6a0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
1e6b0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
1e6c0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
1e6d0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
1e6e0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
1e6f0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
1e700 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
1e710 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
1e720 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
1e730 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1e740 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
1e750 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
1e760 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
1e770 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1e780 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
1e790 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
1e7a0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
1e7b0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
1e7c0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
1e7d0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
1e7e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
1e7f0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
1e800 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
1e810 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
1e820 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
1e830 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
1e840 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
1e850 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
1e860 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
1e870 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
1e880 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
1e890 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
1e8a0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
1e8b0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
1e8c0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
1e8d0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
1e8e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1e8f0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
1e900 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
1e910 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
1e920 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
1e930 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
1e940 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
1e950 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
1e960 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
1e970 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
1e980 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
1e990 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
1e9a0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
1e9b0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
1e9c0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
1e9d0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
1e9e0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
1e9f0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
1ea00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
1ea10 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
1ea20 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
1ea30 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
1ea40 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
1ea50 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
1ea60 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
1ea70 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
1ea80 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
1ea90 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
1eaa0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
1eab0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
1eac0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
1ead0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
1eae0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
1eaf0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
1eb00 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
1eb10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1eb20 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
1eb30 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
1eb40 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
1eb50 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
1eb60 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
1eb70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
1eb80 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
1eb90 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
1eba0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
1ebb0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
1ebc0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
1ebd0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1ebe0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
1ebf0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1ec00 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
1ec10 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1ec20 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
1ec30 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
1ec40 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
1ec50 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
1ec60 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
1ec70 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
1ec80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
1ec90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
1eca0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
1ecb0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
1ecc0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
1ecd0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
1ece0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1ecf0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
1ed00 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
1ed10 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
1ed20 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
1ed30 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
1ed40 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
1ed50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
1ed60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
1ed70 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
1ed80 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
1ed90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1eda0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1edb0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
1edc0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
1edd0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
1ede0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
1edf0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
1ee00 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
1ee10 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
1ee20 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
1ee30 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
1ee40 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
1ee50 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
1ee60 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
1ee70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
1ee80 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
1ee90 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
1eea0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
1eeb0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
1eec0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
1eed0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
1eee0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
1eef0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
1ef00 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1ef10 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
1ef20 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
1ef30 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
1ef40 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
1ef50 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
1ef60 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
1ef70 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
1ef80 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
1ef90 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
1efa0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
1efb0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
1efc0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
1efd0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
1efe0 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
1eff0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f000 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1f010 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f020 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
1f030 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
1f040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1f050 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1f060 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
1f070 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
1f080 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
1f090 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
1f0a0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
1f0b0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
1f0c0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
1f0d0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
1f0e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
1f0f0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1f100 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1f110 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33  * [H13202] [H153
1f120 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31  04] [H15306] [H1
1f130 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a  5308] [H15310].*
1f140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
1f150 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
1f160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f170 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
1f180 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
1f190 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
1f1a0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
1f1b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1f1c0 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
1f1d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
1f1e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
1f1f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1f200 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d  nts:.** [H13771]
1f210 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74   [H13772].*/.int
1f220 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
1f230 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1f240 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1f250 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
1f260 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
1f270 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31   {H10265} <S1011
1f280 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45  0><S10120>.** KE
1f290 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
1f2a0 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36  EXT.**.** {H1026
1f2b0 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  6} Every value i
1f2c0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
1f2d0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
1f2e0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
1f2f0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
1f300 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
1f310 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
1f320 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
1f330 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
1f340 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
1f350 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
1f360 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
1f370 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
1f380 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1f390 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
1f3a0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
1f3b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
1f3c0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
1f3d0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
1f3e0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
1f3f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
1f400 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
1f410 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
1f420 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
1f430 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
1f440 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
1f450 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
1f460 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1f470 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
1f480 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
1f490 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
1f4a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f4b0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
1f4c0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
1f4d0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1f4e0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
1f4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
1f500 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
1f510 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
1f520 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
1f530 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
1f540 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
1f550 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1f560 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
1f570 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
1f580 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
1f590 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b  s From A Query {
1f5a0 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e  H13800} <S10700>
1f5b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
1f5c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1f5d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
1f5e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
1f5f0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
1f600 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61  t query" interfa
1f610 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ce..**.** These 
1f620 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f630 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
1f640 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
1f650 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
1f660 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
1f670 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
1f680 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
1f690 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
1f6a0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
1f6b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f6c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
1f6d0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
1f6e0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1f6f0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
1f700 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
1f710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f720 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
1f730 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
1f740 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
1f750 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1f760 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
1f770 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
1f780 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
1f790 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
1f7a0 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
1f7b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
1f7c0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
1f7d0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20   index 0..**.** 
1f7e0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
1f7f0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
1f800 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
1f810 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
1f820 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
1f830 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
1f840 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
1f850 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
1f860 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1f870 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
1f880 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
1f890 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
1f8a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1f8b0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
1f8c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
1f8d0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
1f8e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1f8f0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
1f900 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
1f910 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
1f920 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
1f930 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
1f940 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1f950 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
1f960 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
1f970 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f980 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
1f990 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
1f9a0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
1f9b0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
1f9c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
1f9d0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
1f9e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
1f9f0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
1fa00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1fa10 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
1fa20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1fa30 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
1fa40 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
1fa50 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
1fa60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1fa70 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
1fa80 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
1fa90 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
1faa0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1fab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
1fac0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1fad0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
1fae0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
1faf0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
1fb00 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
1fb10 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
1fb20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
1fb30 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
1fb40 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
1fb50 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
1fb60 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
1fb70 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
1fb80 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
1fb90 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
1fba0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
1fbb0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1fbc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
1fbd0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
1fbe0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
1fbf0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
1fc00 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
1fc10 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
1fc20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
1fc30 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
1fc40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1fc50 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
1fc60 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
1fc70 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
1fc80 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
1fc90 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
1fca0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
1fcb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1fcc0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
1fcd0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
1fce0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
1fcf0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
1fd00 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
1fd10 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
1fd20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
1fd30 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
1fd40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1fd50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1fd60 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
1fd70 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
1fd80 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
1fd90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
1fda0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
1fdb0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
1fdc0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
1fdd0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
1fde0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1fdf0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
1fe00 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
1fe10 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
1fe20 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
1fe30 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
1fe40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
1fe50 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
1fe60 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
1fe70 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
1fe80 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
1fe90 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1fea0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
1feb0 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
1fec0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
1fed0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
1fee0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
1fef0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
1ff00 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
1ff10 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
1ff20 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
1ff30 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
1ff40 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
1ff50 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
1ff60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1ff70 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20  ..**.** Strings 
1ff80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ff90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1ffa0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
1ffb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
1ffc0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
1ffd0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
1ffe0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
1fff0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a  .  The return.**
20000 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
20010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
20020 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
20030 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
20040 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
20050 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
20060 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
20070 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
20080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
20090 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
200a0 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
200b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
200c0 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
200d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
200e0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
200f0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
20100 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
20110 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
20120 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
20130 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
20140 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
20150 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
20160 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20170 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
20180 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
20190 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
201a0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
201b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
201c0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
201d0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
201e0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
201f0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
20200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
20210 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
20220 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
20230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
20240 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
20250 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
20260 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
20270 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
20280 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
20290 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
202a0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
202b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
202c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
202d0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
202e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
202f0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
20300 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
20310 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
20320 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
20330 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
20340 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
20350 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
20360 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
20370 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
20380 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
20390 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
203a0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
203b0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
203c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
203d0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
203e0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
203f0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
20400 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
20410 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
20420 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
20430 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
20440 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
20450 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
20460 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
20470 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
20480 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
20490 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
204a0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
204b0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
204c0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
204d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
204e0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
204f0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
20500 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20510 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
20520 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
20530 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20540 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
20550 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
20560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
20570 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20580 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
20590 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
205a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
205b0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
205c0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
205d0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
205e0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
205f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
20600 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
20610 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
20620 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
20630 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
20640 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
20650 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
20660 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
20670 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
20680 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20690 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
206a0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
206b0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
206c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
206d0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
206e0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
206f0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
20700 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
20710 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
20720 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
20730 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
20740 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
20750 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
20760 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
20770 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
20780 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
20790 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
207a0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
207b0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
207c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
207d0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
207e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
207f0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
20800 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
20810 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
20820 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
20830 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
20840 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
20850 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
20860 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
20870 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20880 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
20890 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
208a0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
208b0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
208c0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
208d0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
208e0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
208f0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
20900 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
20910 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
20920 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
20930 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
20940 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
20950 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
20960 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
20970 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
20980 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
20990 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
209a0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
209b0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
209c0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
209d0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
209e0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
209f0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
20a00 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
20a10 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
20a20 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
20a30 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
20a40 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
20a50 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
20a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20a70 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
20a80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
20a90 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
20aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
20ab0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
20ac0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
20ad0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
20ae0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
20af0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
20b00 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
20b10 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
20b20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
20b30 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
20b40 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
20b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20b60 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
20b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20b80 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
20b90 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
20ba0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
20bb0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
20bc0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
20bd0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
20be0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
20bf0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
20c00 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
20c10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
20c20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
20c30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
20c40 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
20c50 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
20c60 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
20c70 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
20c80 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
20c90 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
20ca0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
20cb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
20cc0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
20cd0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
20ce0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
20cf0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
20d00 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
20d10 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
20d20 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
20d30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
20d40 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
20d50 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
20d60 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
20d70 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
20d80 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
20d90 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
20da0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
20db0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
20dc0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
20dd0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
20de0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
20df0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
20e00 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
20e10 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
20e20 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
20e30 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
20e40 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
20e50 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
20e60 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
20e70 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
20e80 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
20e90 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
20ea0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
20eb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
20ec0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
20ed0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
20ee0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
20ef0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
20f00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
20f10 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
20f20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
20f30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20f40 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
20f50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
20f60 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
20f70 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
20f80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
20f90 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
20fa0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
20fb0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
20fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
20fd0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
20fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20ff0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
21000 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
21010 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
21020 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
21030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21040 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
21050 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
21060 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21070 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
21080 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
21090 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
210a0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
210b0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
210c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
210d0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
210e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
210f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
21100 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
21110 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
21120 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
21130 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
21140 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
21150 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
21160 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
21170 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
21180 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
21190 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
211a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
211b0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
211c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
211d0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
211e0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
211f0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
21200 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
21210 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
21220 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
21230 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
21240 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21250 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
21260 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
21270 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21280 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
21290 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
212a0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
212b0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
212c0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
212d0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
212e0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
212f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
21300 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
21310 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
21320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21330 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
21340 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
21350 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
21360 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
21370 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
21380 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
21390 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
213a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
213b0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
213c0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
213d0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
213e0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
213f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
21400 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
21410 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
21420 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
21430 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
21440 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
21450 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
21460 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
21470 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
21480 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
21490 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 31  .** [H13803] [H1
214a0 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b  3806] [H13809] [
214b0 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 35 5d  H13812] [H13815]
214c0 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 38 32   [H13818] [H1382
214d0 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b  1] [H13824].** [
214e0 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 30 5d  H13827] [H13830]
214f0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
21500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21510 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
21520 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
21530 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
21540 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
21550 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
21570 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
21580 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21590 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
215a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
215b0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
215c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
215d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
215e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
215f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
21600 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
21610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
21620 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21630 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
21640 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
21650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21660 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
21670 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
21680 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
216a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
216b0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
216c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
216d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
216e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
216f0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
21700 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
21710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21720 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
21730 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
21740 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
21750 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
21760 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13300} <S70300>
21770 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
21780 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
21790 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
217a0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
217b0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
217c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
217d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
217e0 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
217f0 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
21800 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
21810 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
21820 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
21830 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
21840 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
21850 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
21860 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
21870 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
21880 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
21890 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
218a0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
218b0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
218c0 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
218d0 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
218e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
218f0 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
21900 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
21910 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
21920 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
21930 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
21940 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
21950 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
21960 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
21970 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
21980 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
21990 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70  rupt]..** Incomp
219a0 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
219b0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
219c0 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
219d0 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65   canceled,.** de
219e0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
219f0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
21a00 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20  d the.** [error 
21a10 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
21a20 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
21a30 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  BORT]..**.** Req
21a40 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
21a50 31 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a  11302] [H11304].
21a60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
21a70 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
21a80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
21a90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
21aa0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
21ab0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
21ac0 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30   {H13330} <S7030
21ad0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
21ae0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
21af0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
21b00 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
21b10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
21b20 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
21b30 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
21b40 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
21b50 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
21b60 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
21b70 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
21b80 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
21b90 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
21ba0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
21bb0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
21bc0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
21bd0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
21be0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
21bf0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
21c00 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
21c10 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
21c20 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20  .**.** {H11332} 
21c30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
21c40 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
21c50 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
21c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21c70 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
21c80 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
21c90 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
21ca0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ram..**.** {H113
21cb0 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} If the most 
21cc0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
21cd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21ce0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
21cf0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
21d00 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
21d10 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
21d20 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
21d30 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
21d40 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
21d50 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
21d60 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
21d70 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
21d80 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
21d90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
21da0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
21db0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  K]..**.** {H1133
21dc0 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
21dd0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
21de0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
21df0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
21e00 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
21e10 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
21e20 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
21e30 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
21e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
21e50 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
21e60 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
21e70 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48   code]..**.** {H
21e80 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69  11338} The [sqli
21e90 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
21ea0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
21eb0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
21ec0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
21ed0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
21ee0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
21ef0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
21f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
21f10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21f20 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
21f30 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
21f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
21f50 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
21f60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
21f70 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H16100} <S20200>
21f80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
21f90 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
21fa0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
21fb0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
21fc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
21fd0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
21fe0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
21ff0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
22000 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
22010 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63  * These two func
22020 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
22030 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
22040 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
22050 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
22060 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
22070 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
22080 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
22090 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
220a0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
220b0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
220c0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
220d0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
220e0 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
220f0 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
22100 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
22110 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
22120 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
22130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
22140 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
22150 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
22160 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
22170 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
22180 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
22190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
221a0 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
221b0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
221c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
221d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
221e0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
221f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
22200 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
22210 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f   If a single pro
22220 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
22230 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
22240 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
22250 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
22260 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
22270 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
22280 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65  vidually to.** e
22290 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
222a0 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  nection..**.** T
222b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
222c0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
222d0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
222e0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
222f0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
22300 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  d.  The length o
22310 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
22320 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
22330 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
22340 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
22350 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
22360 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
22370 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
22380 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
22390 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
223a0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
223b0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
223c0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
223d0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
223e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
223f0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
22400 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
22410 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
22420 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
22430 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
22440 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
22450 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
22460 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
22470 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
22480 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
22490 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
224a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
224b0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
224c0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
224d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
224e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
224f0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
22500 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
22510 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
22520 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
22530 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
22540 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
22550 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
22560 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
22570 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
22580 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
22590 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
225a0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
225b0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
225c0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
225d0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
225e0 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
225f0 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
22600 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
22610 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74   It is allowed t
22620 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
22630 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
22640 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
22650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
22660 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
22670 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
22680 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
22690 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
226a0 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
226b0 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c  Rep..** When mul
226c0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
226d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
226e0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
226f0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
22700 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
22710 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
22720 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
22730 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
22740 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
22750 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
22760 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
22770 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
22780 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
22790 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
227a0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
227b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
227c0 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
227d0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
227e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
227f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
22800 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
22810 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22820 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
22830 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
22840 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
22850 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
22860 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
22870 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
22880 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
22890 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
228a0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
228b0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
228c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
228d0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
228e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
228f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
22900 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
22910 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
22920 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
22930 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
22940 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
22950 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
22960 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
22970 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
22980 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
22990 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
229a0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
229b0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
229c0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
229d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
229e0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
229f0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
22a00 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
22a10 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
22a20 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
22a30 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
22a40 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
22a50 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
22a60 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61  hree function ca
22a70 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49  llbacks..**.** I
22a80 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
22a90 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
22aa0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
22ab0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
22ac0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
22ad0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
22ae0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
22af0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
22b00 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
22b10 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
22b20 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
22b30 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65  codings.  SQLite
22b40 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
22b50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22b60 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
22b70 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
22b80 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
22b90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
22ba0 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69  d.  A function i
22bb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
22bc0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
22bd0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
22be0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
22bf0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
22c00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
22c10 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
22c20 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41  egative nArg.  A
22c30 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
22c40 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
22c50 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
22c60 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
22c70 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
22c80 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
22c90 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
22ca0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
22cb0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
22cc0 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69  t.  .** A functi
22cd0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
22ce0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
22cf0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
22d00 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
22d10 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
22d20 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
22d30 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
22d40 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
22d50 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
22d60 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
22d70 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20  .**.** Built-in 
22d80 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
22d90 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
22da0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
22db0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
22dc0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
22dd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
22de0 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ed function with
22df0 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76   a given name ov
22e00 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62  errides all.** b
22e10 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
22e20 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  s in the same [d
22e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22e40 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d  on] with the sam
22e50 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65  e name..** Subse
22e60 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  quent applicatio
22e70 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
22e80 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
22e90 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69  name only overri
22ea0 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70  de .** prior app
22eb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22ec0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
22ed0 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74  are an exact mat
22ee0 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75  ch for the.** nu
22ef0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
22f00 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64  rs and preferred
22f10 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
22f20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
22f30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
22f40 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
22f50 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
22f60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
22f70 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
22f80 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
22f90 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
22fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22fb0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
22fc0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
22fd0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
22fe0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
22ff0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
23000 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  g..**.** Require
23010 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30  ments:.** [H1610
23020 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36  3] [H16106] [H16
23030 31 30 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48  109] [H16112] [H
23040 31 36 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20  16118] [H16121] 
23050 5b 48 31 36 31 32 34 5d 20 5b 48 31 36 31 32 37  [H16124] [H16127
23060 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48  ].** [H16130] [H
23070 31 36 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20  16133] [H16136] 
23080 5b 48 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32  [H16139] [H16142
23090 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
230a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
230b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
230c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
230d0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
230e0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
230f0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
23100 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
23110 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
23120 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23130 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23140 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
23150 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
23160 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
23170 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
23180 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
23190 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
231a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
231b0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
231c0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
231d0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
231e0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
231f0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
23200 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
23210 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
23220 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23230 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
23240 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
23250 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
23260 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23270 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23280 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
23290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
232a0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
232b0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
232c0 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53  ings {H10267} <S
232d0 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a  50200> <H16100>.
232e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
232f0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
23300 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
23310 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
23320 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
23330 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
23340 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
23350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23360 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
23370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23380 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
23390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
233a0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
233b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
233c0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
233d0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
233e0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
233f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
23400 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
23410 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
23420 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
23430 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23440 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
23450 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
23460 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
23470 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
23480 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
23490 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
234a0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
234b0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
234c0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
234d0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
234e0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
234f0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
23500 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
23510 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
23520 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
23530 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
23540 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
23550 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
23560 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
23570 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
23580 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
23590 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
235a0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
235b0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
235c0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
235d0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
235e0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
235f0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
23600 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
23610 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
23620 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
23630 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
23640 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
23650 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
23660 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
23670 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
23680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
23690 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
236a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
236b0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
236c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
236d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
236e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
236f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
23700 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
23710 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23720 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
23730 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
23740 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
23750 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
23760 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
23770 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
23780 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
23790 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
237a0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
237b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
237c0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
237d0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
237e0 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30  r Values {H15100
237f0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
23800 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
23810 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
23820 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
23830 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
23840 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
23850 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
23860 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
23870 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
23880 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
23890 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
238a0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
238b0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
238c0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
238d0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
238e0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
238f0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
23900 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23910 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23920 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23930 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
23940 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
23950 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
23960 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
23970 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
23980 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
23990 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
239a0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
239b0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
239c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
239d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
239e0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
239f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
23a00 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
23a10 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
23a20 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
23a30 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
23a40 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
23a50 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
23a60 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
23a70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23a80 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
23a90 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
23aa0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
23ab0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23ac0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
23ad0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
23ae0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
23af0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
23b00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23b10 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
23b20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
23b30 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
23b40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
23b50 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
23b60 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
23b70 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
23b80 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
23b90 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
23ba0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
23bb0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
23bc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23bd0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
23be0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
23bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
23c00 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
23c10 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
23c20 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  umber..**.** The
23c30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
23c40 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
23c50 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
23c60 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
23c70 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
23c80 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
23c90 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
23ca0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
23cb0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
23cc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
23cd0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
23ce0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
23cf0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
23d00 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
23d10 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
23d20 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
23d30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
23d40 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
23d50 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
23d60 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
23d70 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
23d80 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
23d90 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
23da0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
23db0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
23dc0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
23dd0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
23de0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
23df0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
23e00 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
23e10 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
23e20 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
23e30 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
23e40 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
23e50 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
23e60 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
23e70 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
23e80 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
23e90 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
23ea0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
23eb0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
23ec0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
23ed0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
23ee0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
23ef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
23f00 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
23f10 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
23f20 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
23f30 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
23f40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
23f50 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
23f60 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
23f70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
23f80 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
23f90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
23fa0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
23fb0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
23fc0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
23fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
23fe0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
23ff0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
24000 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
24010 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
24020 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24030 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
24040 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24050 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
24060 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
24070 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
24080 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
24090 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
240a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
240b0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
240c0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
240d0 20 5b 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30   [H15103] [H1510
240e0 36 5d 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35  6] [H15109] [H15
240f0 31 31 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48  112] [H15115] [H
24100 31 35 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20  15118] [H15121] 
24110 5b 48 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35  [H15124].** [H15
24120 31 32 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48  127] [H15130] [H
24130 31 35 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a  15133] [H15136].
24140 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
24150 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
24160 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
24170 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
24180 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
24190 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
241a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
241b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
241c0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
241d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
241e0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
241f0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
24200 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
24210 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
24220 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
24230 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
24240 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
24250 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
24260 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
24270 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
24280 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
24290 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
242a0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
242b0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
242c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
242d0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
242e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
242f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
24300 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
24310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
24330 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
24340 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
24350 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
24360 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
24370 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
24380 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24390 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
243a0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36  ion Context {H16
243b0 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  210} <S20200>.**
243c0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
243d0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
243e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
243f0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
24400 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
24410 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
24420 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
24430 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  state..**.** The
24440 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
24450 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
24460 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
24470 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ine is called fo
24480 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  r a.** particula
24490 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
244a0 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
244b0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
244c0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a  zeroes out that.
244d0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  ** memory, and r
244e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
244f0 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e   to it. On secon
24500 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
24510 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
24520 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
24530 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
24540 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
24550 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a  function index,.
24560 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
24570 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
24580 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
24590 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  on of the aggreg
245a0 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74  ate can use.** t
245b0 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
245c0 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
245d0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
245e0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
245f0 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
24600 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
24610 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
24620 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
24630 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
24640 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
24650 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
24660 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
24670 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
24680 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
24690 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
246a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
246b0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
246c0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
246d0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
246e0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e  regate function.
246f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
24700 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
24710 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
24720 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
24730 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
24740 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
24750 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
24760 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
24770 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32  * [H16211] [H162
24780 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31  13] [H16215] [H1
24790 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73  6217].*/.void *s
247a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
247b0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
247c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
247d0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
247e0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
247f0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
24800 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
24810 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
24820 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
24830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24840 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
24850 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
24860 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
24870 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
24880 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
24890 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
248a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
248b0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
248c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
248d0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
248e0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
248f0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
24900 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
24910 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
24920 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
24930 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
24940 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
24950 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
24960 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
24970 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
24980 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
24990 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
249a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
249b0 2a 20 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f  * [H16243].*/.vo
249c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
249d0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
249e0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
249f0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
24a00 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
24a10 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
24a20 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32  250} <S60600><S2
24a30 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
24a40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
24a50 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
24a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
24a70 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
24a80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
24a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24aa0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
24ab0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
24ac0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
24ad0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
24ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
24af0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
24b00 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
24b10 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
24b20 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
24b30 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
24b40 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
24b50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
24b60 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73  ** [H16253].*/.s
24b70 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
24b80 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
24b90 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
24ba0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
24bb0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
24bc0 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48  uxiliary Data {H
24bd0 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16270} <S20200>.
24be0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
24bf0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
24c00 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
24c10 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
24c20 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
24c30 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
24c40 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
24c50 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
24c60 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
24c70 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
24c80 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
24c90 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
24ca0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
24cb0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
24cc0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
24cd0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
24ce0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
24cf0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
24d00 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
24d10 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
24d20 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
24d30 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
24d40 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
24d50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
24d60 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
24d70 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
24d80 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
24d90 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
24da0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
24db0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
24dc0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
24dd0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
24de0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
24df0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
24e00 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
24e10 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
24e20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
24e30 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
24e40 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
24e50 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
24e60 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
24e70 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
24e80 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
24e90 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
24ea0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
24eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
24ec0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
24ed0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
24ee0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
24ef0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
24f00 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
24f10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
24f20 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
24f30 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
24f40 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
24f50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24f60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66  ned function. If
24f70 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
24f80 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
24f90 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
24fa0 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
24fb0 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
24fc0 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
24fd0 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
24fe0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
24ff0 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
25000 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
25010 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
25020 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
25030 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
25040 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
25050 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
25060 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
25070 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
25080 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
25090 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
250a0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
250b0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
250c0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
250d0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
250e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
250f0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
25100 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
25110 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
25120 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
25130 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
25140 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
25150 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
25160 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e  * If it is not N
25170 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
25180 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
25190 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
251a0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
251b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
251c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
251d0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
251e0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
251f0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
25200 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
25210 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
25220 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
25230 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
25240 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
25250 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
25260 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
25270 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
25280 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
25290 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
252a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
252b0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
252c0 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f  any time.  The o
252d0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
252e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
252f0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
25300 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
25310 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
25320 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  opped..**.** In 
25330 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
25340 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
25350 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
25360 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
25370 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
25380 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
25390 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
253a0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
253b0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
253c0 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
253d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
253e0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
253f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
25400 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
25410 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
25420 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
25430 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
25440 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32  ents:.** [H16272
25450 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 32  ] [H16274] [H162
25460 37 36 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 31  76] [H16277] [H1
25470 36 32 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a  6278] [H16279].*
25480 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
25490 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
254a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
254b0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
254c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
254d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
254e0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
254f0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
25500 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
25510 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
25520 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
25530 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
25540 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31  r {H10280} <S301
25550 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
25560 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
25570 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
25580 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
25590 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
255a0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
255b0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
255c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
255d0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
255e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
255f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
25600 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
25610 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
25620 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
25630 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
25640 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
25650 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
25660 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
25670 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53  royed.  The.** S
25680 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
25690 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
256a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
256b0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
256c0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
256d0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
256e0 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
256f0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
25700 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
25710 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
25720 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
25730 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
25740 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
25750 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
25760 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
25770 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
25780 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
25790 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
257a0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
257b0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
257c0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
257d0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
257e0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
257f0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
25800 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
25810 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
25820 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
25830 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
25840 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
25850 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
25860 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31  SQL Function {H1
25870 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6400} <S20200>.*
25880 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25890 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
258a0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
258b0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
258c0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
258d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
258e0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
258f0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
25900 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25910 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
25920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
25930 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
25940 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25950 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
25960 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
25970 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
25980 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
25990 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
259a0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
259b0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
259c0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
259d0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
259e0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
259f0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
25a00 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
25a10 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
25a20 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
25a30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
25a40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
25a50 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
25a60 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
25a70 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
25a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
25a90 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
25aa0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
25ab0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
25ac0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
25ad0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
25ae0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
25af0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
25b00 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
25b10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
25b20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
25b30 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
25b40 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
25b50 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
25b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
25b70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
25b80 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
25b90 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
25ba0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
25bb0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
25bc0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
25bd0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
25be0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
25bf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
25c00 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
25c10 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
25c20 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
25c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25c40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
25c50 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
25c60 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
25c70 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
25c80 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
25c90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
25ca0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
25cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
25cc0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
25cd0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
25ce0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
25cf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
25d00 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
25d10 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
25d20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
25d30 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
25d40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
25d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
25d60 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
25d70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
25d80 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
25d90 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
25da0 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20  essage.  SQLite 
25db0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
25dc0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
25dd0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
25de0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
25df0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c  () as UTF-8. SQL
25e00 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
25e10 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
25e20 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
25e30 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
25e40 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
25e50 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
25e60 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
25e70 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25e80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
25e90 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
25ea0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
25eb0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
25ec0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
25ed0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
25ee0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
25ef0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
25f00 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
25f10 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
25f20 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25f30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
25f40 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
25f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
25f60 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
25f70 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
25f80 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
25f90 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
25fa0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
25fb0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
25fc0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
25fd0 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
25fe0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
25ff0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
26000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26010 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
26020 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
26030 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
26040 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
26050 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
26060 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
26070 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
26080 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
26090 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
260a0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
260b0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
260c0 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71   harm..** The sq
260d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
260e0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
260f0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
26100 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
26110 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
26120 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
26130 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
26140 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75  ction.  By defau
26150 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
26160 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
26170 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71  ERROR.  A subseq
26180 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
26190 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
261a0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
261b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
261c0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
261d0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
261e0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
261f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
26200 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
26210 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
26220 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
26230 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
26240 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
26250 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
26260 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
26270 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
26280 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
26290 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
262a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
262b0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
262c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
262d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
262e0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
262f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26300 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
26310 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
26320 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
26330 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
26340 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26350 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
26360 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
26370 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
26380 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
26390 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
263a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
263b0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
263c0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
263d0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
263e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
263f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26400 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
26410 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
26420 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
26430 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
26440 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26450 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
26460 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26470 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
26480 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
26490 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
264a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
264b0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
264c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
264d0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
264e0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
264f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26500 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
26510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26520 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
26530 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
26540 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
26550 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
26560 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26570 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
26580 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
26590 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
265a0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
265b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
265c0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
265d0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
265e0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
265f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
26600 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
26610 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
26620 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
26630 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
26640 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
26650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26660 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
26670 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  es..** If the 3r
26680 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
26690 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
266a0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
266b0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
266c0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
266d0 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
266e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
266f0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
26700 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
26710 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
26720 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
26730 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
26740 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26750 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
26760 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
26770 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
26780 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
26790 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
267a0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
267b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
267c0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
267d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
267e0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
267f0 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
26800 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
26810 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
26820 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
26830 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
26840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26850 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
26860 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
26870 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
26880 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
26890 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
268a0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
268b0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
268c0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
268d0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
268e0 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
268f0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
26900 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
26910 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
26920 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69  faces or.** sqli
26930 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
26940 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
26950 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
26960 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
26970 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
26980 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
26990 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
269a0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
269b0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
269c0 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63  copy the it or c
269d0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
269e0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
269f0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
26a00 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
26a10 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
26a20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
26a30 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
26a40 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
26a50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
26a60 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
26a70 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
26a80 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
26a90 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
26aa0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
26ab0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
26ac0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
26ad0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
26ae0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
26af0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
26b00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26b10 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
26b20 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
26b30 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
26b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26b50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
26b60 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
26b70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
26b80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26b90 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
26ba0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
26bb0 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
26bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
26bd0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
26be0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
26bf0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26c00 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
26c10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
26c20 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
26c30 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
26c40 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
26c50 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
26c60 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
26c70 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
26c80 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
26c90 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73  * A [protected s
26ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26cb0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
26cc0 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
26cd0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
26ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
26cf0 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
26d00 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
26d10 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
26d20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26d30 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
26d40 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
26d50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
26d60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
26d70 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
26d80 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
26d90 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
26da0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
26db0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26dc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26dd0 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
26de0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
26df0 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
26e00 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26e10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26e20 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
26e30 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36  ** [H16403] [H16
26e40 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48  406] [H16409] [H
26e50 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20  16412] [H16415] 
26e60 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31  [H16418] [H16421
26e70 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48  ] [H16424].** [H
26e80 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20  16427] [H16430] 
26e90 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36  [H16433] [H16436
26ea0 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34  ] [H16439] [H164
26eb0 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31  42] [H16445] [H1
26ec0 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31  6448].** [H16451
26ed0 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34  ] [H16454] [H164
26ee0 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31  57] [H16460] [H1
26ef0 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71  6463].*/.void sq
26f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
26f10 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
26f20 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
26f30 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
26f40 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
26f50 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
26f60 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
26f70 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
26f80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
26f90 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
26fa0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
26fb0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
26fc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26fd0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
26fe0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
26ff0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
27000 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27010 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
27020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
27030 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27040 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
27050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27060 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
27070 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
27080 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
27090 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
270a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
270b0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
270c0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
270d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
270e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
270f0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
27100 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
27110 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
27120 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27130 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27140 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
27150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27160 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
27170 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27180 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27190 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
271a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
271b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
271c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
271d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
271e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
271f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27200 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
27210 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
27220 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27230 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
27240 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27250 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
27260 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
27270 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27280 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
27290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
272a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
272b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
272c0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
272d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
272e0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
272f0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
27300 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
27310 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20  uences {H16600} 
27320 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
27330 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
27340 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
27350 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
27360 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
27370 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27380 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
27390 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
273a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
273b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
273c0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
273d0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
273e0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
273f0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
27400 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27410 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
27420 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27430 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
27440 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
27450 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
27460 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
27470 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
27480 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
27490 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
274a0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
274b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
274c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
274d0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
274e0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
274f0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
27500 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
27510 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
27520 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
27530 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
27540 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
27550 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
27560 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
27570 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
27580 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
27590 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
275a0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
275b0 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70  big-endian, resp
275c0 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a  ectively. The.**
275d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
275e0 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53  might also be [S
275f0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
27600 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  NED] to indicate
27610 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75   that.** the rou
27620 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
27630 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
27640 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
27650 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31  ings.** of UTF-1
27660 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
27670 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
27680 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
27690 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
276a0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
276b0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
276c0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
276d0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
276e0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
276f0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
27700 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
27710 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
27720 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
27730 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
27740 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
27750 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
27760 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
27770 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
27780 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
27790 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
277a0 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
277b0 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
277c0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
277d0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
277e0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
277f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27800 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
27810 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27820 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
27830 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
27840 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
27850 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
27860 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
27870 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
27880 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
27890 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
278a0 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
278b0 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
278c0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
278d0 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
278e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
278f0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
27900 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
27910 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
27920 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c   {END}  The appl
27930 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
27940 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
27950 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
27960 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
27970 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
27980 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
27990 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
279a0 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
279b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
279c0 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
279d0 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
279e0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
279f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
27a00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27a10 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
27a20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
27a30 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
27a40 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
27a50 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
27a60 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
27a70 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
27a80 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
27a90 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
27aa0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
27ab0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
27ac0 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
27ad0 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
27ae0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
27af0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
27b00 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
27b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27b20 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
27b30 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
27b40 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
27b50 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
27b60 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
27b70 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
27b80 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
27b90 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
27ba0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
27bb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
27bc0 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
27bd0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
27be0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
27bf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33  ents:.** [H16603
27c00 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31 36 36  ] [H16604] [H166
27c10 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b 48 31  06] [H16609] [H1
27c20 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b  6612] [H16615] [
27c30 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32 31 5d  H16618] [H16621]
27c40 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b 48 31  .** [H16624] [H1
27c50 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a  6627] [H16630].*
27c60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
27c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
27c80 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
27c90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
27ca0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
27cb0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
27cc0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
27cd0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
27ce0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
27cf0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
27d00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
27d10 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
27d20 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
27d30 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
27d40 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
27d50 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
27d60 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
27d70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
27d80 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
27d90 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
27da0 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
27db0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27dc0 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
27dd0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
27de0 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
27df0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
27e00 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
27e10 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
27e20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
27e30 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
27e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27e50 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
27e60 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ded Callbacks {H
27e70 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a  16700} <S20300>.
27e80 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68  **.** To avoid h
27e90 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
27ea0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
27eb0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
27ec0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
27ed0 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
27ee0 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
27ef0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
27f00 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
27f10 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
27f20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
27f30 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
27f40 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
27f50 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
27f60 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
27f70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
27f80 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
27f90 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
27fa0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
27fb0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
27fc0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
27fd0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
27fe0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
27ff0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
28000 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
28010 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b  oded in UTF-8. {
28020 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74  H16703} If sqlit
28030 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28040 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
28050 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
28060 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
28070 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
28080 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
28090 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69  .** A call to ei
280a0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
280b0 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74  places any exist
280c0 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ing callback..**
280d0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
280e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
280f0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
28100 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
28110 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
28120 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
28130 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
28140 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
28150 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
28160 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
28170 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
28180 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
28190 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
281a0 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
281b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
281c0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
281d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
281e0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
281f0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
28200 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
28210 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
28220 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
28230 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
28240 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
28250 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
28260 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
28270 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
28280 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
28290 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  equence..**.** T
282a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
282b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
282c0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
282d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
282e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
282f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
28300 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
28310 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
28320 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
28330 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
28340 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  n_v2()]..**.** R
28350 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
28360 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37 30 34  [H16702] [H16704
28370 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e  ] [H16706].*/.in
28380 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
28390 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
283a0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
283b0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
283c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
283d0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
283e0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
283f0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
28400 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
28410 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
28420 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
28430 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
28440 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
28450 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
28460 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
28470 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
28480 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
28490 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
284a0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
284b0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
284c0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
284d0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
284e0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
284f0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
28500 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
28510 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
28520 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
28530 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
28540 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
28550 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28560 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
28570 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
28580 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
28590 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
285a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
285b0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
285c0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
285d0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
285e0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
285f0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
28600 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
28610 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
28620 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
28630 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
28640 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
28650 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
28660 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
28670 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
28680 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
28690 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
286a0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
286b0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
286c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
286d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
286e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
286f0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
28700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
28710 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
28720 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
28730 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
28740 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
28750 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
28760 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
28770 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
28780 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
28790 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
287a0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
287b0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
287c0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
287d0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
287e0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
287f0 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
28800 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
28810 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
28820 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
28830 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
28840 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
28850 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
28860 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
28870 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
28880 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
28890 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
288a0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
288b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
288c0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
288d0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
288e0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
288f0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
28900 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
28910 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
28920 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
28930 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
28940 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
28950 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
28960 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
28970 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
28980 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
28990 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31 30 35  : [H10533] [H105
289a0 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  36].*/.int sqlit
289b0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
289c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
289d0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
289e0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
289f0 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33  rary Files {H103
28a00 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  10} <S20000>.**.
28a10 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
28a20 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
28a30 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
28a40 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
28a50 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
28a60 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
28a70 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
28a80 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
28a90 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
28aa0 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   by SQLite will 
28ab0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
28ac0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66  t directory.  If
28ad0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
28ae0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
28af0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
28b00 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
28b10 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
28b20 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
28b30 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
28b40 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
28b50 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
28b60 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
28b70 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
28b80 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
28b90 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
28ba0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
28bb0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
28bc0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
28bd0 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
28be0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
28bf0 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
28c00 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
28c10 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
28c20 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
28c30 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
28c40 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
28c50 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
28c60 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
28c70 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
28c80 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
28c90 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
28ca0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
28cb0 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
28cc0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
28cd0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
28ce0 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
28cf0 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f 73 74  .** The [temp_st
28d00 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
28d10 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
28d20 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
28d30 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
28d40 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
28d50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
28d60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
28d70 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a  .  Furthermore,.
28d80 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
28d90 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
28da0 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
28db0 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
28dc0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
28dd0 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
28de0 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
28df0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
28e00 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
28e10 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
28e20 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
28e30 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
28e40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
28e50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
28e60 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
28e70 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
28e80 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
28e90 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
28ea0 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
28eb0 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
28ec0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
28ed0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
28ee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
28ef0 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
28f00 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
28f10 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
28f20 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
28f30 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
28f40 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
28f50 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
28f60 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
28f70 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
28f80 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
28f90 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32  e {H12930} <S602
28fa0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
28fb0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
28fc0 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e}.**.** The sql
28fd0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
28fe0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
28ff0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
29000 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
29010 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
29020 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
29030 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
29040 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
29050 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
29060 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
29070 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
29080 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
29090 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
290a0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
290b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f  atement..** Auto
290c0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
290d0 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
290e0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
290f0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
29100 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
29110 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
29120 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
29130 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
29140 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
29150 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
29160 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
29170 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
29180 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
29190 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
291a0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
291b0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
291c0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
291d0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
291e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
291f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
29200 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
29210 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
29220 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
29230 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
29240 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
29250 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
29260 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
29270 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
29280 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
29290 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
292a0 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
292b0 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
292c0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
292d0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
292e0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
292f0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
29300 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
29310 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  fined..**.** Req
29320 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39  uirements: [H129
29330 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48 31  31] [H12932] [H1
29340 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a  2933] [H12934].*
29350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
29360 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
29370 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
29380 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
29390 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
293a0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
293b0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32  Statement {H1312
293c0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S60600>.**.*
293d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
293e0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
293f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
29400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29410 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
29420 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
29430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
29440 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74  longs.  The [dat
29450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29460 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
29470 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
29480 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
29490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
294a0 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68  ion] that was th
294b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
294c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
294d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
294e0 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
294f0 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
29500 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
29510 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
29520 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
29530 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  lace..**.** Requ
29540 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32  irements: [H1312
29550 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  3].*/.sqlite3 *s
29560 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
29570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29590 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
295a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
295b0 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30  nt {H13140} <S60
295c0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
295d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
295e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
295f0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
29600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
29610 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
29620 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
29630 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29640 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
29650 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
29660 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
29670 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
29680 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
29690 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
296a0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
296b0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
296c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
296d0 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65   pDb.  If no pre
296e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
296f0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
29700 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
29710 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
29720 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
29730 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
29740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
29750 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
29760 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
29770 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
29780 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
29790 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
297a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
297b0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
297c0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
297d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
297e0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
297f0 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31 34 36  [H13143] [H13146
29800 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31 33 31  ] [H13149] [H131
29810 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73  52].*/.sqlite3_s
29820 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78  tmt *sqlite3_nex
29830 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a  t_stmt(sqlite3 *
29840 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  pDb, sqlite3_stm
29850 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29860 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
29870 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
29880 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
29890 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20  lbacks {H12950} 
298a0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
298b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
298c0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
298d0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
298e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
298f0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
29900 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
29910 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
29920 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
29930 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
29940 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
29950 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
29960 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
29970 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
29980 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
29990 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
299a0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
299b0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
299c0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
299d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
299e0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
299f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
29a00 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
29a10 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
29a20 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
29a30 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
29a40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
29a50 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
29a60 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
29a70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
29a80 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
29a90 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
29aa0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
29ab0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
29ac0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
29ad0 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
29ae0 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
29af0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
29b00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
29b10 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
29b20 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
29b30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
29b40 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
29b50 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
29b60 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
29b70 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
29b80 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
29b90 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
29ba0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  d..**.** The cal
29bb0 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
29bc0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
29bd0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
29be0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
29bf0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
29c00 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
29c10 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
29c20 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
29c30 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
29c40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29c50 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
29c60 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
29c70 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
29c80 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
29c90 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
29ca0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
29cb0 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
29cc0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
29cd0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
29ce0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
29cf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29d00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
29d10 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
29d20 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
29d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29d40 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
29d50 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
29d60 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
29d70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  h..**.** Registe
29d80 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
29d90 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
29da0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
29db0 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
29dc0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
29dd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
29de0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
29df0 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
29e00 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
29e10 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
29e20 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
29e30 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
29e40 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
29e50 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
29e60 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
29e70 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  ccur..** The rol
29e80 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
29e90 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
29ea0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
29eb0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
29ec0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
29ed0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
29ee0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29ef0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65  s closed..** The
29f00 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
29f10 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
29f20 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
29f30 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20  on is.** rolled 
29f40 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63  back because a c
29f50 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
29f60 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f  eturned non-zero
29f70 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63  ..** <todo> Chec
29f80 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f  k on this </todo
29f90 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  >.**.** Requirem
29fa0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31  ents:.** [H12951
29fb0 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39  ] [H12952] [H129
29fc0 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31  53] [H12954] [H1
29fd0 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31  2955].** [H12961
29fe0 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39  ] [H12962] [H129
29ff0 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a  63] [H12964].*/.
2a000 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2a010 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
2a020 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
2a030 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
2a040 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
2a050 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
2a060 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
2a070 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2a080 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
2a090 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
2a0a0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
2a0b0 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12970} <S60400>.
2a0c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a0d0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
2a0e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2a0f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
2a100 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
2a110 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2a120 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
2a130 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
2a140 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2a150 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2a160 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
2a170 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2a180 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
2a190 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2a1a0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2a1b0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
2a1c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
2a1d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2a1e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2a1f0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
2a200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2a210 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2a220 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
2a230 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
2a240 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
2a250 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2a260 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69  leted..** The fi
2a270 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2a280 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2a290 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
2a2a0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
2a2b0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2a2c0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65  e_hook()..** The
2a2d0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
2a2e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2a2f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
2a300 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
2a310 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
2a320 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
2a330 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
2a340 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
2a350 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
2a360 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
2a370 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  d..** The third 
2a380 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
2a390 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
2a3a0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
2a3b0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
2a3c0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
2a3d0 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
2a3e0 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
2a3f0 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61  row..** The fina
2a400 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2a410 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
2a420 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
2a430 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  ** In the case o
2a440 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
2a450 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
2a460 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
2a470 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
2a480 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2a490 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2a4a0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2a4b0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2a4c0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2a4d0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2a4e0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2a4f0 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
2a500 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2a510 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2a520 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
2a530 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
2a540 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
2a550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a560 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
2a570 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
2a580 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2a590 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2a5a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a5b0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2a5c0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2a5d0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2a5e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2a5f0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2a600 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
2a610 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
2a620 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2a630 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a640 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2a650 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2a660 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2a670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2a680 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2a690 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2a6a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2a6b0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
2a6c0 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
2a6d0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2a6e0 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75  d, its pArg valu
2a6f0 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  e.** is returned
2a700 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
2a710 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
2a720 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2a730 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b  s:.** [H12971] [
2a740 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d  H12973] [H12975]
2a750 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37   [H12977] [H1297
2a760 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32  9] [H12981] [H12
2a770 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f  983] [H12986].*/
2a780 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2a790 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2a7a0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2a7b0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2a7c0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2a7d0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2a7e0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2a7f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2a800 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2a810 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2a820 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33  ger Cache {H1033
2a830 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b  0} <S30900>.** K
2a840 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
2a850 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20   cache} {shared 
2a860 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  cache mode}.**.*
2a870 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
2a880 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2a890 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2a8a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2a8b0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2a8c0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2a8d0 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
2a8e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a8f0 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
2a900 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
2a910 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
2a920 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
2a930 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
2a940 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
2a950 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2a960 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  nt is false..**.
2a970 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
2a980 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2a990 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2a9a0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2a9b0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2a9c0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2a9d0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2a9e0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2a9f0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2aa00 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2aa10 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2aa20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2aa30 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2aa40 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
2aa50 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
2aa60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
2aa70 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
2aa80 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2aa90 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2aaa0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2aab0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
2aac0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2aad0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
2aae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2aaf0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
2ab00 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
2ab10 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
2ab20 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
2ab30 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
2ab40 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
2ab50 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
2ab60 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
2ab70 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
2ab80 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
2ab90 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
2aba0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2abb0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
2abc0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
2abd0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
2abe0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
2abf0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
2ac00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2ac10 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2ac20 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2ac30 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2ac40 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2ac50 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2ac60 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2ac70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2ac80 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53  herwise..**.** S
2ac90 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2aca0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2acb0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2acc0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2acd0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2ace0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2acf0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2ad00 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2ad10 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2ad20 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2ad30 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2ad40 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2ad50 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2ad60 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71   Mode].**.** Req
2ad70 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33  uirements: [H103
2ad80 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31  31] [H10336] [H1
2ad90 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a  0337] [H10339].*
2ada0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2adb0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2adc0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2add0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2ade0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2adf0 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53  mory {H17340} <S
2ae00 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2ae10 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2ae20 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2ae30 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2ae40 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
2ae50 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2ae60 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2ae70 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2ae80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
2ae90 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
2aea0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
2aeb0 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
2aec0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2aed0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2aee0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2aef0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2af00 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2af10 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2af20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2af30 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2af40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2af50 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2af60 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2af70 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2af80 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2af90 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2afa0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2afb0 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37  s: [H17341] [H17
2afc0 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  342].*/.int sqli
2afd0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2afe0 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2aff0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2b000 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2b010 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c   Size {H17350} <
2b020 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2b030 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2b040 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2b050 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
2b060 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
2b070 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2b080 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2b090 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2b0a0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
2b0b0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2b0c0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2b0d0 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2b0e0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2b0f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2b100 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2b110 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2b120 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2b130 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2b140 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2b150 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2b160 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2b170 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rmed..**.** The 
2b180 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
2b190 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
2b1a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2b1b0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2b1c0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2b1d0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2b1e0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2b1f0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2b200 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2b210 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2b220 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2b230 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2b240 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2b250 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
2b260 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
2b270 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
2b280 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
2b290 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
2b2a0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
2b2b0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
2b2c0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
2b2d0 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
2b2e0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
2b2f0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2b300 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2b310 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2b320 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
2b330 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2b340 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2b350 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2b360 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2b370 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2b380 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2b390 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2b3a0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2b3b0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2b3c0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
2b3d0 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
2b3e0 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
2b3f0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
2b400 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
2b410 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
2b420 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
2b430 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
2b440 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
2b450 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
2b460 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
2b470 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
2b480 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
2b490 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
2b4a0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
2b4b0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
2b4c0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
2b4d0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
2b4e0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2b4f0 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
2b500 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
2b510 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
2b520 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2b530 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
2b540 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
2b550 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
2b560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
2b570 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
2b580 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
2b590 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
2b5a0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
2b5b0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
2b5c0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
2b5d0 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
2b5e0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2b5f0 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48  :.** [H16351] [H
2b600 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20  16352] [H16353] 
2b610 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35  [H16354] [H16355
2b620 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f  ] [H16358].*/.vo
2b630 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
2b640 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
2b650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b660 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
2b670 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
2b680 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31  n Of A Table {H1
2b690 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a  2850} <S60300>.*
2b6a0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2b6b0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2b6c0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2b6d0 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2b6e0 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2b6f0 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2b700 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2b710 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b720 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2b730 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2b740 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2b750 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
2b760 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
2b770 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
2b780 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
2b790 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2b7a0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
2b7b0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
2b7c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
2b7d0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
2b7e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2b7f0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
2b800 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
2b810 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
2b820 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
2b830 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
2b840 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
2b850 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
2b860 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
2b870 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
2b880 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
2b890 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
2b8a0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
2b8b0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2b8c0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
2b8d0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
2b8e0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
2b8f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
2b900 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2b910 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2b920 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2b930 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2b940 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2b950 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2b960 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2b970 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2b980 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2b990 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2b9a0 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72  ** Metadata is r
2b9b0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
2b9c0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
2b9d0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
2b9e0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
2b9f0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
2ba00 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2ba10 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
2ba20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
2ba30 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
2ba40 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2ba50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2ba60 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2ba70 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
2ba80 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d..**.** <blockq
2ba90 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2baa0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2bab0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
2bac0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
2bad0 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
2bae0 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
2baf0 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
2bb00 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2bb10 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
2bb20 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
2bb30 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2bb40 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
2bb50 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2bb60 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
2bb70 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
2bb80 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2bb90 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
2bba0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2bbb0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
2bbc0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2bbd0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2bbe0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
2bbf0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
2bc00 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
2bc10 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2bc20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2bc30 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
2bc40 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
2bc50 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2bc60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
2bc70 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
2bc80 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
2bc90 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
2bca0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
2bcb0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
2bcc0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
2bcd0 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
2bce0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
2bcf0 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
2bd00 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
2bd10 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2bd20 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2bd30 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2bd40 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2bd50 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2bd60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
2bd70 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2bd80 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
2bd90 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
2bda0 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
2bdb0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2bdc0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
2bdd0 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
2bde0 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
2bdf0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2be00 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2be10 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
2be20 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
2be30 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
2be40 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2be50 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2be60 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2be70 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2be80 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2be90 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2bea0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2beb0 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2bec0 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2bed0 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2bee0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2bef0 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2bf00 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2bf10 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2bf20 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2bf30 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2bf40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  e>.**.** This fu
2bf50 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
2bf60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
2bf70 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
2bf80 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
2bf90 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
2bfa0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
2bfb0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
2bfc0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
2bfd0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
2bfe0 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
2bff0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2c000 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
2c010 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
2c020 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
2c030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c040 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
2c050 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
2c060 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
2c070 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
2c080 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2c090 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2c0a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2c0b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2c0c0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2c0d0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2c0e0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
2c0f0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2c100 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
2c110 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
2c120 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c130 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
2c140 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
2c150 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
2c160 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
2c170 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
2c180 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
2c190 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
2c1a0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
2c1b0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
2c1c0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
2c1d0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
2c1e0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
2c1f0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
2c200 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
2c210 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
2c220 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
2c230 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
2c240 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
2c250 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
2c260 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
2c270 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
2c280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2c290 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
2c2a0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2c2b0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
2c2c0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
2c2d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2c2e0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2c2f0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
2c300 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
2c310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2c320 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2c330 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
2c340 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
2c350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c360 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
2c370 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32  ion {H12600} <S2
2c380 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2c390 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
2c3a0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
2c3b0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
2c3c0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
2c3d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d  ..**.** {H12601}
2c3e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2c3f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2c400 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2c410 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20   to load an.**  
2c420 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65          SQLite e
2c430 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2c440 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2c450 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
2c460 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65  .** {H12602} The
2c470 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2c480 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zProc..**.** {H1
2c490 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
2c4a0 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
2c4b0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
2c4c0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
2c4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
2c4e0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
2c4f0 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
2c500 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d  ..**.** {H12604}
2c510 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2c520 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2c530 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2c540 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2c550 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2c560 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2c570 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2c580 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2c590 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  ng..**.** {H1260
2c5a0 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  5} If an error o
2c5b0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
2c5c0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
2c5d0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2c5e0 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f    [sqlite3_load_
2c5f0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
2c600 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
2c610 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  empt to.**      
2c620 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d      fill *pzErrM
2c630 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
2c640 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
2c650 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  d in memory.**  
2c660 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64          obtained
2c670 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2c680 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20  alloc()]. {END} 
2c690 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
2c6a0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2c6b0 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68    should free th
2c6c0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2c6d0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2c6e0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ee()]..**.** {H1
2c6f0 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20  2606} Extension 
2c700 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
2c710 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
2c720 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c730 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2c740 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
2c750 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
2c760 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20  s API,.**       
2c770 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20     otherwise an 
2c780 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2c790 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
2c7a0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2c7b0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
2c7c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
2c7d0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
2c7e0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
2c7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c800 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2c810 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
2c820 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
2c830 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
2c840 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
2c850 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c860 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
2c870 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
2c880 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
2c890 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
2c8a0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
2c8b0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
2c8c0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
2c8d0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
2c8e0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2c8f0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
2c900 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48  nsion Loading {H
2c910 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12620} <S20500>.
2c920 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20  **.** So as not 
2c930 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
2c940 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
2c950 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2c960 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
2c970 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
2c980 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
2c990 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
2c9a0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
2c9b0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
2c9c0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
2c9d0 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
2c9e0 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
2c9f0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
2ca00 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
2ca10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
2ca20 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2ca30 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
2ca40 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65   off..**.** Exte
2ca50 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2ca60 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2ca70 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
2ca80 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31  3..**.** {H12621
2ca90 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
2caa0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2cab0 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
2cac0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
2cad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2cae0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2caf0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
2cb00 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
2cb10 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20  ==0 to turn.**  
2cb20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20          it back 
2cb30 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a  off again..**.**
2cb40 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73   {H12622} Extens
2cb50 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
2cb60 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ff by default..*
2cb70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2cb80 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
2cb90 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
2cba0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
2cbb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
2cbc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
2cbd0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b   An Extensions {
2cbe0 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e  H12640} <S20500>
2cbf0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2cc00 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
2cc10 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
2cc20 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
2cc30 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
2cc40 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
2cc50 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
2cc60 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
2cc70 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
2cc80 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73  all new [databas
2cc90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20  e connections]. 
2cca0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
2ccb0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
2ccc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ccd0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e   extension in an
2cce0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a   array that is.*
2ccf0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2cd00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2cd10 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20  )].  If you run 
2cd20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68  a memory leak ch
2cd30 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72  ecker.** on your
2cd40 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
2cd50 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
2cd60 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61  ecause of this a
2cd70 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  rray, invoke.** 
2cd80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
2cd90 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
2cda0 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f   prior to shutdo
2cdb0 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
2cdc0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
2cdd0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
2cde0 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
2cdf0 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
2ce00 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
2ce10 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2ce20 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
2ce30 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
2ce40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ce50 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
2ce60 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e    is opened usin
2ce70 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
2ce80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2ce90 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2cea0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2ceb0 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2cec0 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69  * {H12642} Dupli
2ced0 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
2cee0 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
2cef0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
2cf00 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tine.**         
2cf10 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
2cf20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
2cf30 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
2cf40 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ess..**.** {H126
2cf50 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
2cf60 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65   stores a pointe
2cf70 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69  r to the extensi
2cf80 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a  on in an array.*
2cf90 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
2cfa0 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2cfc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2cfd0 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
2cfe0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2cff0 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2d000 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2d010 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2d020 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2d030 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2d040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2d050 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2d060 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2d070 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30  {H12660} <S20500
2d080 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2d090 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2d0a0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2d0b0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2d0c0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2d0d0 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f  . {END}  It undo
2d0e0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
2d0f0 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73   all prior.** [s
2d100 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2d110 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a  nsion()] calls..
2d120 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54  **.** {H12661} T
2d130 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
2d140 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f  ables all previo
2d150 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a  usly registered.
2d160 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2d170 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2d180 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d  ..**.** {H12662}
2d190 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2d1a0 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
2d1b0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
2d1c0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2d1d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d1e0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2d1f0 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a  n(void);../*.***
2d200 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
2d210 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
2d220 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
2d230 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
2d240 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
2d250 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
2d260 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2d270 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
2d280 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
2d290 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
2d2a0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
2d2b0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
2d2c0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
2d2d0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
2d2e0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
2d2f0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
2d300 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
2d310 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
2d320 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
2d330 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2d340 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
2d350 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
2d360 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
2d370 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
2d380 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
2d390 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
2d3a0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
2d3b0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
2d3c0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
2d3d0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
2d3e0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
2d3f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2d400 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
2d410 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2d420 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2d430 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
2d440 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
2d450 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2d460 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
2d470 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
2d480 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2d490 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
2d4a0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
2d4b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2d4c0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
2d4d0 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32  ect {H18000} <S2
2d4e0 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
2d4f0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
2d500 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  e.** EXPERIMENTA
2d510 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65  L.**.** A module
2d520 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76   is a class of v
2d530 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20  irtual tables.  
2d540 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64  Each module is d
2d550 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20  efined.** by an 
2d560 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
2d570 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
2d580 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63  ure.  This struc
2d590 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a  ture consists.**
2d5a0 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
2d5b0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
2d5c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
2d5d0 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
2d5e0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
2d5f0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2d600 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
2d610 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2d620 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
2d630 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
2d640 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
2d650 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
2d660 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
2d670 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
2d680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2d690 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
2d6a0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
2d6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
2d6c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
2d6d0 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
2d6e0 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
2d6f0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
2d700 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
2d710 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
2d720 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
2d730 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
2d740 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
2d750 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
2d760 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
2d770 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
2d780 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
2d790 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2d7a0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
2d7b0 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
2d7c0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2d7d0 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
2d7e0 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
2d7f0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2d800 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
2d810 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
2d820 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2d830 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
2d840 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
2d850 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2d860 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
2d870 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
2d880 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
2d890 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
2d8a0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
2d8b0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2d8c0 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
2d8d0 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
2d8e0 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
2d8f0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2d900 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
2d910 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2d920 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
2d930 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
2d940 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2d950 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d960 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
2d970 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
2d980 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
2d990 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
2d9a0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
2d9b0 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
2d9c0 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
2d9d0 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
2d9e0 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
2d9f0 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
2da00 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2da10 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
2da20 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
2da30 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2da40 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
2da50 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2da60 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
2da70 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
2da80 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2da90 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
2daa0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2dab0 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
2dac0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2dad0 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
2dae0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
2daf0 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
2db00 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2db10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2db20 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2db30 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
2db40 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
2db50 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
2db60 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
2db70 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
2db80 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
2db90 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
2dba0 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
2dbb0 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20  mation {H18100} 
2dbc0 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
2dbd0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e  ORDS: sqlite3_in
2dbe0 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45  dex_info.** EXPE
2dbf0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2dc00 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
2dc10 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
2dc20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
2dc30 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
2dc40 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
2dc50 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
2dc60 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
2dc70 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
2dc80 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
2dc90 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
2dca0 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
2dcb0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
2dcc0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
2dcd0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
2dce0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
2dcf0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
2dd00 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
2dd10 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
2dd20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
2dd30 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
2dd40 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
2dd50 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
2dd60 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
2dd70 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
2dd80 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d  **.** <pre>colum
2dd90 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a  n OP expr</pre>.
2dda0 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69  **.** where OP i
2ddb0 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
2ddc0 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
2ddd0 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  .  The particula
2dde0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
2ddf0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
2de00 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68  traint[].op.  Th
2de10 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2de20 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
2de30 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
2de40 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43  t[].iColumn.  aC
2de50 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
2de60 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
2de70 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
2de80 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
2de90 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
2dea0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
2deb0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
2dec0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
2ded0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
2dee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d  .**.** The optim
2def0 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
2df00 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
2df10 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
2df20 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
2df30 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
2df40 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
2df50 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
2df60 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
2df70 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
2df80 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
2df90 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
2dfa0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
2dfb0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
2dfc0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
2dfd0 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
2dfe0 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
2dff0 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
2e000 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
2e010 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
2e020 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
2e030 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
2e040 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
2e050 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   Information abo
2e060 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
2e070 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
2e080 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
2e090 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20  ** Each term of 
2e0a0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
2e0b0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
2e0c0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2e0d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73  ..**.** The xBes
2e0e0 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75  tIndex method mu
2e0f0 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
2e100 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
2e110 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
2e120 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
2e130 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
2e140 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67  xFilter.  If arg
2e150 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
2e160 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
2e170 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
2e180 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
2e190 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
2e1a0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
2e1b0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
2e1c0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
2e1d0 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61  gv.  If aConstra
2e1e0 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
2e1f0 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
2e200 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
2e210 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
2e220 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
2e230 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
2e240 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
2e250 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
2e260 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
2e270 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20   The idxNum and 
2e280 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
2e290 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
2e2a0 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74  assed into xFilt
2e2b0 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  er..** sqlite3_f
2e2c0 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f  ree() is used to
2e2d0 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
2e2e0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
2e2f0 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
2e300 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
2e310 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
2e320 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74  utput from xFilt
2e330 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  er will occur in
2e340 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
2e350 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
2e360 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
2e370 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
2e380 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
2e390 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
2e3a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
2e3b0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61  estimatedCost va
2e3c0 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61  lue is an estima
2e3d0 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f  te of the cost o
2e3e0 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70  f doing the.** p
2e3f0 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70  articular lookup
2e400 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f  .  A full scan o
2e410 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e  f a table with N
2e420 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
2e430 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f  have.** a cost o
2e440 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73  f N.  A binary s
2e450 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65  earch of a table
2e460 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68   of N entries sh
2e470 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63  ould have a.** c
2e480 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61  ost of approxima
2e490 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a  tely log(N)..**.
2e4a0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2e4b0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
2e4c0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
2e4d0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
2e4e0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
2e4f0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2e500 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  QLite..*/.struct
2e510 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2e520 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
2e530 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
2e540 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
2e550 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
2e560 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
2e570 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
2e580 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e590 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
2e5a0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
2e5b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
2e5c0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
2e5d0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
2e5e0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
2e5f0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
2e600 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
2e610 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
2e620 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
2e630 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
2e640 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
2e650 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
2e660 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
2e670 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
2e680 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
2e690 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
2e6a0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
2e6b0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
2e6c0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
2e6d0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
2e6e0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
2e6f0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
2e700 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
2e710 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
2e720 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2e730 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
2e740 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
2e750 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
2e760 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
2e770 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
2e780 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
2e790 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
2e7a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
2e7b0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
2e7c0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
2e7d0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
2e7e0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
2e7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e800 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
2e810 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
2e820 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
2e830 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
2e840 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
2e850 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
2e860 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
2e870 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
2e880 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
2e890 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
2e8a0 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
2e8b0 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
2e8c0 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
2e8d0 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
2e8e0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
2e8f0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
2e900 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
2e910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e920 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
2e930 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
2e940 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
2e950 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
2e960 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
2e970 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
2e980 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
2e990 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
2e9a0 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
2e9b0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
2e9c0 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
2e9d0 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
2e9e0 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
2e9f0 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
2ea00 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
2ea10 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
2ea20 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
2ea30 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
2ea40 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
2ea50 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
2ea60 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
2ea70 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
2ea80 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2ea90 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
2eaa0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2eab0 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
2eac0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2ead0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2eae0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
2eaf0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2eb00 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
2eb10 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
2eb20 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2eb30 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
2eb40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2eb50 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
2eb60 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
2eb70 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
2eb80 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
2eb90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48  mplementation {H
2eba0 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18200} <S20400>.
2ebb0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2ebc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2ebd0 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
2ebe0 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
2ebf0 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 0a  ule name with a.
2ec00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2ec10 6e 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75 6c  nection].  Modul
2ec20 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
2ec30 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
2ec40 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 6e 65  e.** creating ne
2ec50 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  w virtual tables
2ec60 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20   on the module, 
2ec70 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 0a  or before using.
2ec80 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 76  ** preexisting v
2ec90 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 66  irtual tables of
2eca0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
2ecb0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2ecc0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
2ecd0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
2ece0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
2ecf0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
2ed00 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2ed10 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
2ed20 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
2ed30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2ed40 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
2ed50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2ed60 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
2ed70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
2ed80 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
2ed90 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
2eda0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
2edb0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2edc0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
2edd0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
2ede0 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68  le *,    /* Meth
2edf0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
2ee00 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20  le */.  void *  
2ee10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ee20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
2ee30 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
2ee40 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
2ee50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2ee60 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
2ee70 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
2ee80 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c  ation {H18210} <
2ee90 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20400>.** EXPER
2eea0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
2eeb0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64  is routine is id
2eec0 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b  entical to the [
2eed0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2eee0 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 20  odule()] method 
2eef0 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74  above,.** except
2ef00 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20   that it allows 
2ef10 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
2ef20 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63  ction to be spec
2ef30 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20  ified. It is.** 
2ef40 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69  even more experi
2ef50 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20  mental than the 
2ef60 72 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74  rest of the virt
2ef70 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a  ual tables API..
2ef80 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
2ef90 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
2efa0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
2efb0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2efc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2efd0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
2efe0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
2eff0 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
2f000 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2f010 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
2f020 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
2f030 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
2f040 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
2f050 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ,    /* Methods 
2f060 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
2f070 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
2f080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2f090 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
2f0a0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
2f0b0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
2f0c0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
2f0d0 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
2f0e0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2f0f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2f100 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2f110 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
2f120 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c  bject {H18010} <
2f130 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
2f140 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
2f150 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  b.** EXPERIMENTA
2f160 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  L.**.** Every mo
2f170 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
2f180 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
2f190 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
2f1a0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
2f1b0 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  * to describe a 
2f1c0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
2f1d0 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  nce of the modul
2f1e0 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  e.  Each subclas
2f1f0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
2f200 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
2f210 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
2f220 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
2f230 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  entation..** The
2f240 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
2f250 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
2f260 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
2f270 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
2f280 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  .** common to al
2f290 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
2f2a0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
2f2b0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
2f2c0 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
2f2d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
2f2e0 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
2f2f0 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
2f300 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2f310 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45  mprintf()] to zE
2f320 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
2f330 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
2f340 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
2f350 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
2f360 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
2f370 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2f380 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
2f390 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
2f3a0 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
2f3b0 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72  g.  After the er
2f3c0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
2f3d0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
2f3e0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
2f3f0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
2f400 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
2f410 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
2f420 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
2f430 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
2f440 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
2f450 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74   be zeroed.  Not
2f460 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65  e.** that sqlite
2f470 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
2f480 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
2f490 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a  re used on the z
2f4a0 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20  ErrMsg field.** 
2f4b0 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61  since virtual ta
2f4c0 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c  bles are commonl
2f4d0 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  y implemented in
2f4e0 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73   loadable extens
2f4f0 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f  ions which.** do
2f500 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
2f510 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e   to sqlite3MPrin
2f520 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46  tf() or sqlite3F
2f530 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ree()..**.** Thi
2f540 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
2f550 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2f560 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2f570 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
2f580 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
2f590 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2f5a0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2f5b0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
2f5c0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2f5d0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
2f5e0 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
2f5f0 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
2f600 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
2f610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f620 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
2f630 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68  ternally */.  ch
2f640 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
2f650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f660 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
2f670 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
2f680 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
2f690 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
2f6a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
2f6b0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
2f6c0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
2f6d0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
2f6e0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2f6f0 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a  Table Cursor Obj
2f700 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53  ect  {H18020} <S
2f710 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20400>.** KEYWOR
2f720 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
2f730 5f 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50 45 52  _cursor.** EXPER
2f740 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76  IMENTAL.**.** Ev
2f750 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
2f760 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
2f770 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
2f780 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
2f790 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
2f7a0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
2f7b0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
2f7c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
2f7d0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
2f7e0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
2f7f0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
2f800 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
2f810 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
2f820 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
2f830 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
2f840 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
2f850 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
2f860 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
2f870 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
2f880 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
2f890 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
2f8a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
2f8b0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
2f8c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
2f8d0 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
2f8e0 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
2f8f0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
2f900 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
2f910 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
2f920 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
2f930 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
2f940 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2f950 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
2f960 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2f970 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
2f980 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2f990 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
2f9a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
2f9b0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
2f9c0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
2f9d0 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
2f9e0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
2f9f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
2fa00 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
2fa10 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
2fa20 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
2fa30 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2fa40 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
2fa50 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
2fa60 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30   {H18280} <S2040
2fa70 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
2fa80 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72  AL.**.** The xCr
2fa90 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63  eate and xConnec
2faa0 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d  t methods of a m
2fab0 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f  odule use the fo
2fac0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74  llowing API.** t
2fad0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
2fae0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
2faf0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
2fb00 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
2fb10 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
2fb20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
2fb30 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ement..**.** Thi
2fb40 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
2fb50 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2fb60 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2fb70 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
2fb80 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
2fb90 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2fba0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
2fbb0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
2fbc0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
2fbd0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
2fbe0 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
2fbf0 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ble);../*.** CAP
2fc00 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
2fc10 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
2fc20 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b   Virtual Table {
2fc30 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18300} <S20400>
2fc40 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2fc50 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
2fc60 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
2fc70 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
2fc80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2fc90 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
2fca0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
2fcb0 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
2fcc0 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
2fcd0 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
2fce0 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
2fcf0 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
2fd00 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
2fd10 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
2fd20 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
2fd30 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
2fd40 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
2fd50 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
2fd60 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
2fd70 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
2fd80 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
2fd90 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
2fda0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
2fdb0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
2fdc0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
2fdd0 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
2fde0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
2fdf0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
2fe00 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
2fe10 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
2fe20 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
2fe30 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
2fe40 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
2fe50 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
2fe60 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
2fe70 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
2fe80 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
2fe90 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
2fea0 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
2feb0 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61  ded.** by virtua
2fec0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  l tables..**.** 
2fed0 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20  This API should 
2fee0 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61  be considered pa
2fef0 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  rt of the virtua
2ff00 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
2ff10 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65  e,.** which is e
2ff20 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2ff30 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
2ff40 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  e..*/.SQLITE_EXP
2ff50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
2ff60 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
2ff70 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
2ff80 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
2ff90 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
2ffa0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
2ffb0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
2ffc0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2ffd0 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
2ffe0 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
2fff0 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
30000 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
30010 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
30020 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
30030 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
30040 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
30050 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
30060 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
30070 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
30080 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
30090 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
300a0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
300b0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
300c0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
300d0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
300e0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
300f0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
30100 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
30110 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
30120 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
30130 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
30140 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
30150 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45  ent..**.****** E
30160 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
30170 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
30180 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
30190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f  *************.*/
301a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
301b0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
301c0 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38   Open BLOB {H178
301d0 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20  00} <S30230>.** 
301e0 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
301f0 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
30200 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
30210 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
30220 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
30230 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
30240 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
30250 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
30260 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
30270 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
30280 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65  rformed..** Obje
30290 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
302a0 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20   are created by 
302b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
302c0 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73  en()].** and des
302d0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
302e0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
302f0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
30300 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
30310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
30320 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
30330 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
30340 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
30350 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
30360 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
30370 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  OB..** The [sqli
30380 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
30390 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
303a0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
303b0 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65  the BLOB in byte
303c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
303d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
303e0 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
303f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30400 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
30410 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
30420 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33   {H17810} <S3023
30430 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
30440 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61  terfaces opens a
30450 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20   [BLOB handle | 
30460 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42  handle] to the B
30470 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69  LOB located.** i
30480 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75  n row iRow, colu
30490 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c  mn zColumn, tabl
304a0 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61  e zTable in data
304b0 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20  base zDb;.** in 
304c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
304d0 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20   same BLOB that 
304e0 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65  would be selecte
304f0 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
30500 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
30510 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
30520 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72  .zTable WHERE [r
30530 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a  owid] = iRow;.**
30540 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a   </pre> {END}.**
30550 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73  .** If the flags
30560 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
30570 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 65 20  n-zero, the the 
30580 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
30590 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77  or read.** and w
305a0 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20  rite access. If 
305b0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
305c0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
305d0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
305e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
305f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
30600 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
30610 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
30620 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
30630 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
30640 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
30650 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
30660 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69   that.** is assi
30670 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64 61  gned when the da
30680 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63  tabase is connec
30690 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43  ted using [ATTAC
306a0 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d  H]..** For the m
306b0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
306c0 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  e, the database 
306d0 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a  name is "main"..
306e0 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  ** For TEMP tabl
306f0 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
30700 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
30710 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
30720 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
30730 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74  s returned and t
30740 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e  he new [BLOB han
30750 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a  dle] is written.
30760 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f  ** to *ppBlob. O
30770 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
30780 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
30790 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 61 6c  rned and any val
307a0 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  ue written.** to
307b0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20   *ppBlob should 
307c0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74  not be used by t
307d0 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68  he caller..** Th
307e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
307f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30800 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
30810 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
30820 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
30830 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
30840 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
30850 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
30860 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77  **.** If the row
30870 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
30880 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
30890 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
308a0 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
308b0 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
308c0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
308d0 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
308e0 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
308f0 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
30900 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
30910 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
30920 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
30930 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
30940 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
30950 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
30960 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
30970 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20   is open on..** 
30980 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
30990 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
309a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
309b0 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
309c0 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
309d0 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
309e0 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
309f0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
30a00 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72  ]..** Changes wr
30a10 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f  itten into a BLO
30a20 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42  B prior to the B
30a30 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65  LOB expiring are
30a40 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b   not.** rollback
30a50 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69   by the expirati
30a60 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20  on of the BLOB. 
30a70 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69   Such changes wi
30a80 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ll eventually.**
30a90 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74   commit if the t
30aa0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69  ransaction conti
30ab0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
30ac0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  on..**.** Requir
30ad0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38  ements:.** [H178
30ae0 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 48 31  13] [H17814] [H1
30af0 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b  7816] [H17819] [
30b00 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 34 5d  H17821] [H17824]
30b10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30b20 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
30b30 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
30b40 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
30b50 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
30b60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
30b70 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
30b80 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
30b90 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
30ba0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
30bb0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
30bc0 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c  3REF: Close A BL
30bd0 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33  OB Handle {H1783
30be0 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
30bf0 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e  * Closes an open
30c00 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a   [BLOB handle]..
30c10 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20  **.** Closing a 
30c20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65  BLOB shall cause
30c30 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61   the current tra
30c40 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d  nsaction to comm
30c50 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61  it.** if there a
30c60 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42  re no other BLOB
30c70 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72  s, no pending pr
30c80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30c90 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61  s, and the.** da
30ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30cb0 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d  n is in [autocom
30cc0 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66  mit mode]..** If
30cd0 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65   any writes were
30ce0 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f   made to the BLO
30cf0 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65  B, they might be
30d00 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a   held in cache.*
30d10 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73  * until the clos
30d20 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74  e operation if t
30d30 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45  hey will fit. {E
30d40 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e  ND}.**.** Closin
30d50 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
30d60 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
30d70 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
30d80 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
30d90 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
30da0 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
30db0 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
30dc0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
30dd0 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
30de0 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e 79 20  .  {H17833} Any 
30df0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
30e00 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
30e10 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
30e20 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
30e30 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a  eturn value..**.
30e40 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63  ** The BLOB is c
30e50 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f  losed unconditio
30e60 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20  nally.  Even if 
30e70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
30e80 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  urns.** an error
30e90 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20   code, the BLOB 
30ea0 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e  is still closed.
30eb0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
30ec0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d  nts:.** [H17833]
30ed0 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33   [H17836] [H1783
30ee0 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
30ef0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c  3_blob_close(sql
30f00 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
30f10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
30f20 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
30f30 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b  f An Open BLOB {
30f40 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e  H17840} <S30230>
30f50 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
30f60 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
30f70 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
30f80 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
30f90 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68  open.** []BLOB h
30fa0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
30fb0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ly argument..**.
30fc0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
30fd0 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a  .** [H17843].*/.
30fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
30ff0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
31000 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
31010 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
31020 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
31030 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31  ncrementally {H1
31040 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7850} <S30230>.*
31050 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
31060 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
31070 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
31080 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
31090 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
310a0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
310b0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
310c0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
310d0 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
310e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
310f0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
31100 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
31110 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74  .**.** If offset
31120 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
31130 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
31140 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
31150 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
31160 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
31170 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
31180 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e  a is read.  If N
31190 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a   or iOffset is.*
311a0 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
311b0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
311c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
311d0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
311e0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d  ..**.** An attem
311f0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
31200 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
31210 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
31220 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
31230 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
31240 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ABORT]..**.** On
31250 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
31260 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
31270 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
31280 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
31290 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
312a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
312b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
312c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
312d0 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d  H17853] [H17856]
312e0 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36   [H17859] [H1786
312f0 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37  2] [H17863] [H17
31300 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f  865] [H17868].*/
31310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
31320 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
31330 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
31340 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
31350 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
31360 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61  3REF: Write Data
31370 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63   Into A BLOB Inc
31380 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38  rementally {H178
31390 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  70} <S30230>.**.
313a0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
313b0 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74   is used to writ
313c0 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f  e data into an o
313d0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
313e0 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c  ] from a.** call
313f0 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
31400 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
31410 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
31420 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a  rom the buffer Z
31430 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  .** into the ope
31440 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
31450 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
31460 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  et..**.** If the
31470 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
31480 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
31490 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
314a0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
314b0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
314c0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
314d0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
314e0 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
314f0 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
31500 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
31510 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
31520 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
31530 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
31540 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
31550 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20  of the BLOB; it 
31560 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
31570 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
31580 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f  he size of a BLO
31590 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  B using this API
315a0 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69  ..** If offset i
315b0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
315c0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
315d0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
315e0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
315f0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
31600 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
31610 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20  is written.  If 
31620 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
31630 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
31640 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
31650 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
31660 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20   written..**.** 
31670 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
31680 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
31690 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
316a0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
316b0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
316c0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
316d0 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c  Writes to the BL
316e0 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64  OB that occurred
316f0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
31700 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70  BLOB handle] exp
31710 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c  ired are not rol
31720 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a  led back by the.
31730 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  ** expiration of
31740 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f   the handle, tho
31750 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
31760 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68  ose changes migh
31770 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f  t.** have been o
31780 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
31790 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
317a0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f   expired the BLO
317b0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62  B handle.** or b
317c0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64  y other independ
317d0 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  ent statements..
317e0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
317f0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
31800 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
31810 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
31820 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
31830 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
31840 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
31850 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
31860 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d  nts:.** [H17873]
31870 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37   [H17874] [H1787
31880 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37  5] [H17876] [H17
31890 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48  877] [H17879] [H
318a0 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a  17882] [H17885].
318b0 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69  ** [H17888].*/.i
318c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
318d0 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c  write(sqlite3_bl
318e0 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ob *, const void
318f0 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
31900 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
31910 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
31920 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f  al File System O
31930 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20  bjects {H11200} 
31940 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
31950 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
31960 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
31970 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
31980 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
31990 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
319a0 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
319b0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
319c0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
319d0 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
319e0 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
319f0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
31a00 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
31a10 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
31a20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
31a30 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
31a40 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
31a50 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
31a60 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
31a70 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
31a80 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
31a90 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
31aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31ab0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
31ac0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31ad0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
31ae0 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
31af0 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63  ..** Names are c
31b00 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a  ase sensitive..*
31b10 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f  * Names are zero
31b20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
31b30 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  8 strings..** If
31b40 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
31b50 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ch, a NULL point
31b60 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
31b70 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69  ** If zVfsName i
31b80 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
31b90 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72  default VFS is r
31ba0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e  eturned..**.** N
31bb0 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
31bc0 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
31bd0 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
31be0 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77  r()..** Each new
31bf0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
31c00 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
31c10 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
31c20 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65  g is set..** The
31c30 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
31c40 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
31c50 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
31c60 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f  ut injury..** To
31c70 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
31c80 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
31c90 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
31ca0 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
31cb0 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
31cc0 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
31cd0 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
31ce0 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
31cf0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
31d00 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
31d10 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
31d20 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
31d30 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
31d40 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
31d50 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
31d60 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
31d70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
31d80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
31d90 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65  .**.** Unregiste
31da0 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
31db0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
31dc0 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66  egister() interf
31dd0 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ace..** If the d
31de0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
31df0 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
31e00 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
31e10 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
31e20 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
31e30 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
31e40 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
31e50 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
31e60 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b  s:.** [H11203] [
31e70 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d  H11206] [H11209]
31e80 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31   [H11212] [H1121
31e90 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73  5] [H11218].*/.s
31ea0 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
31eb0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
31ec0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
31ed0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
31ee0 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
31ef0 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
31f00 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
31f10 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
31f20 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
31f30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31f40 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31  REF: Mutexes {H1
31f50 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7000} <S20000>.*
31f60 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
31f70 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
31f80 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
31f90 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
31fa0 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74  zation. Though t
31fb0 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
31fc0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
31fd0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
31fe0 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
31ff0 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
32000 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
32010 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
32020 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
32030 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
32040 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
32050 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
32060 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
32070 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
32080 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
32090 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
320a0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
320b0 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
320c0 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
320d0 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  ime.  The follow
320e0 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
320f0 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
32100 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
32110 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
32120 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
32130 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
32140 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
32150 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
32160 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
32170 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
32180 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
32190 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NOOP.** </ul>.**
321a0 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  .** The SQLITE_M
321b0 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
321c0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
321d0 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  t of routines.**
321e0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
321f0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
32200 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
32210 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69  r use in.** a si
32220 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
32230 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
32240 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
32250 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
32260 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
32270 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
32280 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
32290 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
322a0 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53  te for use on OS
322b0 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69  /2, Unix, and Wi
322c0 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ndows..**.** If 
322d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
322e0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
322f0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
32300 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
32310 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
32320 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
32330 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
32340 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
32350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32360 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
32370 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
32380 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
32390 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
323a0 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
323b0 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
323c0 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
323d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
323e0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
323f0 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
32400 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
32410 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
32420 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
32430 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
32440 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
32450 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
32460 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
32470 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
32480 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ()..**.** {H1701
32490 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
324a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
324b0 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
324c0 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
324d0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
324e0 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30  ter to it. {H170
324f0 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e  12} If it return
32500 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
32510 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
32520 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
32530 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31  llocated. {H1701
32540 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  3} SQLite.** wil
32550 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61  l unwind its sta
32560 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ck and return an
32570 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d   error. {H17014}
32580 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   The argument.**
32590 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
325a0 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
325b0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
325c0 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
325d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
325e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
325f0 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
32600 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
32610 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
32620 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
32630 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
32640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
32650 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
32660 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
32670 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
32680 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
32690 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
326a0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
326b0 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
326c0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
326d0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
326e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48  * </ul>.**.** {H
326f0 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74  17015} The first
32700 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63   two constants c
32710 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
32720 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
32730 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
32740 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75  tex.  The new mu
32750 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
32760 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
32770 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
32780 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
32790 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
327a0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
327b0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b  _FAST is used. {
327c0 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65  END}.** The mute
327d0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
327e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
327f0 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
32800 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
32810 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
32820 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
32830 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
32840 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
32850 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36  ant to.  {H17016
32860 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c  } But SQLite wil
32870 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
32880 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
32890 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
328a0 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
328b0 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49  ds one.  {END} I
328c0 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72  f a faster non-r
328d0 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a  ecursive mutex.*
328e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
328f0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e   is available on
32900 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f   the host platfo
32910 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75  rm, the mutex su
32920 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74  bsystem.** might
32930 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d   return such a m
32940 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65  utex in response
32950 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   to SQLITE_MUTEX
32960 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  _FAST..**.** {H1
32970 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20  7017} The other 
32980 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65  allowed paramete
32990 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  rs to sqlite3_mu
329a0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68  tex_alloc() each
329b0 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
329c0 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
329d0 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
329e0 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20  ex. {END}  Four 
329f0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  static mutexes a
32a00 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68  re.** used by th
32a10 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
32a20 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75  n of SQLite.  Fu
32a30 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
32a40 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61   SQLite.** may a
32a50 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  dd additional st
32a60 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53  atic mutexes.  S
32a70 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
32a80 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  e for internal.*
32a90 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20  * use by SQLite 
32aa0 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
32ab0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c  ons that use SQL
32ac0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ite mutexes shou
32ad0 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74  ld.** use only t
32ae0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
32af0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  es returned by S
32b00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
32b10 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55   or.** SQLITE_MU
32b20 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a  TEX_RECURSIVE..*
32b30 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f  *.** {H17018} No
32b40 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f  te that if one o
32b50 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  f the dynamic mu
32b60 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28  tex parameters (
32b70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
32b80 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d  T.** or SQLITE_M
32b90 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
32ba0 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c  is used then sql
32bb0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
32bc0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
32bd0 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20  different mutex 
32be0 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20  on every call.  
32bf0 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72  {H17034} But for
32c00 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d   the static.** m
32c10 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20  utex types, the 
32c20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65  same mutex is re
32c30 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20  turned on every 
32c40 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a  call that has.**
32c50 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e   the same type n
32c60 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  umber..**.** {H1
32c70 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65  7019} The sqlite
32c80 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72  3_mutex_free() r
32c90 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74  outine deallocat
32ca0 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a  es a previously.
32cb0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e  ** allocated dyn
32cc0 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37  amic mutex. {H17
32cd0 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63  020} SQLite is c
32ce0 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
32cf0 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
32d00 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
32d10 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b   it allocates. {
32d20 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61  A17021} The dyna
32d30 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74  mic mutexes must
32d40 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73   not be in.** us
32d50 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  e when they are 
32d60 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31  deallocated. {A1
32d70 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67  7022} Attempting
32d80 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
32d90 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
32da0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
32db0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
32dc0 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20  {H17023} SQLite 
32dd0 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65  never deallocate
32de0 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75  s.** a static mu
32df0 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  tex. {END}.**.**
32e00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
32e10 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
32e20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
32e30 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
32e40 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
32e50 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34  a mutex. {H17024
32e60 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
32e70 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
32e80 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
32e90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
32ea0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
32eb0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
32ec0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
32ed0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
32ee0 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35  TE_BUSY. {H17025
32ef0 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  }  The sqlite3_m
32f00 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
32f10 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51  face returns [SQ
32f20 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e  LITE_OK].** upon
32f30 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72   successful entr
32f40 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74  y.  {H17026} Mut
32f50 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
32f60 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
32f70 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
32f80 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
32f90 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
32fa0 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
32fb0 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75  * {H17027} In su
32fc0 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
32fd0 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
32fe0 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
32ff0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
33000 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
33010 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
33020 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20  r.  {A17028} If 
33030 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
33040 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
33050 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  ny other.** kind
33060 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74   of mutex more t
33070 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
33080 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
33090 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d  ned..** {H17029}
330a0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
330b0 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75  er exhibit.** su
330c0 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69  ch behavior in i
330d0 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75  ts own use of mu
330e0 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  texes..**.** Som
330f0 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
33100 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
33110 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
33120 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
33130 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
33140 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
33150 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
33160 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
33170 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
33180 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
33190 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
331a0 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20  .  {H17030} The 
331b0 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79  SQLite core only
331c0 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71   ever uses.** sq
331d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
331e0 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61  ) as an optimiza
331f0 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20  tion so this is 
33200 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76  acceptable behav
33210 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  ior..**.** {H170
33220 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  31} The sqlite3_
33230 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
33240 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
33250 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
33260 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
33270 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
33280 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d  hread.  {A17032}
33290 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   The behavior.**
332a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
332b0 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
332c0 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
332d0 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
332e0 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
332f0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
33300 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31   allocated.  {H1
33310 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c  7033} SQLite wil
33320 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
33330 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ther. {END}.**.*
33340 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e  * If the argumen
33350 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  t to sqlite3_mut
33360 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69  ex_enter(), sqli
33370 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c  te3_mutex_try(),
33380 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   or.** sqlite3_m
33390 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20  utex_leave() is 
333a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
333b0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72  then all three r
333c0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76  outines.** behav
333d0 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  e as no-ops..**.
333e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
333f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
33400 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33410 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
33420 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  ]..*/.sqlite3_mu
33430 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74  tex *sqlite3_mut
33440 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  ex_alloc(int);.v
33450 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
33460 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d  x_free(sqlite3_m
33470 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
33480 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
33490 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
334a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
334b0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f  tex_try(sqlite3_
334c0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
334d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
334e0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
334f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33500 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64  EF: Mutex Method
33510 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30  s Object {H17120
33520 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58  } <S20130>.** EX
33530 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
33540 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
33550 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64  this structure d
33560 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c  efines the low-l
33570 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  evel routines.**
33580 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74   used to allocat
33590 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65  e and use mutexe
335a0 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79  s..**.** Usually
335b0 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  , the default mu
335c0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
335d0 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20  ons provided by 
335e0 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75  SQLite are.** su
335f0 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65  fficient, howeve
33600 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74  r the user has t
33610 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62  he option of sub
33620 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74  stituting a cust
33630 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  om.** implementa
33640 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c  tion for special
33650 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73  ized deployments
33660 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20   or systems for 
33670 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20  which SQLite.** 
33680 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
33690 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
336a0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74  ementation. In t
336b0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73  his case, the us
336c0 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e  er.** creates an
336d0 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69  d populates an i
336e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
336f0 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73  structure to pas
33700 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
33710 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77  config() along w
33720 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
33730 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
33740 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  tion..** Additio
33750 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e  nally, an instan
33760 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
33770 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
33780 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74   as an.** output
33790 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71   variable when q
337a0 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74  uerying the syst
337b0 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  em for the curre
337c0 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  nt mutex.** impl
337d0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e  ementation, usin
337e0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
337f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f  NFIG_GETMUTEX] o
33800 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ption..**.** The
33810 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
33820 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
33830 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
33840 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
33850 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69  rt of system ini
33860 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74  tialization by t
33870 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
33880 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
33890 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68  ..** {H17001} Th
338a0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75  e xMutexInit rou
338b0 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61  tine shall be ca
338c0 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  lled by SQLite o
338d0 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  nce for each.** 
338e0 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
338f0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  o [sqlite3_initi
33900 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
33910 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65  The xMutexEnd me
33920 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20  thod defined by 
33930 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69  this structure i
33940 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20  s invoked as.** 
33950 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73  part of system s
33960 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73  hutdown by the s
33970 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
33980 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a  ) function. The.
33990 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
339a0 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64  n of this method
339b0 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20   is expected to 
339c0 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73  release all outs
339d0 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75  tanding.** resou
339e0 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79  rces obtained by
339f0 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f   the mutex metho
33a00 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ds implementatio
33a10 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a  n, especially.**
33a20 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20   those obtained 
33a30 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69  by the xMutexIni
33a40 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30  t method. {H1700
33a50 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64  3} The xMutexEnd
33a60 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
33a70 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
33a80 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
33a90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33aa0 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
33ab0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
33ac0 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64   seven methods d
33ad0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
33ae0 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78  tructure (xMutex
33af0 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78  Alloc,.** xMutex
33b00 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65  Free, xMutexEnte
33b10 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d  r, xMutexTry, xM
33b20 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65  utexLeave, xMute
33b30 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75  xHeld and.** xMu
33b40 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c  texNotheld) impl
33b50 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77  ement the follow
33b60 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28  ing interfaces (
33b70 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a  respectively):.*
33b80 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
33b90 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
33ba0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c  tex_alloc()] </l
33bb0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
33bc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
33bd0 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
33be0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
33bf0 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f  utex_enter()] </
33c00 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
33c10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
33c20 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  y()] </li>.**   
33c30 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
33c40 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f  utex_leave()] </
33c50 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
33c60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
33c70 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ld()] </li>.**  
33c80 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
33c90 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
33ca0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   </li>.** </ul>.
33cb0 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64  **.** The only d
33cc0 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61  ifference is tha
33cd0 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c  t the public sql
33ce0 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f  ite3_XXX functio
33cf0 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a  ns enumerated.**
33d00 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20   above silently 
33d10 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63  ignore any invoc
33d20 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73  ations that pass
33d30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
33d40 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
33d50 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64  valid mutex hand
33d60 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  le. The implemen
33d70 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d  tations of the m
33d80 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a  ethods defined.*
33d90 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  * by this struct
33da0 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75  ure are not requ
33db0 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74  ired to handle t
33dc0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65  his case, the re
33dd0 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73  sults.** of pass
33de0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
33df0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
33e00 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64  valid mutex hand
33e10 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  le are undefined
33e20 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20  .** (i.e. it is 
33e30 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72  acceptable to pr
33e40 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65  ovide an impleme
33e50 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67  ntation that seg
33e60 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20  faults if.** it 
33e70 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c  is passed a NULL
33e80 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79   pointer)..*/.ty
33e90 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
33ea0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
33eb0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
33ec0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
33ed0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
33ee0 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
33ef0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
33f00 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
33f10 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
33f20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
33f30 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
33f40 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
33f50 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
33f60 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
33f70 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
33f80 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
33f90 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
33fa0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
33fb0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
33fc0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
33fd0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
33fe0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
33ff0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
34000 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
34010 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
34020 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
34030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34040 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
34050 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
34060 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e  H17080} <S20130>
34070 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
34080 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
34090 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
340a0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
340b0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
340c0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
340d0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
340e0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
340f0 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53  . {H17081} The S
34100 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65  QLite core.** ne
34110 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72  ver uses these r
34120 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69  outines except i
34130 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28  nside an assert(
34140 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  ) and applicatio
34150 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65  ns.** are advise
34160 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20  d to follow the 
34170 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65  lead of the core
34180 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20  .  {H17082} The 
34190 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
341a0 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
341b0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
341c0 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
341d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
341e0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
341f0 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31  DEBUG flag.  {A1
34200 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d  7087} External m
34210 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
34220 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79  ions.** are only
34230 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
34240 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69  vide these routi
34250 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45  nes if SQLITE_DE
34260 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65  BUG is.** define
34270 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20  d and if NDEBUG 
34280 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a  is not defined..
34290 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54  **.** {H17083} T
342a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
342b0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65  ould return true
342c0 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e   if the mutex in
342d0 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a   their argument.
342e0 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f  ** is held or no
342f0 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69  t held, respecti
34300 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c  vely, by the cal
34310 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a  ling thread..**.
34320 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20  ** {X17084} The 
34330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
34340 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
34350 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69  o provided versi
34360 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
34370 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63  routines that ac
34380 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20  tually work. If 
34390 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
343a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  on does not prov
343b0 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76  ide working.** v
343c0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
343d0 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68   routines, it sh
343e0 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72  ould at least pr
343f0 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74  ovide stubs that
34400 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72   always.** retur
34410 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f  n true so that o
34420 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20  ne does not get 
34430 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69  spurious asserti
34440 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
34450 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74  ** {H17085} If t
34460 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
34470 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
34480 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
34490 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
344a0 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
344b0 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44   return 1.  {END
344c0 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75  } This seems cou
344d0 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73  nter-intuitive s
344e0 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20  ince.** clearly 
344f0 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74  the mutex cannot
34500 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64   be held if it d
34510 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20  oes not exist.  
34520 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72  But the.** the r
34530 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20  eason the mutex 
34540 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
34550 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75  s because the bu
34560 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73  ild is not.** us
34570 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e  ing mutexes.  An
34580 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74  d we do not want
34590 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f   the assert() co
345a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
345b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
345c0 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20  mutex_held() to 
345d0 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a  fail, so a non-z
345e0 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a  ero return is.**
345f0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
34600 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b   thing to do.  {
34610 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69  H17086} The sqli
34620 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
34630 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
34640 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
34650 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
34660 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
34670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34680 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
34690 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
346a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
346b0 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
346c0 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
346d0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79  PI3REF: Mutex Ty
346e0 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31  pes {H17001} <H1
346f0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7000>.**.** The 
34700 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
34710 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
34720 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
34730 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
34740 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
34750 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
34760 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
34770 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75  set of static mu
34780 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65  texes may change
34790 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65   from one SQLite
347a0 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a   release to the.
347b0 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
347c0 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
347d0 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ride the built-i
347e0 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75  n mutex logic mu
347f0 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65  st be.** prepare
34800 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65  d to accommodate
34810 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
34820 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23  ic mutexes..*/.#
34830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
34840 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
34850 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
34860 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
34870 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
34880 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
34890 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
348a0 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
348b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
348c0 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
348d0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
348e0 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
348f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
34900 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
34910 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23  /* NOT USED */.#
34920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
34930 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20  TEX_STATIC_OPEN 
34940 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
34950 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f  e3BtreeOpen() */
34960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34970 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
34980 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
34990 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
349a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
349b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
349c0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
349d0 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64   page list */.#d
349e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
349f0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20  EX_STATIC_LRU2  
34a00 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61      7  /* lru pa
34a10 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
34a20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
34a30 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66  ieve the mutex f
34a40 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
34a50 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32  nnection {H17002
34a60 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <H17000>.**.**
34a70 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
34a80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34a90 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  r the [sqlite3_m
34aa0 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61  utex] object tha
34ab0 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73  t .** serializes
34ac0 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b   access to the [
34ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34ae0 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68  ion] given in th
34af0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68  e argument.** wh
34b00 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  en the [threadin
34b10 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61  g mode] is Seria
34b20 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  lized..** If the
34b30 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
34b40 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] is Single-thre
34b50 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65  ad or Multi-thre
34b60 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20  ad then this.** 
34b70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34b80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
34b90 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
34ba0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74   *sqlite3_db_mut
34bb0 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  ex(sqlite3*);../
34bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
34bd0 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c  ow-Level Control
34be0 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c   Of Database Fil
34bf0 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30  es {H11300} <S30
34c00 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  800>.**.** {H113
34c10 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
34c20 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
34c30 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
34c40 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74   a direct call t
34c50 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f  o the.** xFileCo
34c60 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72  ntrol method for
34c70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
34c80 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
34c90 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
34ca0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
34cb0 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69   database identi
34cc0 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
34cd0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31  nd argument. {H1
34ce0 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d  1302} The.** nam
34cf0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
34d00 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73  e is the name as
34d10 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61  signed to the da
34d20 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a  tabase by the.**
34d30 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61   <a href="lang_a
34d40 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41  ttach.html">ATTA
34d50 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61  CH</a> SQL comma
34d60 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74  nd that opened t
34d70 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
34d80 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74  {H11303} To cont
34d90 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74  rol the main dat
34da0 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20  abase file, use 
34db0 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a  the name "main".
34dc0 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ** or a NULL poi
34dd0 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54  nter. {H11304} T
34de0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
34df0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
34e00 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  o this routine.*
34e10 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72  * are passed dir
34e20 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f  ectly through to
34e30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
34e40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73  third parameters
34e50 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65   of.** the xFile
34e60 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
34e70 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65   {H11305} The re
34e80 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
34e90 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a  e xFileControl.*
34ea0 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73  * method becomes
34eb0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34ec0 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
34ed0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36  e..**.** {H11306
34ee0 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  } If the second 
34ef0 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61  parameter (zDbNa
34f00 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74  me) does not mat
34f10 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ch the name of a
34f20 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ny.** open datab
34f30 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53  ase file, then S
34f40 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72  QLITE_ERROR is r
34f50 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37  eturned. {H11307
34f60 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20  } This error.** 
34f70 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65  code is not reme
34f80 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20  mbered and will 
34f90 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20  not be recalled 
34fa0 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
34fb0 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  ode()].** or [sq
34fc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
34fd0 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e   {A11308} The un
34fe0 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f  derlying xFileCo
34ff0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67  ntrol method mig
35000 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72  ht.** also retur
35010 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  n SQLITE_ERROR. 
35020 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20   {A11309} There 
35030 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73  is no way to dis
35040 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e  tinguish between
35050 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74  .** an incorrect
35060 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20   zDbName and an 
35070 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74  SQLITE_ERROR ret
35080 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  urn from the und
35090 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65  erlying.** xFile
350a0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
350b0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20  {END}.**.** See 
350c0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
350d0 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
350e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
350f0 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
35100 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
35110 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
35120 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
35130 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69   CAPI3REF: Testi
35140 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31  ng Interface {H1
35150 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a  1400} <S30800>.*
35160 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35170 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20  _test_control() 
35180 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
35190 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e  d to read out in
351a0 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20  ternal.** state 
351b0 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f  of SQLite and to
351c0 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69   inject faults i
351d0 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74  nto SQLite for t
351e0 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73  esting.** purpos
351f0 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  es.  The first p
35200 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f  arameter is an o
35210 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68  peration code th
35220 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
35230 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61   the number, mea
35240 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74  ning, and operat
35250 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65  ion of all subse
35260 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
35270 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
35280 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f  erface is not fo
35290 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61  r use by applica
352a0 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74  tions.  It exist
352b0 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20  s solely.** for 
352c0 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f  verifying the co
352d0 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrect operation 
352e0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
352f0 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e  brary.  Dependin
35300 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20  g.** on how the 
35310 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
35320 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73  s compiled, this
35330 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
35340 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a   not exist..**.*
35350 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
35360 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63   the operation c
35370 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e  odes, their mean
35380 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65  ings, the parame
35390 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b  ters.** they tak
353a0 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79  e, and what they
353b0 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a   do are all subj
353c0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
353d0 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a  thout notice..**
353e0 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20   Unlike most of 
353f0 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20  the SQLite API, 
35400 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
35410 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
35420 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f  to.** operate co
35430 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20  nsistently from 
35440 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
35450 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20  he next..*/.int 
35460 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
35470 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e  trol(int op, ...
35480 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35490 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65  EF: Testing Inte
354a0 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20  rface Operation 
354b0 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c  Codes {H11410} <
354c0 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H11400>.**.** Th
354d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
354e0 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72  e the valid oper
354f0 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d  ation code param
35500 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73  eters used.** as
35510 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35520 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
35530 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e  test_control()].
35540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72  .**.** These par
35550 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69  ameters and thei
35560 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73  r meanings are s
35570 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
35580 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  .** without noti
35590 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65  ce.  These value
355a0 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e  s are for testin
355b0 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e  g purposes only.
355c0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
355d0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
355e0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72  any of these par
355f0 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a  ameters or the.*
35600 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  * [sqlite3_test_
35610 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
35620 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
35630 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
35640 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20  _PRNG_SAVE      
35650 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
35660 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
35670 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45  TRL_PRNG_RESTORE
35680 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
35690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
356a0 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45  STCTRL_PRNG_RESE
356b0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
356c0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
356d0 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43  _TESTCTRL_BITVEC
356e0 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20  _TEST           
356f0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
35700 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55  ITE_TESTCTRL_FAU
35710 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20  LT_INSTALL      
35720 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
35730 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
35740 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f  BENIGN_MALLOC_HO
35750 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69  OKS     10.#defi
35760 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
35770 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20  RL_PENDING_BYTE 
35780 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
35790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
357a0 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53 74  QLite Runtime St
357b0 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c 53  atus {H17200} <S
357c0 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60200>.** EXPERI
357d0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69  MENTAL.**.** Thi
357e0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  s interface is u
357f0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
35800 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69  runtime status i
35810 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
35820 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d 61  out the preforma
35830 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20 61  nce of SQLite, a
35840 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f  nd optionally to
35850 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a 2a   reset various.*
35860 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  * highwater mark
35870 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  s.  The first ar
35880 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
35890 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a  eger code for.**
358a0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70 61   the specific pa
358b0 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73 75  rameter to measu
358c0 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64 20  re.  Recognized 
358d0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a  integer codes.**
358e0 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d   are of the form
358f0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f   [SQLITE_STATUS_
35900 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51  MEMORY_USED | SQ
35910 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d  LITE_STATUS_...]
35920 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74  ..** The current
35930 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 61   value of the pa
35940 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75 72  rameter is retur
35950 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 65  ned into *pCurre
35960 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68 65  nt..** The highe
35970 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75  st recorded valu
35980 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e  e is returned in
35990 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20 49   *pHighwater.  I
359a0 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c  f the.** resetFl
359b0 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ag is true, then
359c0 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65 63   the highest rec
359d0 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 73  ord value is res
359e0 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69  et after.** *pHi
359f0 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74 74  ghwater is writt
35a00 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65 74  en. Some paramet
35a10 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72  ers do not recor
35a20 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a  d the highest.**
35a30 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f   value.  For tho
35a40 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
35a50 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74   nothing is writ
35a60 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 77  ten into *pHighw
35a70 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65 73  ater and the res
35a80 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 65  etFlag is ignore
35a90 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72 61  d..** Other para
35aa0 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f 6e  meters record on
35ab0 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65 72  ly the highwater
35ac0 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68   mark and not th
35ad0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c  e current.** val
35ae0 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20 6c  ue.  For these l
35af0 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72 73  atter parameters
35b00 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74   nothing is writ
35b10 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72 65  ten into *pCurre
35b20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  nt..**.** This r
35b30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
35b40 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
35b50 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65  ess and a non-ze
35b60 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ro.** [error cod
35b70 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
35b80 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35b90 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 20  e is threadsafe 
35ba0 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69  but is not atomi
35bb0 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  c.  This routine
35bc0 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77   can.** called w
35bd0 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61  hile other threa
35be0 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74  ds are running t
35bf0 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65  he same or diffe
35c00 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69  rent SQLite.** i
35c10 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
35c20 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72  ver the values r
35c30 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72  eturned in *pCur
35c40 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69  rent and.** *pHi
35c50 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20  ghwater reflect 
35c60 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51  the status of SQ
35c70 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e  Lite at differen
35c80 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65  t points in time
35c90 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f  .** and it is po
35ca0 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74  ssible that anot
35cb0 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74  her thread might
35cc0 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61   change the para
35cd0 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77  meter.** in betw
35ce0 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68  een the times wh
35cf0 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64  en *pCurrent and
35d00 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65   *pHighwater are
35d10 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20   written..**.** 
35d20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
35d30 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a  e3_db_status()].
35d40 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
35d50 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
35d60 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70  e3_status(int op
35d70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c  , int *pCurrent,
35d80 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72   int *pHighwater
35d90 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  , int resetFlag)
35da0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
35db0 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d  EF: Status Param
35dc0 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c  eters {H17250} <
35dd0 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  H17200>.** EXPER
35de0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
35df0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
35e00 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20  tants designate 
35e10 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65  various run-time
35e20 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65   status paramete
35e30 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  rs.** that can b
35e40 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
35e50 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
35e60 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
35e70 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
35e80 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64  S_MEMORY_USED</d
35e90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
35ea0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
35eb0 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f  current amount o
35ec0 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64  f memory checked
35ed0 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73   out.** using [s
35ee0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35ef0 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74 6c  , either directl
35f00 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e  y or indirectly.
35f10 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20    The.** figure 
35f20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d  includes calls m
35f30 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ade to [sqlite3_
35f40 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65  malloc()] by the
35f50 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
35f60 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  and internal mem
35f70 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68 65  ory usage by the
35f80 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
35f90 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79    Scratch memory
35fa0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  .** controlled b
35fb0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
35fc0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75  _SCRATCH] and au
35fd0 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63  xiliary page-cac
35fe0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e  he.** memory con
35ff0 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49  trolled by [SQLI
36000 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
36010 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c  CHE] is not incl
36020 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20  uded in.** this 
36030 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
36040 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20  amount returned 
36050 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68  is the sum of th
36060 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  e allocation.** 
36070 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65  sizes as reporte
36080 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d  d by the xSize m
36090 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65  ethod in [sqlite
360a0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c  3_mem_methods].<
360b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
360c0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c  QLITE_STATUS_MAL
360d0 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a  LOC_SIZE</dt>.**
360e0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
360f0 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20  ter records the 
36100 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61  largest memory a
36110 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
36120 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b  t.** handed to [
36130 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
36140 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
36150 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65  alloc()] (or the
36160 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65  ir.** internal e
36170 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e  quivalents).  On
36180 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ly the value ret
36190 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  urned in the.** 
361a0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61  *pHighwater para
361b0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
361c0 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f  3_status()] is o
361d0 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a  f interest.  .**
361e0 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74   The value writt
361f0 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75  en into the *pCu
36200 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20  rrent parameter 
36210 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  is undefined.</d
36220 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
36230 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43  ITE_STATUS_PAGEC
36240 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a  ACHE_USED</dt>.*
36250 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
36260 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65  eter returns the
36270 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
36280 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65   used out of the
36290 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 6d  .** [pagecache m
362a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
362b0 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 67   that was config
362c0 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ured using .** [
362d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
362e0 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a  GECACHE].  The.*
362f0 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  * value returned
36300 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f   is in pages, no
36310 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  t in bytes.</dd>
36320 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
36330 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43  E_STATUS_PAGECAC
36340 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e  HE_OVERFLOW</dt>
36350 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
36360 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
36370 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
36380 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 65  es of page cache
36390 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77  .** allocation w
363a0 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62  hich could not b
363b0 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20  e statisfied by 
363c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
363d0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a  IG_PAGECACHE].**
363e0 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72   buffer and wher
363f0 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72  e forced to over
36400 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33  flow to [sqlite3
36410 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
36420 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 6c  .** returned val
36430 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f  ue includes allo
36440 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65  cations that ove
36450 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 20  rflowed because 
36460 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f  they.** where to
36470 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 65  o large (they we
36480 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  re larger than t
36490 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65  he "sz" paramete
364a0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
364b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
364c0 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f  ]) and allocatio
364d0 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77  ns that overflow
364e0 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f  ed because.** no
364f0 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 20   space was left 
36500 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
36510 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
36520 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
36530 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f  PAGECACHE_SIZE</
36540 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
36550 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64  parameter record
36560 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65  s the largest me
36570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
36580 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65  request.** hande
36590 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 20  d to [pagecache 
365a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
365b0 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c  ].  Only the val
365c0 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74  ue returned in t
365d0 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65  he.** *pHighwate
365e0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
365f0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
36600 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74  ] is of interest
36610 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .  .** The value
36620 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
36630 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61  e *pCurrent para
36640 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e  meter is undefin
36650 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
36660 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
36670 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f 64  _SCRATCH_USED</d
36680 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
36690 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73  arameter returns
366a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
366b0 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 20  llocations used 
366c0 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  out of the.** [s
366d0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c  cratch memory al
366e0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
366f0 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51  red using.** [SQ
36700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
36710 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  TCH].  The value
36720 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20   returned is in 
36730 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74  allocations, not
36740 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 53  .** in bytes.  S
36750 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 68  ince a single th
36760 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61  read may only ha
36770 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 61  ve one scratch a
36780 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74  llocation.** out
36790 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d 65  standing at time
367a0 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  , this parameter
367b0 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 68   also reports th
367c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  e number of thre
367d0 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72  ads.** using scr
367e0 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 74  atch memory at t
367f0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64  he same time.</d
36800 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
36810 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
36820 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e  CH_OVERFLOW</dt>
36830 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
36840 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
36850 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
36860 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  es of scratch me
36870 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
36880 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e  on which could n
36890 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64  ot be statisfied
368a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
368b0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 0a  CONFIG_SCRATCH].
368c0 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68  ** buffer and wh
368d0 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76  ere forced to ov
368e0 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74  erflow to [sqlit
368f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
36900 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74  he values.** ret
36910 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f 76  urned include ov
36920 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 20  erflows because 
36930 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c  the requested al
36940 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f  location was too
36950 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 74  .** larger (that
36960 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 65   is, because the
36970 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63   requested alloc
36980 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 72  ation was larger
36990 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a   than the.** "sz
369a0 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  " parameter to [
369b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
369c0 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 61  RATCH]) and beca
369d0 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 62  use no scratch b
369e0 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77  uffer.** slots w
369f0 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  ere available..*
36a00 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
36a10 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
36a20 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74  SCRATCH_SIZE</dt
36a30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36a40 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20  rameter records 
36a50 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f  the largest memo
36a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
36a70 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20  quest.** handed 
36a80 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f  to [scratch memo
36a90 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20  ry allocator].  
36aa0 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72  Only the value r
36ab0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a  eturned in the.*
36ac0 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61  * *pHighwater pa
36ad0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
36ae0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73  te3_status()] is
36af0 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a   of interest.  .
36b00 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69  ** The value wri
36b10 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70  tten into the *p
36b20 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65  Current paramete
36b30 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c  r is undefined.<
36b40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
36b50 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52  QLITE_STATUS_PAR
36b60 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a  SER_STACK</dt>.*
36b70 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
36b80 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
36b90 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72 20   deepest parser 
36ba0 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e  stack.  It is on
36bb0 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c  ly.** meaningful
36bc0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
36bd0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 54  mpiled with [YYT
36be0 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 54  RACKMAXSTACKDEPT
36bf0 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  H].</dd>.** </dl
36c00 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74  >.**.** New stat
36c10 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d 61  us parameters ma
36c20 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d 20  y be added from 
36c30 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f  time to time..*/
36c40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36c50 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53  STATUS_MEMORY_US
36c60 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  ED          0.#d
36c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
36c80 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53  TUS_PAGECACHE_US
36c90 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  ED       1.#defi
36ca0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ne SQLITE_STATUS
36cb0 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46  _PAGECACHE_OVERF
36cc0 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 20  LOW   2.#define 
36cd0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43  SQLITE_STATUS_SC
36ce0 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 20  RATCH_USED      
36cf0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
36d00 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
36d10 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 20  CH_OVERFLOW     
36d20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
36d30 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53  _STATUS_MALLOC_S
36d40 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a 23  IZE          5.#
36d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
36d60 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43  ATUS_PARSER_STAC
36d70 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66  K         6.#def
36d80 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
36d90 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45  S_PAGECACHE_SIZE
36da0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
36db0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53   SQLITE_STATUS_S
36dc0 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 20  CRATCH_SIZE     
36dd0 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
36de0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
36df0 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 75  Connection Statu
36e00 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 32  s {H17500} <S602
36e10 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
36e20 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  TAL.**.** This i
36e30 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
36e40 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e   to retrieve run
36e50 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f  time status info
36e60 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75  rmation .** abou
36e70 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 61  t a single [data
36e80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36e90 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
36ea0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
36eb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36ec0 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 65  ion object to be
36ed0 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
36ee0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
36ef0 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 61  ent.** is the pa
36f00 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 72  rameter to inter
36f10 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e 74  rogate.  Current
36f20 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c  ly, the only all
36f30 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f  owed value.** fo
36f40 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  r the second par
36f50 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 54  ameter is [SQLIT
36f60 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41  E_DBSTATUS_LOOKA
36f70 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41  SIDE_USED]..** A
36f80 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e  dditional option
36f90 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70  s will likely ap
36fa0 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 72  pear in future r
36fb0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
36fc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72  e..**.** The cur
36fd0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68  rent value of th
36fe0 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72 61  e requested para
36ff0 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65 6e  meter is written
37000 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61   into *pCur.** a
37010 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20 69  nd the highest i
37020 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c  nstantaneous val
37030 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ue is written in
37040 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 0a  to *pHiwtr.  If.
37050 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 20  ** the resetFlg 
37060 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
37070 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e  e highest instan
37080 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73  taneous value is
37090 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 64  .** reset back d
370a0 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 65  own to the curre
370b0 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  nt value..**.** 
370c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
370d0 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64  e3_status()] and
370e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73   [sqlite3_stmt_s
370f0 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  tatus()]..*/.SQL
37100 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
37110 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
37120 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a 2c  status(sqlite3*,
37130 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43   int op, int *pC
37140 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 2c  ur, int *pHiwtr,
37150 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a   int resetFlg);.
37160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37170 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65   Status Paramete
37180 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 20  rs for database 
37190 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37  connections {H17
371a0 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a  520} <H17500>.**
371b0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
371c0 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62 73  .** Status verbs
371d0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 62   for [sqlite3_db
371e0 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a  _status()]..**.*
371f0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
37200 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f  LITE_DBSTATUS_LO
37210 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64 74  OKASIDE_USED</dt
37220 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
37230 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
37240 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f  the number of lo
37250 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 73  okaside memory s
37260 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  lots currently.*
37270 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f  * checked out.</
37280 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
37290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
372a0 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44  BSTATUS_LOOKASID
372b0 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f  E_USED     0.../
372c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
372d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
372e0 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 35 30  t Status {H17550
372f0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58  } <S60200>.** EX
37300 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
37310 20 45 61 63 68 20 70 72 65 70 61 72 65 64 20 73   Each prepared s
37320 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69  tatement maintai
37330 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53  ns various.** [S
37340 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53  QLITE_STMTSTATUS
37350 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 73  _SORT | counters
37360 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 74  ] that measure t
37370 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
37380 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 65 72  times it has per
37390 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63 20  formed specific 
373a0 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 65  operations.  The
373b0 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a  se counters can.
373c0 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 6d 6f  ** be used to mo
373d0 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 6f 72  nitor the perfor
373e0 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 72 69  mance characteri
373f0 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 72 65  stics of the pre
37400 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
37410 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  nts.  For exampl
37420 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72  e, if the number
37430 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 73 20   of table steps 
37440 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 73 0a  greatly exceeds.
37450 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
37460 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 73 20   table searches 
37470 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 2c 20  or result rows, 
37480 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e 64 20  that would tend 
37490 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74  to indicate.** t
374a0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
374b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73   statement is us
374c0 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 6c 65  ing a full table
374d0 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 68 61   scan rather tha
374e0 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20  n.** an index.  
374f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
37500 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
37510 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 72 65   retrieve and re
37520 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 6c 75  set counter valu
37530 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72  es from.** a [pr
37540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37550 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
37560 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 70 72  gument is the pr
37570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37580 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62 65  .** object to be
37590 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
375a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
375b0 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ent.** is an int
375c0 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 61 20  eger code for a 
375d0 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45  specific [SQLITE
375e0 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54  _STMTSTATUS_SORT
375f0 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74   | counter].** t
37600 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65  o be interrogate
37610 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 72 65  d. .** The curre
37620 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  nt value of the 
37630 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74 65  requested counte
37640 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
37650 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 46 6c  * If the resetFl
37660 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  g is true, then 
37670 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20 72  the counter is r
37680 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 74  eset to zero aft
37690 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  er this.** inter
376a0 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72 6e  face call return
376b0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
376c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  o: [sqlite3_stat
376d0 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  us()] and [sqlit
376e0 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e  e3_db_status()].
376f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
37700 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
37710 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28  te3_stmt_status(
37720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
37730 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 46  nt op,int resetF
37740 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lg);../*.** CAPI
37750 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72  3REF: Status Par
37760 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65 70  ameters for prep
37770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
37780 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35 30  {H17570} <H17550
37790 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
377a0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72  L.**.** These pr
377b0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
377c0 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  s define integer
377d0 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d 65   codes that name
377e0 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75   counter.** valu
377f0 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  es associated wi
37800 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  th the [sqlite3_
37810 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 69  stmt_status()] i
37820 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
37830 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
37840 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 72   various counter
37850 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
37860 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
37870 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53  <dt>SQLITE_STMTS
37880 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53  TATUS_FULLSCAN_S
37890 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEP</dt>.** <dd>
378a0 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62  This is the numb
378b0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
378c0 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 70   SQLite has step
378d0 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a  ped forward in.*
378e0 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 72  * a table as par
378f0 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c  t of a full tabl
37900 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e  e scan.  Large n
37910 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 20  umbers for this 
37920 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69  counter.** may i
37930 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e  ndicate opportun
37940 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72  ities for perfor
37950 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e  mance improvemen
37960 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61  t through .** ca
37970 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64  reful use of ind
37980 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ices.</dd>.**.**
37990 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54   <dt>SQLITE_STMT
379a0 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e  STATUS_SORT</dt>
379b0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20  .** <dd>This is 
379c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f  the number of so
379d0 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68  rt operations th
379e0 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  at have occurred
379f0 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20  ..** A non-zero 
37a00 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63 6f  value in this co
37a10 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63 61  unter may indica
37a20 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  te an opportunit
37a30 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d  y to.** improvem
37a40 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ent performance 
37a50 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c 20  through careful 
37a60 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c  use of indices.<
37a70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
37a80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
37a90 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55  TE_STMTSTATUS_FU
37aa0 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20 20  LLSCAN_STEP     
37ab0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
37ac0 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54  _STMTSTATUS_SORT
37ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
37ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37af0 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61 63   Custom Page Cac
37b00 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50  he Object.** EXP
37b10 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
37b20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63  The sqlite3_pcac
37b30 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 71 75  he type is opaqu
37b40 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65 6d  e.  It is implem
37b50 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ented by.** the 
37b60 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65  pluggable module
37b70 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
37b80 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65  re has no knowle
37b90 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69  dge of.** its si
37ba0 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73  ze or internal s
37bb0 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65 76  tructure and nev
37bc0 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 74 68  er deals with th
37bd0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 61  e.** sqlite3_pca
37be0 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65 70  che object excep
37bf0 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64  t by holding and
37c00 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 72   passing pointer
37c10 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65  s.** to the obje
37c20 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73  ct..**.** See [s
37c30 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
37c40 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 74  thods] for addit
37c50 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
37c60 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
37c70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61  ruct sqlite3_pca
37c80 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63  che sqlite3_pcac
37c90 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  he;../*.** CAPI3
37ca0 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e  REF: Application
37cb0 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 43 61   Defined Page Ca
37cc0 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  che..** EXPERIME
37cd0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  NTAL.**.** The [
37ce0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
37cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
37d00 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74  CACHE], ...) int
37d10 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65  erface can.** re
37d20 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72 6e  gister an altern
37d30 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65  ative page cache
37d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37d50 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 6e  by passing in an
37d60 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66   .** instance of
37d70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61   the sqlite3_pca
37d80 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75  che_methods stru
37d90 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72  cture. The major
37da0 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68  ity of the .** h
37db0 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 20  eap memory used 
37dc0 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 73 65  by sqlite is use
37dd0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61  d by the page ca
37de0 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 61 74  che to cache dat
37df0 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c  a read .** from,
37e00 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65 20   or ready to be 
37e10 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 20  written to, the 
37e20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 42  database file. B
37e30 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61  y implementing a
37e40 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 65   .** custom page
37e50 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 68 69   cache using thi
37e60 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 63  s API, an applic
37e70 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f  ation can contro
37e80 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69  l more .** preci
37e90 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 20  sely the amount 
37ea0 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d  of memory consum
37eb0 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74 68  ed by sqlite, th
37ec0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a  e way in which .
37ed0 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 69  ** said memory i
37ee0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20  s allocated and 
37ef0 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68  released, and th
37f00 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20  e policies used 
37f10 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  to .** determine
37f20 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 20 70   exactly which p
37f30 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 62 61  arts of a databa
37f40 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 63 68  se file are cach
37f50 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68  ed and for .** h
37f60 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ow long..**.** T
37f70 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
37f80 68 65 20 73 74 72 75 63 74 75 72 65 20 61 72 65  he structure are
37f90 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 6e   copied to an in
37fa0 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79  ternal buffer by
37fb0 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69   sqlite.** withi
37fc0 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73  n the call to [s
37fd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a  qlite3_config]..
37fe0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28  **.** The xInit(
37ff0 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c  ) method is call
38000 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
38010 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
38020 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a  3_initialize()].
38030 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79  ** (usually only
38040 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65   once during the
38050 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
38060 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73   process). It is
38070 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70   passed.** a cop
38080 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
38090 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e  _pcache_methods.
380a0 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63  pArg value. It c
380b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65  an be used to se
380c0 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73  t.** up global s
380d0 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75  tructures and mu
380e0 74 65 78 65 73 20 72 65 71 75 69 72 65 64 20 62  texes required b
380f0 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67  y the custom pag
38100 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c  e cache .** impl
38110 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20  ementation. The 
38120 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68  xShutdown() meth
38130 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f  od is called fro
38140 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71  m within .** [sq
38150 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
38160 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ], if the applic
38170 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68  ation invokes th
38180 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62  is API. It can b
38190 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65  e used.** to cle
381a0 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74 61  an up any outsta
381b0 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20  nding resources 
381c0 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73  before process s
381d0 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75  hutdown, if requ
381e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
381f0 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64  xCreate() method
38200 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   is used to cons
38210 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68  truct a new cach
38220 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a  e instance. The.
38230 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ** first paramet
38240 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 74  er, szPage, is t
38250 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
38260 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 74 68   of the pages th
38270 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  at must.** be al
38280 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 63  located by the c
38290 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69 6c  ache. szPage wil
382a0 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72  l not be a power
382b0 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20   of two. The.** 
382c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
382d0 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20   bPurgeable, is 
382e0 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68  true if the cach
382f0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
38300 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20  will.** be used 
38310 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
38320 65 20 70 61 67 65 73 20 72 65 61 64 20 66 72 6f  e pages read fro
38330 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20  m a file stored 
38340 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66  on disk, or.** f
38350 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 75 73  alse if it is us
38360 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d  ed for an in-mem
38370 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 54 68  ory database. Th
38380 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
38390 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e  tation.** does n
383a0 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e  ot have to do an
383b0 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62  ything special b
383c0 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 6c 75  ased on the valu
383d0 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 2c  e of bPurgeable,
383e0 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c 79  .** it is purely
383f0 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a   advisory. .**.*
38400 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a 65  * The xCachesize
38410 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65  () method may be
38420 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 74   called at any t
38430 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74 6f  ime by SQLite to
38440 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 67   set the.** sugg
38450 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 61  ested maximum ca
38460 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72  che-size (number
38470 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65 64   of pages stored
38480 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a 2a   by) the cache.*
38490 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73 65  * instance passe
384a0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
384b0 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 73  rgument. This is
384c0 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 69   the value confi
384d0 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74  gured using.** t
384e0 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41 47  he SQLite "[PRAG
384f0 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 20  MA cache_size]" 
38500 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 68  command. As with
38510 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65 20   the bPurgeable 
38520 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 68  parameter,.** th
38530 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38540 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64   is not required
38550 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20   to do anything 
38560 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 68 69  special with thi
38570 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20 69  s.** value, it i
38580 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
38590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65  .**.** The xPage
385a0 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73  count() method s
385b0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
385c0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
385d0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74   currently.** st
385e0 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 63 68  ored in the cach
385f0 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 61 6e  e supplied as an
38600 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a   argument..** .*
38610 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20 6d  * The xFetch() m
38620 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f  ethod is used to
38630 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61 6e   fetch a page an
38640 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
38650 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 20  er to it. .** A 
38660 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73 20  'page', in this 
38670 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62 75  context, is a bu
38680 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20 62  ffer of szPage b
38690 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74 20  ytes aligned at 
386a0 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f 75  an.** 8-byte bou
386b0 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65 20  ndary. The page 
386c0 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69 73  to be fetched is
386d0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
386e0 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 6d  he key. The.** m
386f0 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 65  imimum key value
38700 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74 20   is 1. After it 
38710 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65 76  has been retriev
38720 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68 2c  ed using xFetch,
38730 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 73   the page .** is
38740 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
38750 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e pinned..**.** 
38760 49 66 20 74