/ Hex Artifact Content
Login

Artifact 14f4d065bafed8500ea558a75a8e2be89c784d61:


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 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 33 33 20 32 30 30 39 2f 30  n,v 1.433 2009/0
05f0: 32 2f 31 38 20 31 38 3a 33 37 3a 35 39 20 64 72  2/18 18:37:59 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f 2a  R | (17<<8))../*
4010: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
4020: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
4030: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48 31  n Operations {H1
4040: 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0230} <H11120> <
4050: 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H12700>.**.** Th
4060: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
4070: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
4080: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
4090: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
40a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
40b0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
40c0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
40d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
40e0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
40f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
4100: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
4110: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4120: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
4130: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
4140: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
4150: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
4160: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
4170: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
4180: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
4190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
41a0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
41b0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
41c0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
41d0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
41e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
41f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
4200: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
4210: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
4220: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
4230: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
4240: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
4250: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
4260: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
4270: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
4280: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
4290: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
42a0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
42b0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
42c0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
42d0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
42e0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
42f0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
4300: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
4310: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
4320: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
4330: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
4340: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
4350: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
4360: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
4370: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
4380: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
4390: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
43a0: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
43b0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
43c0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
43d0: 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31 30  acteristics {H10
43e0: 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a  240} <H11120>.**
43f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
4400: 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68  apabilities meth
4410: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
4420: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
4430: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
4440: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
4450: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
4460: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
4470: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
4480: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
4490: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
44a0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
44b0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
44c0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
44d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
44e0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
44f0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
4500: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4510: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
4520: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
4530: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
4540: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
4550: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4560: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
4570: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
4580: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
4590: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
45a0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
45b0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
45c0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
45d0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
45e0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
45f0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
4600: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4610: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
4620: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
4630: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
4640: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
4650: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
4660: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
4670: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
4680: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
4690: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
46a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
46b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
46c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
46d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
46e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
46f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
4700: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
4710: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
4720: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
4730: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
4740: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4750: 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  C          0x000
4760: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
4770: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4780: 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30  C512       0x000
4790: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
47a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
47b0: 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C1K        0x000
47c0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
47d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
47e0: 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C2K        0x000
47f0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
4800: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4810: 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C4K        0x000
4820: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
4830: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4840: 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C8K        0x000
4850: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
4860: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4870: 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30  C16K       0x000
4880: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
4890: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
48a0: 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30  C32K       0x000
48b0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
48c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
48d0: 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30  C64K       0x000
48e0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
48f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
4900: 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30  APPEND     0x000
4910: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
4920: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
4930: 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30  NTIAL      0x000
4940: 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00400../*.** CAP
4950: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
4960: 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 32  ing Levels {H102
4970: 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31  50} <H11120> <H1
4980: 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  1310>.**.** SQLi
4990: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
49a0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
49b0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
49c0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
49d0: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
49e0: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
49f0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
4a00: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
4a10: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
4a20: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4a40: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
4a50: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
4a60: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
4a70: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
4a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
4a90: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
4aa0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
4ab0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4ad0: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
4ae0: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
4af0: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
4b00: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b 48  on Type Flags {H
4b10: 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10260} <H11120>.
4b20: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
4b30: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
4b40: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
4b50: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
4b60: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
4b70: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
4b80: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
4b90: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
4ba0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
4bb0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
4bc0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
4bd0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
4be0: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
4bf0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
4c00: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
4c10: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
4c20: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
4c30: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
4c40: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
4c50: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
4c60: 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45  shed. The SQLITE
4c70: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61  _SYNC_NORMAL fla
4c80: 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  g means.** to us
4c90: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
4ca0: 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20   semantics. The 
4cb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
4cc0: 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74   flag means.** t
4cd0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
4ce0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
4cf0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
4d00: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4d10: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
4d20: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
4d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
4d40: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
4d50: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
4d60: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
4d70: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
4d80: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
4d90: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
4da0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
4db0: 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30 31  e {H11110} <S201
4dc0: 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10>.**.** An [sq
4dd0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
4de0: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
4df0: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
4e00: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
4e10: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
4e20: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
4e30: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
4e40: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
4e50: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
4e60: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
4e70: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
4e80: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
4e90: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
4ea0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
4eb0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
4ec0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
4ed0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
4ee0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
4ef0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
4f00: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
4f10: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
4f20: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
4f30: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
4f40: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
4f50: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
4f60: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
4f70: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
4f80: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
4f90: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
4fa0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
4fb0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
4fc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
4fd0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
4fe0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
4ff0: 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20  Object {H11120} 
5000: 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45  <S20110>.**.** E
5010: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
5020: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
5030: 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68  _vfs] xOpen meth
5040: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
5050: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
5060: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
5070: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
5080: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
5090: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
50a0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
50b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
50c0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
50d0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
50e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
50f0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
5100: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
5110: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
5120: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
5130: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
5140: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
5150: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
5160: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
5170: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
5180: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
5190: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
51a0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
51b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
51c0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
51d0: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
51e0: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
51f0: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
5200: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
5210: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
5220: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
5230: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
5240: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
5250: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
5260: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
5270: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
5280: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
5290: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
52a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
52b0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
52c0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
52d0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
52e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
52f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5300: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5310: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5320: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5330: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
5340: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5350: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5360: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
5370: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5380: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
5390: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
53a0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
53b0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
53c0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
53d0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
53e0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
53f0: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
5400: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5410: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
5420: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
5430: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
5440: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
5450: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
5460: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
5470: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
5480: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
5490: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
54a0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
54b0: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
54c0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
54d0: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
54e0: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
54f0: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
5500: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
5510: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
5520: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
5530: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
5540: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
5550: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
5560: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
5570: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
5580: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
5590: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
55a0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
55b0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
55c0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
55d0: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
55e0: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
55f0: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
5600: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
5610: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
5620: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
5630: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
5640: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
5650: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
5660: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
5670: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
5680: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
5690: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
56a0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
56b0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
56c0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
56d0: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
56e0: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
56f0: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
5700: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
5710: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
5720: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
5730: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
5740: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
5750: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
5760: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
5770: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
5780: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
5790: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
57a0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
57b0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
57c0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
57d0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
57e0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
57f0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
5800: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
5810: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
5820: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
5830: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
5840: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
5850: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
5860: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
5870: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
5880: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
5890: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
58a0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
58b0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
58c0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
58d0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
58e0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
58f0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
5900: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
5910: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
5920: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
5930: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
5940: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
5950: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
5960: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
5970: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
5980: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5990: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
59a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
59b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
59c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
59d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
59e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
59f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
5a00: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5a10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
5a20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5a30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
5a40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5a50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
5a60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5a70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5a80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
5aa0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5ab0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5ac0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
5ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5ae0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
5af0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5b00: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5b10: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5b20: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
5b30: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5b40: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b60: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
5b70: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5b80: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5b90: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5ba0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5bb0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5bc0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5bd0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5be0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5bf0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5c00: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5c10: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
5c20: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
5c30: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5c40: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
5c50: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5c60: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
5c70: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5c80: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5c90: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5ca0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5cb0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5cc0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5cd0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5ce0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5cf0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5d00: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5d10: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
5d20: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
5d30: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
5d40: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
5d50: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
5d60: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
5d70: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
5d80: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
5d90: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
5da0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
5db0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
5dc0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
5dd0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
5de0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
5df0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
5e00: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
5e10: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
5e20: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
5e30: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
5e40: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
5e50: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
5e60: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
5e70: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
5e80: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
5e90: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
5ea0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
5eb0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
5ec0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
5ed0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
5ee0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
5ef0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
5f00: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
5f10: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
5f20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
5f30: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
5f40: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
5f50: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
5f60: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
5f70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
5f80: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
5f90: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
5fa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5fb0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
5fc0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
5fd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
5fe0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
5ff0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6000: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6010: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6020: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6030: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6040: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6050: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
6060: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
6070: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
6080: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
6090: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
60a0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
60b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
60c0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
60d0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
60e0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
60f0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
6100: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
6110: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
6120: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
6130: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
6140: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6150: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
6160: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
6170: 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53  odes {H11310} <S
6180: 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30800>.**.** The
6190: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
61a0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
61b0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
61c0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
61d0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
61e0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
61f0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
6200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6210: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6220: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6240: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6250: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6260: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6270: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6280: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6290: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
62a0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
62b0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
62c0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
62d0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
62e0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
62f0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6300: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6310: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6320: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6330: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6340: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6350: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6360: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6370: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6380: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6390: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
63a0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
63b0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
63c0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
63d0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6400: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6410: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
6420: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32  PROXYFILE      2
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
6450: 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65  E      3.#define
6460: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
6470: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 34  NO             4
6480: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6490: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b  : Mutex Handle {
64a0: 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30 3e  H17110} <S20130>
64b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
64c0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
64d0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
64e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
64f0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
6500: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
6510: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
6520: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
6530: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
6540: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
6550: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
6560: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
6570: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
6580: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
6590: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
65a0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
65b0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
65c0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
65d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
65e0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
65f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6600: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
6610: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
6620: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6630: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 48  erface Object {H
6640: 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a  11140} <S20100>.
6650: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
6660: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
6670: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
6680: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
6690: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
66a0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
66b0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
66c0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
66d0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
66e0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
66f0: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
6700: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
6710: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
6720: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
6730: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
6740: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
6750: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
6760: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
6770: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
6780: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
6790: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
67a0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
67b0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
67c0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
67d0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
67e0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
67f0: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
6800: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
6810: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
6820: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
6830: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
6840: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
6850: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
6860: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
6870: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
6880: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
6890: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
68a0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
68b0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
68c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
68d0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
68e0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
68f0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
6900: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
6910: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
6920: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
6930: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
6940: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
6950: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
6960: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
6970: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
6980: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
6990: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
69a0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
69b0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
69c0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
69d0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
69e0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
69f0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
6a00: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
6a10: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
6a20: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
6a30: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
6a40: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
6a50: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
6a60: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
6a70: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
6a80: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
6a90: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
6aa0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
6ab0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
6ac0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6ad0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
6ae0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
6af0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
6b00: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
6b10: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
6b20: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
6b30: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
6b40: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
6b50: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
6b60: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
6b70: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
6b80: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
6b90: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
6ba0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
6bb0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
6bc0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
6bd0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
6be0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
6bf0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
6c00: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
6c10: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
6c20: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
6c30: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53  modules..**.** S
6c40: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
6c50: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
6c60: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
6c70: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
6c80: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
6c90: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
6ca0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
6cb0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
6cc0: 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68  ).  SQLite furth
6cd0: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
6ce0: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
6cf0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
6d00: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
6d10: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
6d20: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
6d30: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
6d40: 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20 74  s sentense,.** t
6d50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6d60: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
6d70: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
6d80: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
6d90: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
6da0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
6db0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
6dc0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
6dd0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
6de0: 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73 20  ter is xOpen is 
6df0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
6e00: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
6e10: 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77 6e  t invite its own
6e20: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
6e30: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 57  for the file.  W
6e40: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
6e50: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
6e60: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
6e70: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
6e80: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
6e90: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
6ea0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
6eb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6ec0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
6ed0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
6ee0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
6ef0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
6f00: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
6f10: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6f20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
6f30: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
6f40: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
6f50: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
6f60: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
6f70: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
6f80: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
6f90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
6fa0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
6fb0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
6fc0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
6fd0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
6fe0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
6ff0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
7000: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
7010: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7020: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
7030: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
7040: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
7050: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
7060: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7070: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7080: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
7090: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
70a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
70b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
70c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
70d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
70e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
70f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
7100: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
7110: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7120: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
7130: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7140: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
7150: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7160: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
7170: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
7180: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
7190: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
71a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
71b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
71c0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
71d0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
71e0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
71f0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
7200: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
7210: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
7220: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
7230: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
7240: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
7250: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
7260: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
7270: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
7280: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
7290: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
72a0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
72b0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
72c0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
72d0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
72e0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
72f0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
7300: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
7310: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
7320: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
7330: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
7340: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
7350: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
7360: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
7370: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
7380: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
7390: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
73a0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
73b0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
73c0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
73d0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
73e0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
73f0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
7400: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
7410: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
7420: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
7430: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
7440: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7450: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
7460: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
7470: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
7480: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
7490: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
74a0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
74b0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
74c0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
74d0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54  it is closed.  T
74e0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
74f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
7500: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
7510: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
7520: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
7530: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
7540: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7550: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
7560: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
7570: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
7580: 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65   opened.** for e
7590: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
75a0: 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73    This flag is s
75b0: 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73  et for all files
75c0: 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74   except.** for t
75d0: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
75e0: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 74 20   file..**.** At 
75f0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
7600: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
7610: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
7620: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
7630: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7640: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7650: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7660: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
7670: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
7680: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
7690: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
76a0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
76b0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
76c0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
76d0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  n..**.** The fla
76e0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
76f0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
7700: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
7710: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
7720: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
7730: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
7740: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
7750: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
7760: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
7770: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
7780: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
7790: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
77a0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
77b0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
77c0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
77d0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
77e0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
77f0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
7800: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
7810: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
7820: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
7830: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
7840: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
7850: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
7860: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
7870: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
7880: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
7890: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
78a0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
78b0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
78c0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
78d0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
78e0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
78f0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
7900: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
7910: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
7920: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
7930: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
7940: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
7950: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
7960: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
7970: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
7980: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
7990: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
79a0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
79b0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
79c0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
79d0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
79e0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
79f0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
7a00: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
7a10: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
7a20: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
7a30: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
7a40: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
7a50: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
7a60: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
7a70: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
7a80: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
7a90: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
7aa0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
7ab0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
7ac0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
7ad0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
7ae0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
7af0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
7b00: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
7b10: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
7b20: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
7b30: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
7b40: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
7b50: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
7b60: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
7b70: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
7b80: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
7b90: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7ba0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
7bb0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
7bc0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
7bd0: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
7be0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
7bf0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
7c00: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
7c10: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
7c20: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
7c30: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
7c40: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
7c50: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
7c60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
7c70: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
7c80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
7c90: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
7ca0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
7cb0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
7cc0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
7cd0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
7ce0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
7cf0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
7d00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
7d10: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
7d20: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
7d30: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
7d40: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
7d50: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
7d60: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
7d70: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
7d80: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
7d90: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
7da0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7db0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
7dc0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
7dd0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
7de0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
7df0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
7e00: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
7e10: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7e20: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
7e30: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
7e40: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
7e50: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7e60: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
7e70: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
7e80: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
7e90: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
7ea0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7eb0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
7ec0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
7ed0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
7ee0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
7ef0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
7f00: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
7f10: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
7f20: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
7f30: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
7f40: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
7f50: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
7f60: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
7f70: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
7f80: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
7f90: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
7fa0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
7fb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
7fc0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
7fd0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
7fe0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
7ff0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
8000: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
8010: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
8020: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
8030: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8040: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
8050: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
8060: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
8070: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
8080: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
8090: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
80a0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
80b0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
80c0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
80d0: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
80e0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
80f0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
8100: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
8110: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
8120: 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39  FS method {H1119
8130: 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a  0} <H11140>.**.*
8140: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8150: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
8160: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
8170: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
8180: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
8190: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
81a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
81b0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65  . {END}  They de
81c0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
81d0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
81e0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
81f0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
8200: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
8210: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
8220: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
8230: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
8240: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
8250: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
8260: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8270: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8280: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
8290: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
82a0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
82b0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
82c0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
82d0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
82e0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
82f0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
8300: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
8310: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
8320: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
8330: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8340: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
8350: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8360: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
8370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
8380: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
8390: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
83a0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
83b0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
83c0: 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e  H10130} <S20000>
83d0: 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
83e0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
83f0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
8400: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
8410: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
8420: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
8430: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
8440: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
8450: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
8460: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
8470: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
8480: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a  nitialize()..**.
8490: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
84a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
84b0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
84c0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
84d0: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
84e0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
84f0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
8500: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
8510: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
8520: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
8530: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
8540: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
8550: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
8560: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
8570: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
8580: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
8590: 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74    Only an effect
85a0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
85b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
85c0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
85d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
85e0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
85f0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
8600: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  -ops..**.** Amon
8610: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
8620: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8630: 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  ze() shall invok
8640: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
8650: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
8660: 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ly, sqlite3_shut
8670: 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20  down().** shall 
8680: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
8690: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  s_end()..**.** T
86a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
86b0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
86c0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
86d0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
86e0: 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  ** If for some r
86f0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
8700: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
8710: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
8720: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
8730: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
8740: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
8750: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
8760: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
8770: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
8780: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
8790: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
87a0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
87b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
87c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
87d0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
87e0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
87f0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
8800: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
8810: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
8820: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
8830: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
8840: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
8850: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
8860: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
8870: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
8880: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
8890: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
88a0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
88b0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
88c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
88d0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
88e0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
88f0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
8900: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
8910: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
8920: 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c  ready.  However,
8930: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
8940: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
8950: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
8960: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
8970: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
8980: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
8990: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
89a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
89b0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
89c0: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
89d0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
89e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
89f0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
8a00: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
8a10: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
8a20: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
8a30: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
8a40: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
8a50: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
8a60: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
8a70: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
8a80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
8a90: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
8aa0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
8ab0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
8ac0: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
8ad0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
8ae0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
8af0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
8b00: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
8b10: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
8b20: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
8b30: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
8b40: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
8b50: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
8b60: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
8b70: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
8b80: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
8b90: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
8ba0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
8bb0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
8bc0: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
8bd0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
8be0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
8bf0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
8c00: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
8c10: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
8c20: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
8c30: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
8c40: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
8c50: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
8c60: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
8c70: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
8c80: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
8c90: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
8ca0: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
8cb0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
8cc0: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
8cd0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
8ce0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
8cf0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
8d00: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
8d10: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
8d20: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
8d30: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
8d40: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
8d50: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
8d60: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
8d70: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
8d80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
8d90: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
8da0: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
8db0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
8dc0: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
8dd0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
8de0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
8df0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8e00: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
8e10: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
8e20: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
8e30: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
8e40: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
8e50: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
8e60: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
8e70: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
8e80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
8e90: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
8ea0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
8eb0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
8ec0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
8ed0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
8ee0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
8ef0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
8f00: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e   compiled for un
8f10: 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, windows, or 
8f20: 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75  os/2..** When bu
8f30: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
8f40: 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74  atforms (using t
8f50: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
8f60: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
8f70: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
8f80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
8f90: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
8fa0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
8fb0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
8fc0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
8fd0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
8fe0: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
8ff0: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
9000: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
9010: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
9020: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
9030: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
9040: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
9050: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
9060: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
9070: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
9080: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
9090: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
90a0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
90b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
90c0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
90d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
90e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
90f0: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
9100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
9110: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
9120: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31  Lite Library {H1
9130: 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53  4100} <S20000><S
9140: 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  30200>.** EXPERI
9150: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
9160: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
9170: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
9180: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
9190: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
91a0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
91b0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
91c0: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
91d0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
91e0: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
91f0: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
9200: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
9210: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
9220: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
9230: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
9240: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
9250: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
9260: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
9270: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
9280: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
9290: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
92a0: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
92b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
92c0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
92d0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
92e0: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
92f0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
9300: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
9310: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
9320: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
9330: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
9340: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
9350: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9360: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
9370: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
9380: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
9390: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
93a0: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
93b0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
93c0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
93d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
93e0: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
93f0: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
9400: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e  hutdown()]..** N
9410: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
9420: 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  at sqlite3_confi
9430: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
9440: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
9450: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
9460: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
9470: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
9480: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
9490: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
94a0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
94b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
94c0: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
94d0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
94e0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
94f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
9500: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
9510: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
9520: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
9530: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
9540: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
9550: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
9560: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
9570: 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
9580: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
9590: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
95a0: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
95b0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
95c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f  .**.** When a co
95d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
95e0: 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
95f0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
9600: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
9610: 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f  .** If the optio
9620: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
9630: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
9640: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
9650: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
9660: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
9670: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
9680: 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52  r code]..**.** R
9690: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
96a0: 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36  [H14103] [H14106
96b0: 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31  ] [H14120] [H141
96c0: 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31  23] [H14126] [H1
96d0: 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b  4129] [H14132] [
96e0: 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31  H14135].** [H141
96f0: 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31  38] [H14141] [H1
9700: 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b  4144] [H14147] [
9710: 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d  H14150] [H14153]
9720: 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35   [H14156] [H1415
9730: 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b  9].** [H14162] [
9740: 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d  H14165] [H14168]
9750: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
9760: 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
9770: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
9780: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
9790: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
97a0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
97b0: 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20  tions  {H14200} 
97c0: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20000>.** EXPE
97d0: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
97e0: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
97f0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
9800: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
9810: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
9820: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
9830: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9840: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
9850: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
9860: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
9870: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
9880: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
9890: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
98a0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
98b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
98c0: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
98d0: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
98e0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
98f0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
9900: 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  face can only be
9910: 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c   used immediatel
9920: 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64  y after.** the d
9930: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9940: 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73  on is created us
9950: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
9960: 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  n()],.** [sqlite
9970: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
9980: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
9990: 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
99a0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
99b0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
99c0: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
99d0: 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67  is the.** config
99e0: 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61  uration verb - a
99f0: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
9a00: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
9a10: 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20  at.** aspect of 
9a20: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
9a30: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
9a40: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
9a50: 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63  * The only choic
9a60: 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65  e for this value
9a70: 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f   is [SQLITE_DBCO
9a80: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e  NFIG_LOOKASIDE].
9a90: 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72  .** New verbs ar
9aa0: 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61  e likely to be a
9ab0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9ac0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
9ad0: 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  e..** Additional
9ae0: 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e   arguments depen
9af0: 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a  d on the verb..*
9b00: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
9b10: 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b  s:.** [H14203] [
9b20: 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d  H14206] [H14209]
9b30: 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31   [H14212] [H1421
9b40: 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  5].*/.SQLITE_EXP
9b50: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
9b60: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
9b70: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
9b80: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
9b90: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
9ba0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
9bb0: 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32  nes {H10155} <S2
9bc0: 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0120>.** EXPERIM
9bd0: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ENTAL.**.** An i
9be0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9bf0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
9c00: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
9c10: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
9c20: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
9c30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
9c40: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
9c50: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
9c60: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
9c70: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
9c80: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
9c90: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
9ca0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
9cb0: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
9cc0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
9cd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9ce0: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
9cf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
9d00: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
9d10: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42  NFIG_MALLOC].  B
9d20: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
9d30: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
9d40: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
9d50: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
9d60: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75  te3_config()] du
9d70: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
9d80: 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63  on, an.** applic
9d90: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
9da0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
9db0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
9dc0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  on subsystem.** 
9dd0: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
9de0: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
9df0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
9e00: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
9e10: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
9e20: 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c 74  mes with a built
9e30: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
9e40: 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20  ator that is.** 
9e50: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
9e60: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
9e70: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
9e80: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
9e90: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
9ea0: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
9eb0: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
9ec0: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
9ed0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
9ee0: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
9ef0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
9f00: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
9f10: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
9f20: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
9f30: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
9f40: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
9f50: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
9f60: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
9f70: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
9f80: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
9f90: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
9fa0: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
9fb0: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
9fc0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
9fd0: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
9fe0: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
9ff0: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
a000: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72  The xMalloc, xFr
a010: 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63  ee, and xRealloc
a020: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
a030: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
a040: 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c  alloc(), free(),
a050: 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66   and realloc() f
a060: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
a070: 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
a080: 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  ry..**.** xSize 
a090: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
a0a0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
a0b0: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
a0c0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
a0d0: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
a0e0: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
a0f0: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
a100: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
a110: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
a120: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
a130: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
a140: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
a150: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
a160: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
a170: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
a180: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
a190: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
a1a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
a1b0: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
a1c0: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
a1d0: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
a1e0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
a1f0: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
a200: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
a210: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
a220: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
a230: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
a240: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
a250: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
a260: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
a270: 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49   2..**.** The xI
a280: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
a290: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
a2a0: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
a2b0: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
a2c0: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
a2d0: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
a2e0: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
a2f0: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
a300: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
a310: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
a320: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
a330: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
a340: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
a350: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
a360: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
a370: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
a380: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
a390: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
a3a0: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
a3b0: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
a3c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
a3d0: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
a3e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a3f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
a400: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
a410: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
a420: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
a430: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
a440: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
a450: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
a460: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
a470: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
a480: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
a490: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
a4a0: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
a4b0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
a4c0: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
a4d0: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
a4e0: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
a4f0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
a500: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
a510: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
a520: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
a530: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
a540: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
a550: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
a560: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
a570: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
a580: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
a590: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
a5a0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
a5b0: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
a5c0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
a5d0: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
a5e0: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
a5f0: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
a600: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
a610: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
a620: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
a630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a640: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
a650: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
a660: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
a670: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
a680: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
a690: 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32  ons {H10160} <S2
a6a0: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0000>.** EXPERIM
a6b0: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
a6c0: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
a6d0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
a6e0: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
a6f0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
a700: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
a710: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
a720: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
a730: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a740: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
a750: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
a760: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
a770: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
a780: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
a790: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
a7a0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
a7b0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
a7c0: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
a7d0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
a7e0: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
a7f0: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
a800: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
a810: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
a820: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
a830: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
a840: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
a850: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
a860: 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
a870: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
a880: 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
a890: 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
a8a0: 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
a8b0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
a8c0: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
a8d0: 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
a8e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
a8f0: 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
a900: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
a910: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
a920: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
a930: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
a940: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
a950: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
a960: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
a970: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
a980: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
a990: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64  ingle thread.</d
a9a0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
a9b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
a9c0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
a9d0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
a9e0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
a9f0: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
aa00: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a  option disables.
aa10: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
aa20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
aa30: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
aa40: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
aa50: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
aa60: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
aa70: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
aa80: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
aa90: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
aaa0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
aab0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
aac0: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
aad0: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
aae0: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
aaf0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
ab00: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
ab10: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
ab20: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
ab30: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
ab40: 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
ab50: 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
ab60: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
ab70: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
ab80: 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65  e same time.  Se
ab90: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
aba0: 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65   mode].** docume
abb0: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
abc0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
abd0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
abe0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
abf0: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
ac00: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ac10: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
ac20: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
ac30: 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  This option enab
ac40: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
ac50: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
ac60: 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
ac70: 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
ac80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
ac90: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
aca0: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
acb0: 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
acc0: 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
acd0: 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
ace0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
acf0: 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
ad00: 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
ad10: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
ad20: 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
ad30: 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
ad40: 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
ad50: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
ad60: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ad70: 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
ad80: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
ad90: 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
ada0: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
adb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
adc0: 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
add0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ade0: 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
adf0: 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
ae00: 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20  me time..** See 
ae10: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
ae20: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ode] documentati
ae30: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
ae40: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f  l information.</
ae50: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
ae60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
ae70: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
ae80: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
ae90: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
aea0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
aeb0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
aec0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
aed0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
aee0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
aef0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
af00: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
af10: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
af20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
af30: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
af40: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
af50: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
af60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
af70: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
af80: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  SQLite.</dd>.**.
af90: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
afa0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
afb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
afc0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
afd0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
afe0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
aff0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
b000: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
b010: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
b020: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
b030: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b040: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
b050: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
b060: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
b070: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
b080: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
b090: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
b0a0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
b0b0: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
b0c0: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
b0d0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
b0e0: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
b0f0: 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
b100: 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
b110: 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
b120: 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
b130: 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
b140: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  xample.</dd>.**.
b150: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b160: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
b170: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
b180: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
b190: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
b1a0: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
b1b0: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
b1c0: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
b1d0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
b1e0: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
b1f0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
b200: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
b210: 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62  tics. When disab
b220: 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  led, the followi
b230: 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
b240: 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20  aces become .** 
b250: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
b260: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
b270: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
b280: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
b290: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b2a0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
b2b0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
b2c0: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
b2d0: 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c  _limit()].**   <
b2e0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
b2f0: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
b300: 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  >.** </dd>.**.**
b310: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b320: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
b330: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
b340: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
b350: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
b360: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
b370: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
b380: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
b390: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
b3a0: 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
b3b0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
b3c0: 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65  ory, the.** size
b3d0: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
b3e0: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
b3f0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
b400: 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20 54 68  buffers (N).  Th
b410: 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
b420: 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
b430: 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73  ple of 16. The s
b440: 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  z parameter shou
b450: 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65  ld be a few byte
b460: 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e  s.** larger than
b470: 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61   the actual scra
b480: 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72  tch space requir
b490: 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61 6c 20  ed due internal 
b4a0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
b4b0: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
b4c0: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
b4d0: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
b4e0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
b4f0: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
b500: 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  y..** SQLite wil
b510: 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
b520: 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
b530: 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65  uffer at once pe
b540: 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20  r thread, so.** 
b550: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
b560: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
b570: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b580: 66 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20  f threads.  The 
b590: 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  sz.** parameter 
b5a0: 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65  should be 6 time
b5b0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
b5c0: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
b5d0: 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
b5e0: 20 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73   Scratch buffers
b5f0: 20 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72   are used as par
b600: 74 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62  t of the btree b
b610: 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e  alance operation
b620: 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72  .  If.** The btr
b630: 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64  ee balancer need
b640: 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d  s additional mem
b650: 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
b660: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a  is provided by.*
b670: 2a 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  * scratch buffer
b680: 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74  s or if no scrat
b690: 63 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20  ch buffer space 
b6a0: 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
b6b0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65  en SQLite.** goe
b6c0: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
b6d0: 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69  lloc()] to obtai
b6e0: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20  n the memory it 
b6f0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
b700: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
b710: 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
b720: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
b730: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
b740: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
b750: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
b760: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
b770: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
b780: 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
b790: 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
b7a0: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74  cache implemenat
b7b0: 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
b7c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
b7d0: 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
b7e0: 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
b7f0: 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
b800: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
b810: 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
b820: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
b830: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f  _CONFIG_PCACHE o
b840: 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
b850: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
b860: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
b870: 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
b880: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20   the.** memory, 
b890: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
b8a0: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
b8b0: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
b8c0: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
b8d0: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
b8e0: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77  nt must be a pow
b8f0: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
b900: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e  n 512 and 32768.
b910: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
b920: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
b930: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
b940: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
b950: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
b960: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
b970: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
b980: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
b990: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
b9a0: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
b9b0: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
b9c0: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
b9d0: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
b9e0: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
b9f0: 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a    If additional.
ba00: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
ba10: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
ba20: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
ba30: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
ba40: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
ba50: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
ba60: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ba70: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
ba80: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
ba90: 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  e..** The implem
baa0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75  entation might u
bab0: 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  se one or more o
bac0: 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20  f the N buffers 
bad0: 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f  to hold .** memo
bae0: 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e  ry accounting in
baf0: 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e  formation. </dd>
bb00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bb10: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
bb20: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
bb30: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
bb40: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
bb50: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
bb60: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
bb70: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
bb80: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
bb90: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
bba0: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
bbb0: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
bbc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
bbd0: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
bbe0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
bbf0: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
bc00: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
bc10: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
bc20: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  the memory, the 
bc30: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
bc40: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
bc50: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
bc60: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
bc70: 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a  ion size.  If.**
bc80: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
bc90: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
bca0: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
bcb0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
bcc0: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
bcd0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
bce0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
bcf0: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
bd00: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
bd10: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
bd20: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
bd30: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
bd40: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
bd50: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
bd60: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
bd70: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
bd80: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
bd90: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
bda0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
bdb0: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
bdc0: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
bdd0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
bde0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
bdf0: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
be00: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
be10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
be20: 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a  n needs.</dd>.**
be30: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
be40: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
be50: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
be60: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
be70: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
be80: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
be90: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
bea0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
beb0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
bec0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
bed0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
bee0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
bef0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
bf00: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
bf10: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
bf20: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
bf30: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
bf40: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  SQLite.</dd>.**.
bf50: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bf60: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
bf70: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
bf80: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
bf90: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
bfa0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
bfb0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
bfc0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
bfd0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
bfe0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
bff0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
c000: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
c010: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
c020: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
c030: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
c040: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  utex routines..*
c050: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
c060: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
c070: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
c080: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
c090: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
c0a0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
c0b0: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
c0c0: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
c0d0: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
c0e0: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
c0f0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
c100: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c110: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
c120: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
c130: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c140: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
c150: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
c160: 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
c170: 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20  emory allcation 
c180: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
c190: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
c1a0: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
c1b0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c1c0: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
c1d0: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
c1e0: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
c1f0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
c200: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
c210: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
c220: 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  nection.</dd>.**
c230: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c240: 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74  ONFIG_PCACHE</dt
c250: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
c260: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
c270: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
c280: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
c290: 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
c2a0: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
c2b0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
c2c0: 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
c2d0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
c2e0: 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
c2f0: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
c300: 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65  ntation.  SQLite
c310: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
c320: 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
c330: 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
c340: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
c350: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
c360: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c370: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
c380: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
c390: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c3a0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
c3b0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
c3c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
c3d0: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
c3e0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
c3f0: 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
c400: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
c410: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
c420: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
c430: 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f  o that object.</
c440: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
c450: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c460: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c470: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
c480: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c490: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
c4a0: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
c4b0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
c4c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
c4d0: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
c4e0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
c4f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
c500: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
c510: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c520: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c530: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
c540: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
c550: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
c560: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
c570: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c580: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
c590: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
c5a0: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
c5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c5c0: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
c5d0: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
c5e0: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
c5f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c600: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
c610: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
c620: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
c630: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
c640: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
c650: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
c660: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
c670: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c680: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
c690: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
c6a0: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
c6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c6c0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
c6d0: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
c6e0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
c6f0: 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
c700: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
c710: 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
c720: 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
c730: 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
c740: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
c750: 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
c760: 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
c770: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c780: 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
c790: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
c7a0: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
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 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
c7d0: 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
c7e0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
c7f0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
c800: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
c810: 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31  on Options {H101
c820: 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  70} <S20000>.** 
c830: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
c840: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
c850: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
c860: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
c870: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c880: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
c890: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
c8a0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
c8b0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c8c0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
c8d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
c8e0: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
c8f0: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
c900: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
c910: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
c920: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
c930: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c940: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
c950: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
c960: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
c970: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
c980: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
c990: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c9a0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
c9b0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
c9c0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
c9d0: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c9e0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
c9f0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
ca00: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
ca10: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
ca20: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
ca30: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
ca40: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
ca50: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
ca60: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
ca70: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
ca80: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
ca90: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
caa0: 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
cab0: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
cac0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
cad0: 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
cae0: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
caf0: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
cb00: 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
cb10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cb20: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
cb30: 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
cb40: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
cb50: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
cb60: 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
cb70: 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
cb80: 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
cb90: 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
cba0: 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 72 73 74  mory.  The first
cbb0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  .** argument may
cbc0: 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
cbd0: 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
cbe0: 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ll allocate the 
cbf0: 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66  lookaside.** buf
cc00: 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
cc10: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
cc20: 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ()].  The second
cc30: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
cc40: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
cc50: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
cc60: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74  r slot and the t
cc70: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
cc80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
cc90: 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
cca0: 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
ccb0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ccc0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
ccd0: 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
cce0: 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
ccf0: 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
cd00: 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
cd10: 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a  rguments.</dd>.*
cd20: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
cd30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
cd40: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
cd50: 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
cd60: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f  * int int */.../
cd70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
cd80: 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
cd90: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
cda0: 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20   Codes {H12200} 
cdb0: 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
cdc0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
cdd0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
cde0: 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
cdf0: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
ce00: 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
ce10: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
ce20: 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
ce30: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
ce40: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
ce50: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
ce60: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
ce70: 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
ce80: 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e  ty consideration
ce90: 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
cea0: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30  ments:.** [H1220
ceb0: 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 69  1] [H12202].*/.i
cec0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
ced0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
cee0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
cef0: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
cf00: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
cf10: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32  ert Rowid {H1222
cf20: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
cf30: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
cf40: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
cf50: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
cf60: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
cf70: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
cf80: 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
cf90: 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 69  owid"]. The rowi
cfa0: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
cfb0: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
cfc0: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
cfd0: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
cfe0: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
cff0: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
d000: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
d010: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
d020: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
d030: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20   columns. If.** 
d040: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
d050: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
d060: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
d070: 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
d080: 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
d090: 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
d0a0: 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54  e rowid..**.** T
d0b0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
d0c0: 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
d0d0: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
d0e0: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
d0f0: 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
d100: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
d110: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
d120: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
d130: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
d140: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63  ent.  If no succ
d150: 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
d160: 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
d170: 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
d180: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d190: 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
d1a0: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rned..**.** If a
d1b0: 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
d1c0: 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
d1d0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f  er, then the [ro
d1e0: 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
d1f0: 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72  rted.** row is r
d200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
d210: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
d220: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
d230: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
d240: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
d250: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74  er terminates, t
d260: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d270: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
d280: 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20  e.** reverts to 
d290: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69  the last value i
d2a0: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74  nserted before t
d2b0: 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64  he trigger fired
d2c0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45  ..**.** An [INSE
d2d0: 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
d2e0: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
d2f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
d300: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
d310: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
d320: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
d330: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
d340: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
d350: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
d360: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
d370: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
d380: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
d390: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
d3a0: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
d3b0: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
d3c0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
d3d0: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
d3e0: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
d3f0: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
d400: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
d410: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
d420: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
d430: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
d440: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
d450: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
d460: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
d470: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
d480: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
d490: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
d4a0: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
d4b0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
d4c0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
d4d0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
d4e0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
d4f0: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
d500: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
d510: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
d520: 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
d530: 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
d540: 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
d550: 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
d560: 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
d570: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
d580: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
d590: 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 32  ** [H12221] [H12
d5a0: 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  223].**.** If a 
d5b0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
d5c0: 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
d5d0: 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
d5e0: 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
d5f0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
d600: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
d610: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
d620: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
d630: 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
d640: 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
d650: 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
d660: 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
d670: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
d680: 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
d690: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
d6a0: 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
d6b0: 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
d6c0: 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
d6d0: 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
d6e0: 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
d6f0: 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
d700: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
d710: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
d720: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
d730: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d740: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
d750: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
d760: 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30  ed {H12240} <S10
d770: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
d780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
d790: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
d7a0: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
d7b0: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
d7c0: 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
d7d0: 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
d7e0: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
d7f0: 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
d800: 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
d810: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d820: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
d830: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
d840: 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20  ameter..** Only 
d850: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
d860: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
d870: 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
d880: 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
d890: 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
d8a0: 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
d8b0: 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
d8c0: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
d8d0: 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72  y.** triggers ar
d8e0: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55  e not counted. U
d8f0: 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
d900: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
d910: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20   function.** to 
d920: 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
d930: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
d940: 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
d950: 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
d960: 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22  ggers..**.** A "
d970: 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
d980: 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
d990: 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
d9a0: 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
d9b0: 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
d9c0: 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
d9d0: 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
d9e0: 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
d9f0: 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
da00: 20 65 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c   effects of REPL
da10: 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  ACE constraint r
da20: 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
da30: 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
da40: 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54  ocessing, DROP T
da50: 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20  ABLE, or by any 
da60: 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
da70: 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
da80: 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
da90: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  hanges..**.** A 
daa0: 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
dab0: 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
dac0: 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
dad0: 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
dae0: 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
daf0: 74 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20  t of a trigger. 
db00: 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
db10: 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
db20: 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
db30: 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
db40: 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
db50: 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
db60: 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
db70: 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
db80: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
db90: 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
dba0: 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
dbb0: 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
dbc0: 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
dbd0: 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
dbe0: 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
dbf0: 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
dc00: 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
dc10: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  on..**.** Callin
dc20: 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
dc30: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
dc40: 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
dc50: 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
dc60: 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
dc70: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
dc80: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
dc90: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
dca0: 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
dcb0: 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
dcc0: 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
dcd0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
dce0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
dcf0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
dd00: 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
dd10: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ontext..**.** Th
dd20: 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
dd30: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
dd40: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
dd50: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
dd60: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
dd70: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
dd80: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
dd90: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
dda0: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
ddb0: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
ddc0: 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20   level.  Within 
ddd0: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
dde0: 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
ddf0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
de00: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
de10: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
de20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
de30: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
de40: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
de50: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
de60: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
de70: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
de80: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
de90: 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
dea0: 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
deb0: 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
dec0: 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
ded0: 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
dee0: 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
def0: 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
df00: 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
df10: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
df20: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
df30: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
df40: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
df50: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
df60: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
df70: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
df80: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
df90: 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d  .  Doing so is m
dfa0: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
dfb0: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
dfc0: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
dfd0: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
dfe0: 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65  s from the table
dff0: 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
e000: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
e010: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
e020: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
e030: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
e040: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
e050: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
e060: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
e070: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e080: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
e090: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
e0a0: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
e0b0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
e0c0: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
e0d0: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
e0e0: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
e0f0: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
e100: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
e110: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e120: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
e130: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
e140: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
e150: 31 22 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20  1" instead.  Or 
e160: 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20  recompile using 
e170: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
e180: 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54  MIT_TRUNCATE_OPT
e190: 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69  IMIZATION] compi
e1a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
e1b0: 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a  o disable the.**
e1c0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e   optimization on
e1d0: 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a   all queries..**
e1e0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
e1f0: 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48  :.** [H12241] [H
e200: 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  12243].**.** If 
e210: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
e220: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
e230: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
e240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
e250: 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
e260: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
e270: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
e280: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
e290: 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
e2a0: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
e2b0: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
e2c0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
e2d0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
e2e0: 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
e2f0: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
e300: 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30  Modified {H12260
e310: 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
e320: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
e330: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
e340: 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
e350: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
e360: 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
e370: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
e380: 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
e390: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e3a0: 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
e3b0: 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
e3c0: 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
e3d0: 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
e3e0: 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
e3f0: 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
e400: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
e410: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
e420: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
e430: 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
e440: 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
e450: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
e460: 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
e470: 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
e480: 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
e490: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
e4a0: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
e4b0: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
e4c0: 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
e4d0: 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
e4e0: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
e4f0: 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
e500: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
e510: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
e520: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
e530: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
e540: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
e550: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e560: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
e570: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
e580: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
e590: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
e5a0: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
e5b0: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
e5c0: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
e5d0: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
e5e0: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
e5f0: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
e600: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
e610: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
e620: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
e630: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
e640: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
e650: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
e660: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
e670: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
e680: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e690: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
e6a0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
e6b0: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
e6c0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
e6d0: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
e6e0: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
e6f0: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
e700: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
e710: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
e720: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e730: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
e740: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
e750: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
e760: 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72  1" instead.   Or
e770: 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67   recompile using
e780: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
e790: 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50  OMIT_TRUNCATE_OP
e7a0: 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70  TIMIZATION] comp
e7b0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
e7c0: 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a  to disable the.*
e7d0: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f  * optimization o
e7e0: 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a  n all queries..*
e7f0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
e800: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
e810: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
e820: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
e830: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d  nts:.** [H12261]
e840: 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20   [H12263].**.** 
e850: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
e860: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
e870: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
e880: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e890: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
e8a0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e8b0: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
e8c0: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
e8d0: 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
e8e0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
e8f0: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
e900: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e910: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
e920: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
e930: 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
e940: 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
e950: 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30  ng Query {H12270
e960: 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30500>.**.**
e970: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63   This function c
e980: 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
e990: 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
e9a0: 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
e9b0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
e9c0: 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
e9d0: 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
e9e0: 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
e9f0: 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
ea00: 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
ea10: 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
ea20: 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
ea30: 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
ea40: 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
ea50: 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
ea60: 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
ea70: 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
ea80: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ely..**.** It is
ea90: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
eaa0: 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
eab0: 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
eac0: 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
ead0: 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
eae0: 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
eaf0: 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
eb00: 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
eb10: 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
eb20: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
eb30: 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
eb40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
eb50: 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
eb60: 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
eb70: 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
eb80: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
eb90: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  urns..**.** If a
eba0: 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
ebb0: 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
ebc0: 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
ebd0: 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
ebe0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
ebf0: 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
ec00: 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
ec10: 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
ec20: 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
ec30: 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
ec40: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
ec50: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e  letion..**.** An
ec60: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
ec70: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
ec80: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
ec90: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
eca0: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
ecb0: 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
ecc0: 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
ecd0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
ece0: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
ecf0: 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
ed00: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
ed10: 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
ed20: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
ed30: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
ed40: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
ed50: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  ly..**.** A call
ed60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
ed70: 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65  rrupt() has no e
ed80: 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
ed90: 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
eda0: 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
edb0: 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  r sqlite3_interr
edc0: 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
edd0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
ede0: 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b  s:.** [H12271] [
edf0: 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12272].**.** If
ee00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
ee10: 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
ee20: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
ee30: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
ee40: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
ee50: 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
ee60: 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
ee70: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
ee80: 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
ee90: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
eea0: 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
eeb0: 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
eec0: 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48  t Is Complete {H
eed0: 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a  10510} <S70200>.
eee0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
eef0: 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
ef00: 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  for command-line
ef10: 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
ef20: 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
ef30: 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
ef40: 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
ef50: 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51  rm complete a SQ
ef60: 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
ef70: 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
ef80: 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
ef90: 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
efa0: 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
efb0: 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
efc0: 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ng.  These routi
efd0: 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  nes return true 
efe0: 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
eff0: 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
f000: 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
f010: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
f020: 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
f030: 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
f040: 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
f050: 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
f060: 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
f070: 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20   not a fragment 
f080: 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54  of a.** CREATE T
f090: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
f0a0: 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68  .  Semicolons th
f0b0: 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
f0c0: 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
f0d0: 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
f0e0: 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
f0f0: 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
f100: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
f110: 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
f120: 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
f130: 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
f140: 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
f150: 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
f160: 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
f170: 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
f180: 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
f190: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
f1a0: 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
f1b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
f1c0: 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
f1d0: 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
f1e0: 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
f1f0: 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  SQL..**.** Requi
f200: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31  rements: [H10511
f210: 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a  ] [H10512].**.**
f220: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
f230: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
f240: 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
f250: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
f260: 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
f270: 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
f280: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
f290: 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
f2a0: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
f2b0: 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
f2c0: 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
f2d0: 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
f2e0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f2f0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
f300: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
f310: 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
f320: 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
f330: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
f340: 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
f350: 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
f360: 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48  E_BUSY Errors {H
f370: 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a  12310} <S40400>.
f380: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
f390: 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
f3a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
f3b0: 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
f3c0: 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
f3d0: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
f3e0: 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
f3f0: 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
f400: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
f410: 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
f420: 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  locked..**.** If
f430: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
f440: 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
f450: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
f460: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
f470: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
f480: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
f490: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
f4a0: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
f4b0: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
f4c0: 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
f4d0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
f4e0: 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
f4f0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
f500: 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
f510: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f520: 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
f530: 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
f540: 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
f550: 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
f560: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
f570: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
f580: 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65  _handler().  The
f590: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f5a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
f5b0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
f5c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
f5d0: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
f5e0: 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
f5f0: 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
f600: 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
f610: 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ent.  If the.** 
f620: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
f630: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
f640: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
f650: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
f660: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
f670: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
f680: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
f690: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
f6a0: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
f6b0: 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
f6c0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
f6d0: 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
f6e0: 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
f6f0: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
f700: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
f710: 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
f720: 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
f730: 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
f740: 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
f750: 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
f760: 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
f770: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
f780: 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
f790: 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
f7a0: 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
f7b0: 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
f7c0: 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
f7d0: 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
f7e0: 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
f7f0: 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
f800: 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
f810: 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
f820: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
f830: 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
f840: 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
f850: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
f860: 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
f870: 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
f880: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
f890: 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
f8a0: 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
f8b0: 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
f8c0: 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
f8d0: 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
f8e0: 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
f8f0: 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
f900: 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
f910: 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
f920: 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
f930: 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
f940: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
f950: 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
f960: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
f970: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
f980: 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
f990: 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
f9a0: 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
f9b0: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
f9c0: 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
f9d0: 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
f9e0: 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
f9f0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
fa00: 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
fa10: 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
fa20: 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
fa30: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
fa40: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
fa50: 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
fa60: 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
fa70: 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
fa80: 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
fa90: 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
faa0: 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
fab0: 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
fac0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
fad0: 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
fae0: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
faf0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
fb00: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
fb10: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
fb20: 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
fb30: 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
fb40: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
fb50: 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
fb60: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
fb70: 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
fb80: 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
fb90: 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
fba0: 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
fbb0: 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
fbc0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
fbd0: 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
fbe0: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
fbf0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
fc00: 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
fc10: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
fc20: 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
fc30: 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
fc40: 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
fc50: 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
fc60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
fc70: 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
fc80: 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
fc90: 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
fca0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
fcb0: 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
fcc0: 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
fcd0: 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
fce0: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
fcf0: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
fd00: 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
fd10: 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
fd20: 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
fd30: 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
fd40: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
fd50: 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
fd60: 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
fd70: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
fd80: 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
fd90: 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
fda0: 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
fdb0: 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
fdc0: 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
fdd0: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
fde0: 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
fdf0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
fe00: 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
fe10: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
fe20: 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
fe30: 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
fe40: 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
fe50: 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
fe60: 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rtant..**.** The
fe70: 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
fe80: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
fe90: 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
fea0: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
feb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
fec0: 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
fed0: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
fee0: 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
fef0: 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
ff00: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  .  Note that cal
ff10: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
ff20: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
ff30: 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
ff40: 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
ff50: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
ff60: 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
ff70: 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
ff80: 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
ff90: 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
ffa0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
ffb0: 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
ffc0: 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
ffd0: 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
ffe0: 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
fff0: 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
10000 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52  havior..** .** R
10010 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
10020 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32  [H12311] [H12312
10030 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33  ] [H12314] [H123
10040 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a  16] [H12318].**.
10050 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
10060 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
10070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
10080 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
10090 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
100a0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
100b0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
100c0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
100d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
100e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
100f0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
10100 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
10110 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
10120 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
10130 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
10140 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
10150 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
10160 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
10170 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
10180 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
10190 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
101a0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
101b0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
101c0 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
101d0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
101e0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
101f0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
10200 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
10210 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
10220 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32  ccumulated. {H12
10230 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
10240 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
10250 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
10260 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
10270 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
10280 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
10290 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
102a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
102b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
102c0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
102d0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
102e0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
102f0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
10300 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
10310 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
10320 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
10330 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
10340 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
10350 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10360 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
10370 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10380 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
10390 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
103a0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
103b0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
103c0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
103d0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
103e0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
103f0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
10400 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
10410 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
10420 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
10430 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
10440 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32  ** [H12341] [H12
10450 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f  343] [H12344].*/
10460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
10470 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
10480 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
10490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
104a0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
104b0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
104c0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
104d0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
104e0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
104f0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
10500 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
10510 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
10520 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
10530 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
10540 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
10550 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
10560 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
10570 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
10580 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
10590 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
105a0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
105b0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
105c0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
105d0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
105e0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
105f0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
10600 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
10610 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
10620 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
10630 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
10640 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
10650 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
10660 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
10670 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
10680 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
10690 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
106a0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
106b0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
106c0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
106d0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
106e0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
106f0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
10700 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
10710 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
10720 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
10730 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
10740 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
10750 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
10760 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
10770 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
10780 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
10790 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
107a0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
107b0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
107c0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
107d0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
107e0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
107f0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
10800 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
10810 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
10820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
10830 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
10840 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
10850 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
10860 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
10870 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
10880 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
10890 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
108a0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
108b0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
108c0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
108d0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
108e0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
108f0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
10900 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
10910 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
10920 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
10930 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
10940 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
10950 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
10960 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
10970 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
10980 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
10990 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
109a0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
109b0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
109c0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
109d0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
109e0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
109f0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
10a00 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
10a10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
10a20 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
10a30 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
10a40 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
10a50 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
10a60 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
10a70 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
10a80 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
10a90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
10aa0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
10ab0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
10ac0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
10ad0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
10ae0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
10af0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
10b00 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
10b10 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
10b20 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
10b30 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
10b40 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
10b50 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
10b60 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
10b70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
10b80 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
10b90 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10ba0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
10bb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
10bc0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
10bd0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
10be0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
10bf0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
10c00 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
10c10 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
10c20 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
10c30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
10c40 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
10c50 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
10c60 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
10c70 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
10c80 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
10c90 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
10ca0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
10cb0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
10cc0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
10cd0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
10ce0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
10cf0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
10d00 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
10d10 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
10d20 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
10d30 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
10d40 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
10d50 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
10d60 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
10d70 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
10d80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
10d90 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
10da0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
10db0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
10dc0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
10dd0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
10de0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
10df0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
10e00 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
10e10 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
10e20 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
10e30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
10e40 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
10e50 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
10e60 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
10e70 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
10e80 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
10e90 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
10ea0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
10eb0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
10ec0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
10ed0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
10ee0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
10ef0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
10f00 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
10f10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
10f20 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
10f30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
10f40 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
10f50 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
10f60 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
10f70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
10f80 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
10f90 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
10fa0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
10fb0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
10fc0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
10fd0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
10fe0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
10ff0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
11000 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
11010 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
11020 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
11030 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
11040 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
11050 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
11060 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
11070 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
11080 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
11090 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d  nts:.** [H12371]
110a0 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37   [H12373] [H1237
110b0 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32  4] [H12376] [H12
110c0 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f  379] [H12382].*/
110d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
110e0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
110f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
11100 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
11110 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
11120 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
11130 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
11140 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
11150 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
11160 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
11170 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
11180 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
11190 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
111a0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
111b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
111c0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
111d0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
111e0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
111f0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
11200 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
11210 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
11220 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
11230 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
11240 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
11250 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
11260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11270 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
11280 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
11290 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c  tions {H17400} <
112a0 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a  S70000><S20000>.
112b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
112c0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69  ines are workali
112d0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
112e0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
112f0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
11300 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
11310 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
11320 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
11330 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
11340 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
11350 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
11360 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
11370 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
11380 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
11390 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
113a0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
113b0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
113c0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
113d0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
113e0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
113f0 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e  )].  Both routin
11400 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
11410 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
11420 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11430 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
11440 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
11450 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
11460 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
11470 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  tring..**.** In 
11480 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
11490 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
114a0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
114b0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
114c0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
114d0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
114e0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
114f0 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
11500 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
11510 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
11520 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
11530 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
11540 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
11550 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
11560 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
11570 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
11580 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
11590 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
115a0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
115b0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
115c0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
115d0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
115e0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
115f0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
11600 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ity.  Note also 
11610 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
11620 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
11630 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
11640 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
11650 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
11660 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
11670 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
11680 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
11690 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68  er.  We admit th
116a0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
116b0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
116c0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
116d0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
116e0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
116f0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
11700 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
11710 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
11720 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
11730 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
11740 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
11750 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  y..**.** As long
11760 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
11770 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
11780 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
11790 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
117a0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
117b0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
117c0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
117d0 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74  ated.  The first
117e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
117f0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
11800 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
11810 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
11820 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
11830 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
11840 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
11850 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
11860 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
11870 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
11880 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
11890 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
118a0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
118b0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
118c0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
118d0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
118e0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
118f0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
11900 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
11910 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
11920 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
11930 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
11940 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
11950 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
11960 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
11970 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
11980 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e  ** The %q option
11990 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
119a0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
119b0 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
119c0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
119d0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
119e0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
119f0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
11a00 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
11a10 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
11a20 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
11a30 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
11a40 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62  iteral.  By doub
11a50 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
11a60 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
11a70 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
11a80 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
11a90 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
11aa0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
11ab0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
11ac0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
11ad0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
11ae0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
11af0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
11b00 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
11b10 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
11b20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
11b30 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
11b40 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
11b50 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
11b60 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
11b70 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
11b80 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
11b90 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
11ba0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11bb0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
11bc0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
11bd0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
11be0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
11bf0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
11c00 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
11c10 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
11c20 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
11c30 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
11c40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
11c50 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
11c60 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
11c70 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
11c80 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
11c90 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
11ca0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
11cb0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
11cc0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
11cd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
11ce0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
11cf0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
11d00 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
11d10 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
11d20 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
11d30 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
11d40 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
11d50 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
11d60 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
11d70 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
11d80 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
11d90 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
11da0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
11db0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
11dc0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
11dd0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
11de0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
11df0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
11e00 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
11e10 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
11e20 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
11e30 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
11e40 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
11e50 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
11e60 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
11e70 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
11e80 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
11e90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70  .**.** The %Q op
11ea0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
11eb0 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
11ec0 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
11ed0 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
11ee0 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
11ef0 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
11f00 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
11f10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
11f20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
11f30 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
11f40 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
11f50 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
11f60 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
11f70 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
11f80 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66  tes) in place of
11f90 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20   the %Q option. 
11fa0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
11fb0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
11fc0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
11fd0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
11fe0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
11ff0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
12000 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
12010 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
12020 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
12030 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
12040 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
12050 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
12060 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
12070 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
12080 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
12090 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
120a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
120b0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
120c0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
120d0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
120e0 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
120f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
12100 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
12110 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
12120 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
12130 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
12140 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
12150 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
12160 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
12170 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
12180 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
12190 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
121a0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
121b0 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ring. {END}.**.*
121c0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
121d0 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 31 37  ** [H17403] [H17
121e0 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a 2f  406] [H17407].*/
121f0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
12200 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
12210 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
12220 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
12230 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
12240 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
12250 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
12260 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
12270 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
12280 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
12290 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
122a0 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d  bsystem {H17300}
122b0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
122c0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
122d0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
122e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
122f0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
12300 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
12310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12320 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
12330 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
12340 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
12350 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
12360 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
12370 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
12380 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
12390 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
123a0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
123b0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
123c0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
123d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
123e0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
123f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
12400 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
12410 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
12420 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
12430 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
12440 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
12450 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
12460 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
12470 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
12480 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
12490 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
124a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
124b0 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  .  If the parame
124c0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
124d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
124e0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
124f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
12500 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
12510 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
12520 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
12530 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
12540 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
12550 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
12560 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
12570 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
12580 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
12590 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
125a0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
125b0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
125c0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  .  The sqlite3_f
125d0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
125e0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
125f0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
12600 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
12610 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
12620 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
12630 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
12640 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
12650 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
12660 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
12670 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
12680 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
12690 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
126a0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
126b0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
126c0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
126d0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
126e0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
126f0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
12700 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
12710 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
12720 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
12730 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
12740 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
12750 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
12760 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
12770 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
12780 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
12790 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
127a0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
127b0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
127c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
127d0 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
127e0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
127f0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
12800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12810 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
12820 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
12830 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
12840 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
12850 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12860 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
12870 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
12880 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20   parameter.  If 
12890 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
128a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
128b0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
128c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
128d0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
128e0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
128f0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
12900 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
12910 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
12920 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
12930 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12940 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63  )..** If the sec
12950 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
12960 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
12970 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
12980 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
12990 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
129a0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
129b0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
129c0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
129d0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
129e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
129f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12a00 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  )..** sqlite3_re
12a10 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
12a20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
12a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12a40 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
12a50 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
12a60 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
12a70 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
12a80 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
12a90 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
12aa0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
12ab0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
12ac0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
12ad0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
12ae0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
12af0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
12b00 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
12b10 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
12b20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12b30 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
12b40 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
12b50 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  eed..** If sqlit
12b60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
12b70 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
12b80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
12b90 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
12ba0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  reed..**.** The 
12bb0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
12bc0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
12bd0 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
12be0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
12bf0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
12c00 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
12c10 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b  byte boundary. {
12c20 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  END}.**.** The d
12c30 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74  efault implement
12c40 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d  ation of the mem
12c50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12c60 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a  ubsystem uses.**
12c70 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72   the malloc(), r
12c80 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
12c90 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20  e() provided by 
12ca0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
12cb0 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33  ibrary..** {H173
12cc0 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20  82} However, if 
12cd0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12ce0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12cf0 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a  QLITE_MEMORY_SIZ
12d00 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70  E=<i>NNN</i> C p
12d10 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
12d20 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c  o (where <i>NNN<
12d30 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  /i>.** is an int
12d40 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69  eger), then SQLi
12d50 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74  te create a stat
12d60 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c  ic array of at l
12d70 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f  east.** <i>NNN</
12d80 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  i> bytes in size
12d90 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61   and uses that a
12da0 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20  rray for all of 
12db0 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d  its dynamic.** m
12dc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12dd0 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41   needs. {END}  A
12de0 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
12df0 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f   allocator optio
12e00 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64  ns.** may be add
12e10 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12e20 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  eases..**.** In 
12e30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
12e40 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
12e50 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
12e60 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
12e70 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
12e80 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
12e90 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
12ea0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
12eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12ec0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
12ed0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
12ee0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
12ef0 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
12f00 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
12f10 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
12f20 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
12f30 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
12f40 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
12f50 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
12f60 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
12f70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
12f80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
12f90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
12fa0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
12fb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
12fc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
12fd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
12fe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
12ff0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
13000 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
13010 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
13020 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
13030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
13040 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
13050 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
13060 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
13070 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
13080 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
13090 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
130a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
130b0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  NOMEM]..**.** Re
130c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
130d0 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30 34 5d  H17303] [H17304]
130e0 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37 33 30   [H17305] [H1730
130f0 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48 31 37  6] [H17310] [H17
13100 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b 48  312] [H17315] [H
13110 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33 32  17318].** [H1732
13120 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48 31 37  1] [H17322] [H17
13130 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  323].**.** The p
13140 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
13150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
13160 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
13170 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
13180 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
13190 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
131a0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
131b0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
131c0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
131d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
131e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
131f0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
13200 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
13210 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
13220 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13230 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
13240 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
13250 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
13260 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
13270 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
13280 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
13290 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
132a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
132b0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
132c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
132d0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
132e0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
132f0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
13300 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
13310 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13320 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
13330 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48 31  r Statistics {H1
13340 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a  7370} <S30210>.*
13350 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
13360 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
13370 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
13380 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
13390 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
133a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
133b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
133c0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
133d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
133e0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
133f0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
13400 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
13410 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
13420 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
13430 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20  ts:.** [H17371] 
13440 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37 34  [H17373] [H17374
13450 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73 71  ] [H17375].*/.sq
13460 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
13470 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
13480 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
13490 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
134a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
134b0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
134c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
134d0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
134e0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48  ber Generator {H
134f0 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17390} <S20000>.
13500 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
13510 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
13520 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
13530 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
13540 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
13550 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
13560 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
13570 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
13580 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
13590 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
135a0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
135b0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
135c0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
135d0 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
135e0 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
135f0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
13600 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
13610 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
13620 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
13630 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
13640 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
13650 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
13660 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
13670 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  poses..**.** A c
13680 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
13690 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
136a0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
136b0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
136c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
136d0 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
136e0 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
136f0 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
13700 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
13710 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
13720 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
13730 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
13740 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
13750 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
13760 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
13770 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
13780 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e  s] object..** On
13790 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
137a0 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
137b0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
137c0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
137d0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
137e0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
137f0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
13800 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
13810 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
13820 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
13830 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a 2a  s:.** [H17392].*
13840 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
13850 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
13860 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
13870 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
13880 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
13890 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
138a0 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30   {H12500} <S7010
138b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
138c0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
138d0 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  a authorizer cal
138e0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
138f0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
13900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13910 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
13920 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13930 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
13940 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
13950 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
13960 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
13970 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
13980 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
13990 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
139a0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
139b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
139c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
139d0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
139e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
139f0 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75  2()].  At variou
13a00 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
13a10 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
13a20 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
13a30 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
13a40 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
13a50 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
13a60 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
13a70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
13a80 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
13a90 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
13aa0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
13ab0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
13ac0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
13ad0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
13ae0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
13af0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
13b00 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
13b10 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
13b20 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
13b30 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
13b40 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
13b50 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
13b60 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
13b70 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
13b80 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
13b90 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
13ba0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
13bb0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66  th an error.  If
13bc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
13bd0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
13be0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
13bf0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
13c00 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
13c10 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
13c20 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
13c30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
13c40 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
13c50 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
13c60 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
13c70 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
13c80 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
13c90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
13ca0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
13cb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
13cc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
13cd0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
13ce0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
13cf0 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20  ed is ok.  When 
13d00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
13d10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
13d20 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
13d30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
13d40 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
13d50 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
13d60 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
13d70 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
13d80 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
13d90 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
13da0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
13db0 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74  is denied.  If t
13dc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
13dd0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
13de0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
13df0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
13e00 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
13e10 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
13e20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13e30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
13e40 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
13e50 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
13e60 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
13e70 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
13e80 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
13e90 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
13ea0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
13eb0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
13ec0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
13ed0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
13ee0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
13ef0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
13f00 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
13f10 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
13f20 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
13f30 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ble..**.** The f
13f40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13f50 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
13f60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
13f70 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
13f80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
13f90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
13fa0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
13fb0 74 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63  terface. The sec
13fc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
13fd0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
13fe0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
13ff0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
14000 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
14010 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
14020 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
14030 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
14040 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74  zed. The third t
14050 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
14060 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
14070 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
14080 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
14090 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
140a0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
140b0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
140c0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
140d0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
140e0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
140f0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
14100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
14110 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
14120 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
14130 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
14140 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
14150 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
14160 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
14170 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
14180 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
14190 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
141a0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
141b0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
141c0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
141d0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
141e0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
141f0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
14200 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
14210 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
14220 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
14230 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
14240 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
14250 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
14260 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
14270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
14280 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
14290 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
142a0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
142b0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
142c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
142d0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
142e0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
142f0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
14300 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
14310 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
14320 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
14330 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
14340 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
14350 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
14360 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
14370 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
14380 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
14390 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
143a0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
143b0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
143c0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
143d0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
143e0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
143f0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
14400 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
14410 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
14420 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
14430 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
14440 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
14450 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
14460 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
14470 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
14480 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
14490 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
144a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
144b0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
144c0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
144d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
144e0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
144f0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
14500 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65  s call.  Disable
14510 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14520 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
14530 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
14540 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
14550 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
14560 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
14570 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
14580 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
14590 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
145a0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
145b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
145c0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
145d0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
145e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
145f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
14600 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14610 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
14620 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
14630 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
14640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
14650 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
14660 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
14670 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
14680 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69  **.** When [sqli
14690 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
146a0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
146b0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
146c0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
146d0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 70 72  nt might be repr
146e0 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
146f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
14700 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
14710 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
14720 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
14730 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
14740 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
14750 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
14760 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
14770 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
14780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
14790 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ep()]..**.** Not
147a0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
147b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
147c0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
147d0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
147e0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
147f0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
14800 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
14810 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
14820 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
14830 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
14840 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14850 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
14860 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31  ents:.** [H12501
14870 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31 32 35  ] [H12502] [H125
14880 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48 31  03] [H12504] [H1
14890 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b  2505] [H12506] [
148a0 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31 30 5d  H12507] [H12510]
148b0 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48 31  .** [H12511] [H1
148c0 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b  2512] [H12520] [
148d0 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32 32 5d  H12521] [H12522]
148e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
148f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
14900 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
14910 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
14920 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
14930 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
14940 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
14950 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
14960 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
14970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
14980 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
14990 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48  odes {H12590} <H
149a0 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
149b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
149c0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
149d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
149e0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
149f0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
14a00 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
14a10 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
14a20 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
14a30 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
14a40 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
14a50 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
14a60 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
14a70 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
14a80 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
14a90 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
14aa0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
14ab0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
14ac0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
14ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
14ae0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
14af0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
14b00 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
14b10 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
14b20 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
14b30 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
14b40 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
14b50 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
14b60 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
14b70 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
14b80 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b  r Action Codes {
14b90 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e  H12550} <H12500>
14ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
14bb0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
14bc0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
14bd0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
14be0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
14bf0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
14c00 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
14c10 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
14c20 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
14c30 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
14c40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
14c50 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
14c60 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
14c70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
14c80 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
14c90 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
14ca0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
14cb0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
14cc0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
14cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
14ce0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
14cf0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
14d00 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
14d10 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
14d20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
14d30 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
14d40 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
14d50 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
14d60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
14d70 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
14d80 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
14d90 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
14da0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
14db0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
14dc0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
14dd0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14de0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
14df0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
14e00 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
14e10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
14e20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
14e30 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
14e40 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
14e50 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
14e60 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
14e70 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
14e80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
14e90 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
14ea0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
14eb0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
14ec0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
14ed0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
14ee0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
14ef0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
14f00 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
14f10 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
14f20 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
14f30 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  code..**.** Requ
14f40 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
14f50 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d 20 5b  2551] [H12552] [
14f60 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35 34 5d  H12553] [H12554]
14f70 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
14f80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14f90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14fa0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
14fb0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
14fc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14fd0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
14fe0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
14ff0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
15000 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
15010 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15020 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
15030 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
15040 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
15050 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15070 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
15080 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
15090 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
150a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
150b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
150c0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
150d0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
150e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
150f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15110 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
15120 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
15130 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
15140 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
15150 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15160 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
15170 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
15180 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
15190 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
151a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
151b0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
151c0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
151d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
151e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
151f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
15200 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
15210 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
15220 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
15230 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15240 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
15250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15260 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
15270 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15280 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15290 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
152a0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
152b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
152c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
152d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
152e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
152f0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
15300 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
15310 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15320 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15330 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15340 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
15350 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
15360 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15370 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15380 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
15390 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
153a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
153b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
153c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
153d0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
153e0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
153f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
15400 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
15410 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15420 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
15430 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
15440 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
15450 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15470 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
15480 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
15490 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
154a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
154b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
154c0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
154d0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
154e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
154f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15510 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
15520 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
15530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
15540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15560 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
15570 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
15580 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
15590 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
155a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
155b0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
155c0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
155d0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
155e0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
155f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
15600 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
15610 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
15620 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
15630 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
15650 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
15660 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
15670 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
15680 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15690 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
156a0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
156b0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
156c0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
156d0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
156e0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
156f0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
15700 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
15710 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
15720 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15730 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
15740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
15750 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
15760 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
15770 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15780 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
15790 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
157a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
157b0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
157c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
157d0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
157e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
157f0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
15800 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15810 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15820 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
15830 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
15840 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
15850 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15860 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15870 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
15880 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
15890 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
158a0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
158b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
158c0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
158d0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
158e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
158f0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
15900 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15910 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
15920 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
15930 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15940 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
15950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15960 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
15970 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
15980 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
15990 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
159a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
159b0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
159c0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
159d0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
159e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
159f0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
15a00 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
15a10 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34  s {H12280} <S604
15a20 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
15a30 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
15a40 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
15a50 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
15a60 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
15a70 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
15a80 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
15a90 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
15aa0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
15ab0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ts..**.** The ca
15ac0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
15ad0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
15ae0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
15af0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
15b00 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
15b10 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
15b20 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
15b30 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
15b40 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ()]..** The call
15b50 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55  back returns a U
15b60 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
15b70 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
15b80 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74  ent text.** as t
15b90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
15ba0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
15bb0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
15bc0 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72   callbacks occur
15bd0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
15be0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
15bf0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
15c00 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
15c10 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
15c20 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
15c30 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
15c40 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
15c50 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ger..**.** The c
15c60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
15c70 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
15c80 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
15c90 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
15ca0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
15cb0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
15cc0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
15cd0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
15ce0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
15cf0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
15d00 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
15d10 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
15d20 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
15d30 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
15d40 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
15d50 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
15d60 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 32 32  * [H12281] [H122
15d70 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48 31  82] [H12283] [H1
15d80 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d 20 5b  2284] [H12285] [
15d90 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38 38 5d  H12287] [H12288]
15da0 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 31   [H12289].** [H1
15db0 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2290].*/.SQLITE_
15dc0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
15dd0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
15de0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
15df0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
15e00 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
15e10 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
15e20 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
15e30 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
15e40 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
15e50 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
15e60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
15e70 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
15e80 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
15e90 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
15ea0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
15eb0 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30   {H12910} <S6040
15ec0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
15ed0 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
15ee0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
15ef0 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
15f00 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
15f10 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
15f20 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
15f30 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
15f40 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
15f50 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
15f60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15f70 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
15f80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
15f90 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
15fa0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
15fb0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
15fc0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
15fd0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
15fe0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
15ff0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
16000 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
16010 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
16020 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
16030 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
16040 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
16050 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
16060 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
16070 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
16080 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
16090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
160a0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
160b0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
160c0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
160d0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
160e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
160f0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
16100 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
16110 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
16120 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16130 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
16140 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
16150 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
16160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16170 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
16180 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
16190 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
161a0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
161b0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 31  ents:.** [H12911
161c0 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31 32 39  ] [H12912] [H129
161d0 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48 31  13] [H12914] [H1
161e0 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d 20 5b  2915] [H12916] [
161f0 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31 38 5d  H12917] [H12918]
16200 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
16210 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
16220 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
16230 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
16240 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
16250 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
16260 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
16270 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
16280 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a  12700} <S40200>.
16290 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
162a0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
162b0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
162c0 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
162d0 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
162e0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
162f0 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  t. The filename 
16300 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
16310 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
16320 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
16330 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
16340 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
16350 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
16360 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
16370 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
16380 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b  e3_open16(). A [
16390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
163a0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
163b0 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
163c0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
163d0 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
163e0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
163f0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
16400 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
16410 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
16420 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
16430 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
16440 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
16450 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
16460 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
16470 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
16480 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
16490 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20  te3].** object. 
164a0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
164b0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
164c0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
164d0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
164e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
164f0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
16500 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
16510 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
16520 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
16530 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
16540 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
16550 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
16560 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
16570 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
16580 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
16590 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
165a0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ror..**.** The d
165b0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
165c0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
165d0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
165e0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
165f0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
16600 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
16610 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
16620 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
16630 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
16640 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
16650 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
16660 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
16670 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
16680 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
16690 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
166a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
166b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
166c0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
166d0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
166e0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
166f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
16700 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
16710 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
16720 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
16730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16740 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
16750 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
16760 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
16770 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
16780 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
16790 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
167a0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
167b0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
167c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
167d0 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20  ion.  The flags 
167e0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61  parameter can ta
167f0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
16800 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
16810 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
16820 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
16830 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
16840 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
16850 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
16860 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73  FULLMUTEX] flags
16870 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
16880 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
16890 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
168a0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
168b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
168c0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
168d0 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
168e0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
168f0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
16900 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
16910 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
16920 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
16930 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
16940 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
16950 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
16960 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
16970 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
16980 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
16990 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
169a0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
169b0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
169c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
169d0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
169e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
169f0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
16a00 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
16a10 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
16a20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16a30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
16a40 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
16a50 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
16a60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
16a70 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
16a80 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
16a90 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
16aa0 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a  s creates it if.
16ab0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
16ac0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
16ad0 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
16ae0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
16af0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
16b00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
16b10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
16b20 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  ).</dd>.** </dl>
16b30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
16b40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
16b50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16b60 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
16b70 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
16b80 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
16b90 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d  r one of the com
16ba0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
16bb0 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a  above combined.*
16bc0 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
16bd0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
16be0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
16bf0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
16c00 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s,.** then the b
16c10 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
16c20 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
16c30 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
16c40 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
16c50 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
16c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16c70 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
16c80 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
16c90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
16ca0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
16cb0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
16cc0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
16cd0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
16ce0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
16cf0 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a  time.  If the.**
16d00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
16d10 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
16d20 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
16d30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16d40 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
16d50 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
16d60 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
16d70 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
16d80 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
16d90 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
16da0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
16db0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a   start-time..**.
16dc0 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
16dd0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
16de0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
16df0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
16e00 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
16e10 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
16e20 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
16e30 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79    This in-memory
16e40 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
16e50 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
16e60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16e70 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
16e80 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
16e90 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
16ea0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
16eb0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
16ec0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
16ed0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
16ee0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
16ef0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
16f00 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
16f10 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
16f20 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
16f30 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
16f40 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
16f50 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
16f60 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
16f70 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
16f80 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
16f90 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
16fa0 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
16fb0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
16fc0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
16fd0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
16fe0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
16ff0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
17000 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69  be created.  Thi
17010 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
17020 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
17030 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
17040 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
17050 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17060 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
17070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
17080 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
17090 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
170a0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
170b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
170c0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
170d0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
170e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
170f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
17100 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
17110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
17120 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65  uld use.  If the
17130 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
17140 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
17150 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
17160 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
17170 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
17180 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  used..**.** <b>N
17190 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
171a0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
171b0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
171c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
171d0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
171e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
171f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17200 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
17210 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
17220 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
17230 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
17240 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
17250 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
17260 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
17270 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
17280 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
17290 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
172a0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
172b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
172c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
172d0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
172e0 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30 31 5d 20  ts:.** [H12701] 
172f0 5b 48 31 32 37 30 32 5d 20 5b 48 31 32 37 30 33  [H12702] [H12703
17300 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48 31 32 37  ] [H12704] [H127
17310 30 36 5d 20 5b 48 31 32 37 30 37 5d 20 5b 48 31  06] [H12707] [H1
17320 32 37 30 39 5d 20 5b 48 31 32 37 31 31 5d 0a 2a  2709] [H12711].*
17330 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48 31 32 37  * [H12712] [H127
17340 31 33 5d 20 5b 48 31 32 37 31 34 5d 20 5b 48 31  13] [H12714] [H1
17350 32 37 31 37 5d 20 5b 48 31 32 37 31 39 5d 20 5b  2717] [H12719] [
17360 48 31 32 37 32 31 5d 20 5b 48 31 32 37 32 33 5d  H12721] [H12723]
17370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17380 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
17390 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
173a0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
173b0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
173c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
173d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
173e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
173f0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
17400 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
17410 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
17420 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
17430 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
17440 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
17450 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
17460 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
17470 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
17480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
17490 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
174a0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
174b0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
174c0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
174d0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
174e0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
174f0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
17500 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
17510 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
17520 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
17530 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
17540 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
17550 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
17560 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
17570 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
17580 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
17590 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30  es {H12800} <S60
175a0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200>.**.** The s
175b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
175c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
175d0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
175e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
175f0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
17600 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
17610 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
17620 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
17630 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
17640 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
17650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17660 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
17670 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
17680 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
17690 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
176a0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
176b0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
176c0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
176d0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
176e0 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
176f0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
17700 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
17710 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
17720 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
17730 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
17740 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
17750 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
17760 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
17770 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
17780 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
17790 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
177a0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
177b0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
177c0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
177d0 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
177e0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
177f0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
17800 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
17810 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
17820 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
17830 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
17840 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
17850 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
17860 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
17870 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
17880 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
17890 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
178a0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
178b0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
178c0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
178d0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
178e0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
178f0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
17900 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
17910 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
17920 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
17930 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
17940 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
17950 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
17960 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
17970 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
17980 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
17990 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
179a0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
179b0 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
179c0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
179d0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
179e0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
179f0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
17a00 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
17a10 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
17a20 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
17a30 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
17a40 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
17a50 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
17a60 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
17a70 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
17a80 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
17a90 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
17aa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
17ab0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
17ac0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
17ad0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
17ae0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
17af0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
17b00 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
17b10 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
17b20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
17b30 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
17b40 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
17b50 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
17b60 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
17b70 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
17b80 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
17b90 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
17ba0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
17bb0 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
17bc0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
17bd0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
17be0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
17bf0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
17c00 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
17c10 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
17c20 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
17c30 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
17c40 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52   be set..**.** R
17c50 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
17c60 5b 48 31 32 38 30 31 5d 20 5b 48 31 32 38 30 32  [H12801] [H12802
17c70 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48 31 32 38  ] [H12803] [H128
17c80 30 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b 48 31  07] [H12808] [H1
17c90 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2809].*/.int sql
17ca0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
17cb0 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
17cc0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
17cd0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
17ce0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
17cf0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
17d00 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
17d10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
17d20 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
17d30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17d40 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
17d50 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
17d60 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
17d70 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
17d80 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
17d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17da0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
17db0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
17dc0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
17dd0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
17de0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
17df0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
17e00 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
17e10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
17e20 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
17e30 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
17e40 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
17e50 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
17e60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
17e70 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
17e80 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
17e90 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
17ea0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
17eb0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
17ec0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
17ed0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17ee0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
17ef0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
17f00 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
17f10 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
17f20 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
17f30 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
17f40 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
17f50 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
17f60 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
17f70 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
17f80 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
17f90 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
17fa0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
17fb0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
17fc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
17fd0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
17fe0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
17ff0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
18000 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
18010 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
18020 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
18030 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
18040 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
18050 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
18060 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
18070 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
18080 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
18090 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
180a0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
180b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
180c0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
180d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
180e0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
180f0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
18100 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
18110 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
18120 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
18130 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
18140 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
18150 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
18160 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
18170 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
18180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
18190 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
181a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
181b0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
181c0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
181d0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
181e0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
181f0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
18200 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
18210 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
18220 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
18230 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
18240 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
18250 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
18260 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
18270 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
18280 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
18290 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
182a0 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
182b0 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
182c0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
182d0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
182e0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
182f0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
18300 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
18310 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
18320 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
18330 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
18340 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63  d].** set by a c
18350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72  ompile-time C pr
18360 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
18370 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69   named .** [limi
18380 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
18390 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  XYZ]..** (The "_
183a0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
183b0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
183c0 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
183d0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
183e0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
183f0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
18400 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
18410 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
18420 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
18430 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
18440 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
18450 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
18460 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
18470 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
18480 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
18490 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
184a0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
184b0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
184c0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
184d0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
184e0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
184f0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
18500 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
18510 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
18520 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
18530 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
18540 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
18550 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
18560 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
18570 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
18580 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
18590 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
185a0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
185b0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
185c0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
185d0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
185e0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
185f0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
18600 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
18610 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
18620 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
18630 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
18640 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
18650 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
18660 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
18670 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
18680 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
18690 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
186a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
186b0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
186c0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
186d0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
186e0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
186f0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
18700 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
18710 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
18720 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
18730 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
18740 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
18750 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
18760 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
18770 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
18780 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
18790 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
187a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
187b0 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31 32 37  * [H12762] [H127
187c0 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a 2f 0a  66] [H12769].*/.
187d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
187e0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
187f0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
18800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18810 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
18820 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32   Categories {H12
18830 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a  790} <H12760>.**
18840 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
18850 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d  t category} {lim
18860 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
18870 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
18880 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
18890 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
188a0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
188b0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
188c0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
188d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
188e0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
188f0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
18900 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
18910 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
18920 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
18930 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
18940 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
18950 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
18960 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
18970 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
18980 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
18990 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
189a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
189b0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
189c0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
189d0 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a  e row.<dd>.**.**
189e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
189f0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
18a00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
18a10 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
18a20 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
18a30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18a40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
18a50 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
18a60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18a70 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
18a80 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
18a90 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
18aa0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
18ab0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
18ac0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
18ad0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
18ae0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
18af0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
18b00 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
18b10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18b20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
18b30 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
18b40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
18b50 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
18b60 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
18b70 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
18b80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18b90 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
18ba0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
18bb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
18bc0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
18bd0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
18be0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
18bf0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18c00 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
18c10 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
18c20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18c30 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
18c40 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
18c50 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
18c60 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
18c70 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
18c80 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
18c90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
18ca0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
18cb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
18cc0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
18cd0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
18ce0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
18cf0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18d00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
18d10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
18d20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
18d30 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
18d40 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f  ed databases].</
18d50 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
18d70 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
18d80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18d90 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
18da0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
18db0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
18dc0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
18dd0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
18de0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18df0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
18e00 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
18e10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18e20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62  number of variab
18e30 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  les in an SQL st
18e40 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e  atement that can
18e50 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64  .** be bound.</d
18e60 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d>.** </dl>.*/.#
18e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
18e80 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
18e90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
18ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
18eb0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
18ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
18ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ee0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
18ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
18f10 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
18f20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18f30 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
18f40 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
18f50 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
18f60 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
18f70 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
18f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f90 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
18fa0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
18fb0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
18fc0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
18fd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
18fe0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
18ff0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
19000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
19010 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
19020 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
19030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
19040 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
19050 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20         9../*.** 
19060 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
19070 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
19080 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53  ment {H13010} <S
19090 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10000>.** KEYWOR
190a0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
190b0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
190c0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
190d0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
190e0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
190f0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
19100 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
19110 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
19120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
19130 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
19140 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
19150 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
19160 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
19170 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
19180 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
19190 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
191a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
191b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
191c0 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  n16()]..**.** Th
191d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
191e0 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
191f0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
19200 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
19210 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
19220 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
19230 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
19240 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
19250 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19260 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
19270 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
19280 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19290 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
192a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
192b0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
192c0 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  ** If the nByte 
192d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
192e0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
192f0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
19300 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
19310 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
19320 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f  . If nByte is no
19330 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
19340 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
19350 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
19360 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
19370 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79   zSql.  When nBy
19380 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
19390 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
193a0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
193b0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
193c0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
193d0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
193e0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
193f0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
19400 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
19410 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
19420 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
19430 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
19440 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
19450 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
19460 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
19470 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
19480 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
19490 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
194a0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
194b0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
194c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
194d0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
194e0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
194f0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
19500 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
19510 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69  es..**.** *pzTai
19520 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
19530 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
19540 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
19550 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  d of the.** firs
19560 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
19570 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
19580 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f  routines only co
19590 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a  mpile the first.
195a0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
195b0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
195c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
195d0 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e  g to what remain
195e0 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  s.** uncompiled.
195f0 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
19600 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
19610 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
19620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19630 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
19640 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
19650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19660 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ].  If there is 
19670 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
19680 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
19690 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
196a0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
196b0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
196c0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
196d0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
196e0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
196f0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
19700 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31   NULL..** {A1301
19710 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  8} The calling p
19720 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
19730 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
19740 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
19750 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
19760 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
19770 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
19780 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
19790 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a  hed with it..**.
197a0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
197b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
197c0 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73  turned, otherwis
197d0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
197e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
197f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19800 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
19810 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
19820 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
19830 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
19840 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
19850 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
19860 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
19870 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
19880 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
19890 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
198a0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
198b0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
198c0 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20  .** In the "v2" 
198d0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
198e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
198f0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
19900 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
19910 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
19920 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
19930 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
19940 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
19950 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
19960 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19970 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
19980 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
19990 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
199a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
199b0 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
199c0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
199d0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
199e0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
199f0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
19a00 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
19a10 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
19a20 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
19a30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
19a40 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
19a50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
19a60 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
19a70 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
19a80 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
19a90 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
19aa0 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
19ab0 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
19ac0 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
19ad0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
19ae0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
19af0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
19b00 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
19b10 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
19b20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
19b30 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
19b40 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
19b50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19b60 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
19b70 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
19b80 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
19b90 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
19ba0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
19bb0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
19bc0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
19bd0 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
19be0 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
19bf0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
19c00 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
19c10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
19c20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
19c30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19c40 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
19c50 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
19c60 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
19c70 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
19c80 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54  error codes].  T
19c90 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
19ca0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
19cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19cc0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
19cd0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
19ce0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
19cf0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f  t code.** and yo
19d00 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
19d10 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
19d20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
19d30 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
19d40 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
19d50 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
19d60 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
19d70 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
19d80 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
19d90 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
19da0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
19db0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
19dc0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19dd0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
19de0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  /ol>.**.** Requi
19df0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
19e00 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20 5b 48  011] [H13012] [H
19e10 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34 5d 20  13013] [H13014] 
19e20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30 31 36  [H13015] [H13016
19e30 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31 33 30  ] [H13019] [H130
19e40 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  21].**.*/.int sq
19e50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
19e60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
19e70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
19e80 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
19e90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
19ea0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
19eb0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
19ec0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
19ed0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
19ee0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
19ef0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
19f00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
19f10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
19f20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
19f30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
19f40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
19f50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
19f60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
19f70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
19f80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
19f90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
19fa0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
19fb0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
19fc0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
19fd0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
19fe0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
19ff0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1a000 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1a010 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1a020 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1a030 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1a040 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1a050 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1a060 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1a070 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1a080 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1a090 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1a0a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1a0b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1a0c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1a0d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1a0e0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1a0f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1a100 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1a110 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a120 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1a130 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1a140 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1a150 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1a160 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1a170 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1a180 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1a190 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1a1a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1a1b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1a1c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1a1d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1a1e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1a1f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1a200 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1a210 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1a220 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a230 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1a240 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1a250 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1a260 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a270 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1a280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1a290 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1a2a0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a2b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a2c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a2d0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a2e0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a2f0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a300 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a310 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a320 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1a330 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a340 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a350 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a370 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1a380 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33  atement SQL {H13
1a390 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a  100} <H13000>.**
1a3a0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1a3b0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
1a3c0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
1a3d0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
1a3e0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
1a3f0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
1a400 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
1a410 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
1a420 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
1a430 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
1a440 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1a450 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a460 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1a470 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1a480 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1a490 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48 31  .** [H13101] [H1
1a4a0 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a 2a  3102] [H13103].*
1a4b0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1a4c0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1a4d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1a4e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a4f0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1a500 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
1a510 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30  {H15000} <S20200
1a520 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1a530 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1a540 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1a550 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1a560 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1a570 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1a580 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1a590 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1a5a0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1a5b0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1a5c0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1a5d0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1a5e0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1a5f0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1a600 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
1a610 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1a620 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1a630 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1a640 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1a650 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1a660 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1a670 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1a680 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1a690 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1a6a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1a6b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1a6c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1a6d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1a6e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1a6f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1a700 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1a710 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1a720 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1a730 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1a740 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1a750 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1a760 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1a770 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1a780 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1a790 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1a7a0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1a7b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1a7c0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1a7d0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1a7e0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1a7f0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1a800 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1a810 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1a820 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1a830 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1a840 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1a850 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a860 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1a870 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1a880 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1a890 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a8a0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1a8b0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1a8c0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1a8d0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1a8e0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1a8f0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1a900 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1a910 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1a920 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1a930 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1a940 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1a950 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1a960 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1a970 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1a980 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1a990 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1a9a0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1a9b0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1a9c0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1a9d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1a9e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1a9f0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1aa00 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1aa10 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1aa20 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1aa30 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1aa40 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1aa50 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1aa60 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1aa70 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1aa80 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1aa90 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1aaa0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1aab0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1aac0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1aad0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1aae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1aaf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ab00 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1ab10 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1ab20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1ab30 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1ab40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1ab50 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1ab60 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1ab70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ab80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1ab90 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1aba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1abb0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1abc0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1abd0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1abe0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1abf0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1ac00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1ac10 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1ac20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1ac30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
1ac40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1ac50 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
1ac60 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
1ac70 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
1ac80 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
1ac90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1aca0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1acb0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1acc0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1acd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ace0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
1acf0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
1ad00 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a  16001} <S20200>.
1ad10 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1ad20 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1ad30 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1ad40 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1ad50 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1ad60 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1ad70 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1ad80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1ad90 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1ada0 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1adb0 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1adc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1add0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1ade0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1adf0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1ae00 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1ae10 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1ae20 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1ae30 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1ae40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1ae50 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1ae60 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1ae70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1ae80 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1ae90 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1aea0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1aeb0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1aec0 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1aed0 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1aee0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1aef0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1af00 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1af10 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1af20 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1af30 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1af40 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1af50 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1af60 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d Statements {H1
1af70 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3500} <S70300>.*
1af80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
1af90 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
1afa0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
1afb0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1afc0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
1afd0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
1afe0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
1aff0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
1b000 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
1b010 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
1b020 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b030 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b040 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1b050 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
1b060 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
1b070 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69   a [parameter] i
1b080 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66  n one of these f
1b090 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
1b0a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
1b0b0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
1b0c0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
1b0d0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
1b0e0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
1b0f0 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
1b100 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
1b110 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
1b120 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
1b130 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61  .** and VVV is a
1b140 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  n alpha-numeric 
1b150 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20  parameter name. 
1b160 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1b170 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1b180 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1b190 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1b1a0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1b1b0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1b1c0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1b1d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1b1e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1b1f0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1b200 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1b210 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1b220 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1b230 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1b240 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1b250 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1b260 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1b270 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1b280 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b290 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1b2a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1b2b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
1b2c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1b2d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
1b2e0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
1b2f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
1b300 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1b310 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
1b320 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1b330 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1b340 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
1b350 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
1b360 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
1b370 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
1b380 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
1b390 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
1b3a0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
1b3b0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1b3c0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1b3d0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1b3e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1b3f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b400 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
1b410 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
1b420 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1b430 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1b440 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1b450 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
1b460 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
1b470 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
1b480 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1b490 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
1b4a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1b4b0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
1b4c0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
1b4d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
1b4e0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
1b4f0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
1b500 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1b510 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
1b520 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
1b530 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
1b540 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
1b550 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1b560 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1b570 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
1b580 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
1b590 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1b5a0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
1b5b0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
1b5c0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
1b5d0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1b5e0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
1b5f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1b600 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
1b610 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
1b620 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
1b630 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
1b640 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1b650 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1b660 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
1b670 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b680 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1b690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1b6a0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1b6b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1b6c0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1b6d0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1b6e0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1b6f0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1b700 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1b710 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
1b720 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1b730 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1b740 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1b750 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1b760 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1b770 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1b780 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1b790 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1b7a0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1b7b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1b7c0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
1b7d0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1b7e0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1b7f0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1b800 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1b810 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1b820 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1b830 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1b840 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1b850 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1b860 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1b870 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
1b880 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1b890 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1b8a0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1b8b0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1b8c0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1b8d0 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
1b8e0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1b8f0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1b900 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1b910 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
1b920 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
1b930 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
1b940 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
1b950 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
1b960 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
1b970 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1b980 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1b990 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1b9a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
1b9b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
1b9c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
1b9d0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
1b9e0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
1b9f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
1ba00 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
1ba10 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
1ba20 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
1ba30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1ba40 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
1ba50 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
1ba60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ba70 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
1ba80 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
1ba90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
1baa0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
1bab0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1bac0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
1bad0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
1bae0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
1baf0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
1bb00 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
1bb10 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
1bb20 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
1bb30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bb40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1bb50 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1bb60 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
1bb70 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
1bb80 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
1bb90 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1bba0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1bbb0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1bbc0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1bbd0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
1bbe0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1bbf0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1bc00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
1bc10 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
1bc20 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
1bc30 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1bc40 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
1bc50 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
1bc60 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
1bc70 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
1bc80 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
1bc90 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
1bca0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
1bcb0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
1bcc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
1bcd0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
1bce0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
1bcf0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
1bd00 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
1bd10 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
1bd20 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
1bd30 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
1bd40 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
1bd50 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1bd60 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
1bd70 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
1bd80 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
1bd90 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
1bda0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1bdb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1bdc0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1bdd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1bde0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
1bdf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1be00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1be10 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1be20 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d  nts:.** [H13506]
1be30 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35 31   [H13509] [H1351
1be40 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 33  2] [H13515] [H13
1be50 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48  518] [H13521] [H
1be60 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a  13524] [H13527].
1be70 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 33  ** [H13530] [H13
1be80 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48  533] [H13536] [H
1be90 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d 20  13539] [H13542] 
1bea0 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34 38  [H13545] [H13548
1beb0 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f  ] [H13551].**.*/
1bec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1bed0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1bee0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1bef0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1bf00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1bf10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1bf20 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1bf30 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1bf40 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1bf50 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1bf60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1bf70 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1bf80 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1bf90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1bfa0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1bfb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1bfc0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1bfd0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1bfe0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1bff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1c000 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1c010 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1c020 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1c030 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1c040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c050 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1c060 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1c070 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1c080 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1c090 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1c0a0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1c0b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1c0c0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1c0d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1c0e0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1c0f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c100 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1c110 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30  arameters {H1360
1c120 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
1c130 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
1c140 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
1c150 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
1c160 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
1c170 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
1c180 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1c190 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1c1a0 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
1c1b0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
1c1c0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
1c1d0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
1c1e0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
1c1f0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
1c200 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
1c210 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
1c220 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
1c230 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
1c240 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
1c250 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ime..**.** This 
1c260 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
1c270 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
1c280 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
1c290 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
1c2a0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
1c2b0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
1c2c0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
1c2d0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
1c2e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1c2f0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
1c300 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
1c310 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72  s of the ?NNN ar
1c320 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
1c330 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
1c340 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
1c350 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1c360 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1c370 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1c380 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c390 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1c3a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1c3b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1c3c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1c3d0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1c3e0 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e  * [H13601].*/.in
1c3f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1c400 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
1c410 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1c420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c430 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
1c440 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
1c450 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1c460 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1c470 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c480 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
1c490 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
1c4a0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
1c4b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1c4c0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
1c4d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1c4e0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
1c4f0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
1c500 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
1c510 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
1c520 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
1c530 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
1c540 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1c550 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
1c560 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
1c570 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
1c580 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
1c590 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
1c5a0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
1c5b0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
1c5c0 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
1c5d0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
1c5e0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
1c5f0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
1c600 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
1c610 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
1c620 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
1c630 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
1c640 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
1c650 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1c660 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
1c670 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
1c680 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
1c690 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1c6a0 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
1c6b0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1c6c0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1c6d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
1c6e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1c6f0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
1c700 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
1c710 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
1c720 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
1c730 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
1c740 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
1c750 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
1c760 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
1c770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1c780 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1c790 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1c7a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1c7b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1c7c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1c7d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1c7e0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1c7f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1c800 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1c810 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1c820 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f  * [H13621].*/.co
1c830 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1c840 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1c850 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1c860 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
1c870 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
1c880 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
1c890 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
1c8a0 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30  me {H13640} <S70
1c8b0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  300>.**.** Retur
1c8c0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
1c8d0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1c8e0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
1c8f0 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
1c900 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
1c910 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
1c920 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
1c930 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
1c940 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1c950 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1c960 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
1c970 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
1c980 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
1c990 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
1c9a0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1c9b0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1c9c0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1c9d0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1c9e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1c9f0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1ca00 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1ca10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ca20 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1ca30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1ca40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1ca50 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1ca60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ca70 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1ca80 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1ca90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1caa0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1cab0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1cac0 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a  .** [H13641].*/.
1cad0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1cae0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1caf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1cb00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1cb10 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
1cb20 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
1cb30 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
1cb40 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
1cb50 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30  {H13660} <S70300
1cb60 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79  >.**.** Contrary
1cb70 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
1cb80 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
1cb90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
1cba0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
1cbb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1cbc0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
1cbd0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
1cbe0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1cbf0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
1cc00 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
1cc10 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
1cc20 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71   NULL..**.** Req
1cc30 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1cc40 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13661].*/.int sq
1cc50 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1cc60 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
1cc70 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1cc80 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1cc90 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
1cca0 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d  ult Set {H13710}
1ccb0 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
1ccc0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
1ccd0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1cce0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
1ccf0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
1cd00 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1cd10 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75  ement]. This rou
1cd20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
1cd30 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
1cd40 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
1cd50 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
1cd60 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
1cd70 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
1cd80 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ])..**.** Requir
1cd90 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37  ements:.** [H137
1cda0 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  11].*/.int sqlit
1cdb0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
1cdc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1cdd0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1cde0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
1cdf0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
1ce00 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
1ce10 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
1ce20 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1ce30 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
1ce40 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
1ce50 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
1ce60 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1ce70 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
1ce80 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
1ce90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1cea0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1ceb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1cec0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1ced0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1cee0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
1cef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1cf00 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
1cf10 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1cf20 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1cf30 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1cf40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1cf50 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
1cf60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1cf70 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
1cf80 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
1cf90 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
1cfa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1cfb0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
1cfc0 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
1cfd0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
1cfe0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
1cff0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1d000 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
1d010 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
1d020 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1d030 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
1d040 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
1d050 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1d060 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
1d070 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
1d080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1d090 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
1d0a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1d0b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
1d0c0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
1d0d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
1d0e0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
1d0f0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
1d100 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
1d110 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
1d120 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
1d130 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
1d140 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
1d150 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1d160 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1d170 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
1d180 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
1d190 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1d1a0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
1d1b0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
1d1c0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
1d1d0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
1d1e0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
1d1f0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
1d200 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
1d210 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
1d220 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
1d230 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
1d240 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
1d250 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
1d260 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1d270 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48 31 33  ** [H13721] [H13
1d280 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48  723] [H13724] [H
1d290 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36 5d 20  13725] [H13726] 
1d2a0 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73  [H13727].*/.cons
1d2b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d2c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
1d2d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
1d2e0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1d2f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1d300 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1d310 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
1d320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
1d330 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
1d340 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
1d350 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13740} <S10700>.
1d360 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d370 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1d380 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1d390 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66  e what column of
1d3a0 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69   what.** table i
1d3b0 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65  n which database
1d3c0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b   a result of a [
1d3d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1d3e0 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
1d3f0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
1d400 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
1d410 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
1d420 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
1d430 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
1d440 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
1d450 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61  ng.  The _databa
1d460 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
1d470 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
1d480 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
1d490 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
1d4a0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
1d4b0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
1d4c0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
1d4d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
1d4e0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  umn name..** The
1d4f0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1d500 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1d510 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1d520 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1d530 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
1d540 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d550 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1d560 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1d570 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
1d580 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
1d590 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
1d5a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
1d5b0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
1d5c0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
1d5d0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
1d5e0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
1d5f0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
1d600 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
1d610 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1d620 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
1d630 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
1d640 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1d650 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1d660 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1d670 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
1d680 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1d690 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
1d6a0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
1d6b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
1d6c0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
1d6d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68  **.** If the Nth
1d6e0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
1d6f0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
1d700 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
1d710 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
1d720 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
1d730 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
1d740 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
1d750 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
1d760 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20  ** NULL.  These 
1d770 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
1d780 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
1d790 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
1d7a0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
1d7b0 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73  ccurs.  Otherwis
1d7c0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
1d7d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
1d7e0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1d7f0 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63  , table.** and c
1d800 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
1d810 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
1d820 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
1d830 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68  m..**.** As with
1d840 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
1d850 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
1d860 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
1d870 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
1d880 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
1d890 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
1d8a0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
1d8b0 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  TF-8. {END}.**.*
1d8c0 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
1d8d0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
1d8e0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
1d8f0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1d900 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1d910 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
1d920 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
1d930 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1d940 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  fined..**.** {A1
1d950 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
1d960 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1d970 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1d980 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1d990 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
1d9a0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
1d9b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1d9c0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
1d9d0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1d9e0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
1d9f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
1da00 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1da10 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34 32  [H13741] [H13742
1da20 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 37  ] [H13743] [H137
1da30 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 31  44] [H13745] [H1
1da40 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a  3746] [H13748].*
1da50 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
1da60 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
1da70 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1da80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1da90 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
1daa0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
1dab0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
1dac0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
1dad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1dae0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
1daf0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
1db00 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
1db10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1db20 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
1db30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1db40 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1db50 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1db60 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1db70 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1db80 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
1db90 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1dba0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
1dbb0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1dbc0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
1dbd0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1dbe0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1dbf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1dc00 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1dc10 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1dc20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1dc30 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1dc40 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1dc50 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1dc60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1dc70 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
1dc80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1dc90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1dca0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
1dcb0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
1dcc0 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30  y Result {H13760
1dcd0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
1dce0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1dcf0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
1dd00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1dd10 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1dd20 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
1dd30 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
1dd40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1dd50 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
1dd60 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
1dd70 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
1dd80 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
1dd90 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
1dda0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
1ddb0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
1ddc0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
1ddd0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
1dde0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
1ddf0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
1de00 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
1de10 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
1de20 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
1de30 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
1de40 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1de50 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
1de60 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
1de70 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
1de80 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  oded. {END}.**.*
1de90 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  * For example, g
1dea0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
1deb0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
1dec0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
1ded0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
1dee0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
1def0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
1df00 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
1df10 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
1df20 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
1df30 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
1df40 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
1df50 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
1df60 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
1df70 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
1df80 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
1df90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1dfa0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
1dfb0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
1dfc0 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
1dfd0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
1dfe0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
1dff0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
1e000 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
1e010 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
1e020 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
1e030 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
1e040 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
1e050 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
1e060 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
1e070 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
1e080 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
1e090 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
1e0a0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
1e0b0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
1e0c0 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
1e0d0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
1e0e0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
1e0f0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
1e100 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
1e110 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
1e120 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
1e130 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1e140 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48 31 33  ** [H13761] [H13
1e150 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a 2a 2f  762] [H13763].*/
1e160 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1e170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1e180 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
1e190 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e1a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e1b0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
1e1c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1e1d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e1e0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
1e1f0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
1e200 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13200} <S10000>.
1e210 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
1e220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e230 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
1e240 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
1e250 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1e260 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1e270 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e280 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
1e290 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
1e2a0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
1e2b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1e2c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1e2d0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
1e2e0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
1e2f0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
1e300 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
1e310 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
1e320 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
1e330 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
1e340 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
1e350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1e360 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
1e370 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
1e380 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
1e390 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
1e3a0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
1e3b0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
1e3c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e3d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1e3e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
1e3f0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
1e400 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
1e410 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e420 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e430 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
1e440 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
1e450 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
1e460 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1e470 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
1e480 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
1e490 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1e4a0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
1e4b0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
1e4c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
1e4d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1e4e0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1e4f0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
1e500 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
1e510 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
1e520 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
1e530 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
1e540 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
1e550 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
1e560 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
1e570 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
1e580 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
1e590 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1e5a0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
1e5b0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
1e5c0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
1e5d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
1e5e0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
1e5f0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
1e600 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
1e610 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
1e620 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
1e630 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
1e640 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
1e650 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
1e660 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
1e670 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
1e680 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1e690 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
1e6a0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
1e6b0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
1e6c0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
1e6d0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
1e6e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
1e6f0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
1e700 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
1e710 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
1e720 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
1e730 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
1e740 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
1e750 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
1e760 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
1e770 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
1e780 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
1e790 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
1e7a0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
1e7b0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
1e7c0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
1e7d0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
1e7e0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
1e7f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1e800 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
1e810 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
1e820 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
1e830 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
1e840 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
1e850 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
1e860 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
1e870 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
1e880 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
1e890 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1e8a0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
1e8b0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
1e8c0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
1e8d0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
1e8e0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
1e8f0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
1e900 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
1e910 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
1e920 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
1e930 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
1e940 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
1e950 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
1e960 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
1e970 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1e980 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
1e990 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
1e9a0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
1e9b0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
1e9c0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
1e9d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
1e9e0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
1e9f0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
1ea00 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
1ea10 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
1ea20 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
1ea30 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1ea40 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
1ea50 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1ea60 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
1ea70 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
1ea80 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
1ea90 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1eaa0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1eab0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
1eac0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
1ead0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
1eae0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
1eaf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1eb00 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
1eb10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1eb20 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
1eb30 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
1eb40 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
1eb50 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
1eb60 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
1eb70 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
1eb80 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
1eb90 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
1eba0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
1ebb0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
1ebc0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
1ebd0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
1ebe0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
1ebf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ec00 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
1ec10 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
1ec20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
1ec30 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
1ec40 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
1ec50 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
1ec60 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
1ec70 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
1ec80 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
1ec90 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
1eca0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
1ecb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ecc0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
1ecd0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
1ece0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
1ecf0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
1ed00 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
1ed10 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
1ed20 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
1ed30 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
1ed40 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
1ed50 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
1ed60 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
1ed70 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
1ed80 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
1ed90 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
1eda0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
1edb0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
1edc0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
1edd0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
1ede0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
1edf0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
1ee00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1ee10 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
1ee20 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
1ee30 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
1ee40 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
1ee50 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
1ee60 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
1ee70 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
1ee80 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
1ee90 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
1eea0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
1eeb0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
1eec0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
1eed0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
1eee0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
1eef0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
1ef00 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1ef10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ef20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1ef30 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
1ef40 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
1ef50 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
1ef60 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
1ef70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1ef80 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
1ef90 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
1efa0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
1efb0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
1efc0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
1efd0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
1efe0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
1eff0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1f000 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
1f010 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1f020 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32  ents:.** [H13202
1f030 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31 35 33  ] [H15304] [H153
1f040 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48 31  06] [H15308] [H1
1f050 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  5310].*/.int sql
1f060 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
1f070 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1f080 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1f090 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1f0a0 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31  a result set {H1
1f0b0 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3770} <S10700>.*
1f0c0 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
1f0d0 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
1f0e0 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
1f0f0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
1f100 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  lt set..**.** Re
1f110 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1f120 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37 32 5d  H13771] [H13772]
1f130 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f140 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
1f150 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1f160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f170 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
1f180 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d  tatypes {H10265}
1f190 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30   <S10110><S10120
1f1a0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  >.** KEYWORDS: S
1f1b0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
1f1c0 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20   {H10266} Every 
1f1d0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
1f1e0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
1f1f0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
1f200 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
1f210 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
1f220 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
1f230 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
1f240 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
1f250 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
1f260 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
1f270 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
1f280 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
1f290 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1f2a0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
1f2b0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
1f2c0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
1f2d0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
1f2e0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
1f2f0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
1f300 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
1f310 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
1f320 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
1f330 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
1f340 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
1f350 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
1f360 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
1f370 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
1f380 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
1f390 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
1f3a0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
1f3b0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
1f3c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
1f3d0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1f3e0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
1f3f0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
1f400 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
1f410 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
1f420 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
1f430 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
1f440 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
1f450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
1f460 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
1f470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
1f480 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
1f490 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
1f4a0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
1f4b0 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c  Query {H13800} <
1f4c0 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
1f4d0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
1f4e0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
1f4f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1f500 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
1f510 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
1f520 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
1f530 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1f540 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
1f550 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
1f560 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
1f570 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
1f580 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
1f590 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65  .  In every case
1f5a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1f5b0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
1f5c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
1f5d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f5e0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
1f5f0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
1f600 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
1f610 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
1f620 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1f630 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1f640 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
1f650 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
1f660 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1f670 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
1f680 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
1f690 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
1f6a0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
1f6b0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
1f6c0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
1f6d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1f6e0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
1f6f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
1f700 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
1f710 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
1f720 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
1f730 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
1f740 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
1f750 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
1f760 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
1f770 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
1f780 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
1f790 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
1f7a0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
1f7b0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
1f7c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
1f7d0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
1f7e0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
1f7f0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
1f800 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
1f810 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1f820 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
1f830 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
1f840 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
1f850 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1f860 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
1f870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1f880 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1f890 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
1f8a0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
1f8b0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
1f8c0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
1f8d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1f8e0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
1f8f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1f900 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
1f910 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
1f920 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f930 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1f940 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
1f950 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
1f960 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
1f970 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
1f980 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
1f990 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
1f9a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
1f9b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1f9c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
1f9d0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
1f9e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
1f9f0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
1fa00 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
1fa10 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
1fa20 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
1fa30 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
1fa40 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
1fa50 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
1fa60 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
1fa70 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
1fa80 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
1fa90 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
1faa0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
1fab0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
1fac0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
1fad0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
1fae0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
1faf0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
1fb00 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
1fb10 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
1fb20 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
1fb30 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
1fb40 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
1fb50 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
1fb60 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1fb70 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
1fb80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
1fb90 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
1fba0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
1fbb0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
1fbc0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
1fbd0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
1fbe0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
1fbf0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
1fc00 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
1fc10 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
1fc20 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
1fc30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
1fc40 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
1fc50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1fc60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1fc70 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
1fc80 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20  r string..** If 
1fc90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
1fca0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
1fcb0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
1fcc0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
1fcd0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
1fce0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
1fcf0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
1fd00 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
1fd10 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
1fd20 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
1fd30 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
1fd40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
1fd50 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
1fd60 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
1fd70 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
1fd80 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
1fd90 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
1fda0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
1fdb0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
1fdc0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20   string..** The 
1fdd0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
1fde0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1fdf0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1fe00 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
1fe10 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
1fe20 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74    For clarity: t
1fe30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1fe40 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
1fe50 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
1fe60 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
1fe70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1fe80 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53  racters..**.** S
1fe90 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1fea0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
1feb0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
1fec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1fed0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
1fee0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
1fef0 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
1ff00 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
1ff10 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
1ff20 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
1ff30 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
1ff40 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
1ff50 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
1ff60 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
1ff70 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
1ff80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ff90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
1ffa0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
1ffb0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1ffc0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
1ffd0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
1ffe0 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
1fff0 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
20000 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
20010 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
20020 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20  -8..** The zero 
20030 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
20040 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
20050 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
20060 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
20070 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20080 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
20090 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
200a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
200b0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
200c0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
200d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
200e0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
200f0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
20100 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
20110 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
20120 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
20130 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
20140 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20150 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
20160 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
20170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
20180 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
20190 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
201a0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
201b0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
201c0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
201d0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
201e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
201f0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
20200 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
20210 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20220 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
20230 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
20240 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
20250 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
20260 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
20270 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  iate.  For.** ex
20280 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
20290 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
202a0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
202b0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
202c0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
202d0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
202e0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
202f0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
20300 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
20310 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
20320 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
20330 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
20340 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
20350 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
20360 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
20370 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
20380 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
20390 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
203a0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
203b0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
203c0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
203d0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
203e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
203f0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
20400 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
20410 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20420 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
20430 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
20440 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
20450 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
20460 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
20470 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
20480 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
20490 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
204a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
204b0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
204c0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
204d0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
204e0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
204f0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
20500 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
20510 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
20520 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
20530 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
20540 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
20550 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
20560 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
20570 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
20580 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
20590 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
205a0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
205b0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
205c0 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
205d0 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
205e0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
205f0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
20600 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
20610 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
20620 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
20630 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
20640 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
20650 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
20660 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
20670 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
20680 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
20690 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
206a0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
206b0 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
206c0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
206d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
206e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
206f0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
20700 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
20710 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
20720 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
20730 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
20740 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
20750 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
20760 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
20770 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
20780 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
20790 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
207a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
207b0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
207c0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
207d0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
207e0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
207f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
20800 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
20810 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
20820 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
20830 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
20840 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
20850 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
20860 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
20870 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
20880 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
20890 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
208a0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
208b0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
208c0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
208d0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
208e0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
208f0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
20900 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
20910 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
20920 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
20930 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
20940 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
20950 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
20960 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
20970 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
20980 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
20990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
209a0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
209b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
209c0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
209d0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
209e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
209f0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
20a00 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
20a10 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
20a20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
20a30 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
20a40 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
20a50 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
20a60 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
20a70 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
20a80 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
20a90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
20aa0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
20ab0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
20ac0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
20ad0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
20ae0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
20af0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
20b00 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
20b10 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
20b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
20b30 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
20b40 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
20b50 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
20b60 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
20b70 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
20b80 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
20b90 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
20ba0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
20bb0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
20bc0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
20bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
20be0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
20bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
20c00 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
20c10 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
20c20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
20c30 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
20c40 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
20c50 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
20c60 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
20c70 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
20c80 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
20c90 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
20ca0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
20cb0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
20cc0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
20cd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
20ce0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
20cf0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
20d00 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
20d10 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
20d20 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
20d30 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
20d40 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
20d50 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
20d60 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
20d70 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
20d80 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
20d90 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
20da0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
20db0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
20dc0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
20dd0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
20de0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
20df0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
20e00 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
20e10 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
20e20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
20e30 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
20e40 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
20e50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
20e60 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
20e70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
20e80 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
20e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
20ea0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
20eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
20ec0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
20ed0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
20ee0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
20ef0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
20f00 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
20f10 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
20f20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
20f30 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
20f40 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
20f50 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
20f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
20f70 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
20f80 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
20f90 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
20fa0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
20fb0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
20fc0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
20fd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
20fe0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
20ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21000 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
21010 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
21020 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
21030 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
21040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21050 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
21060 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
21070 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
21080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21090 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
210a0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
210b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
210c0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
210d0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
210e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
210f0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  )..**.** The poi
21100 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
21110 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
21120 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
21130 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
21140 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
21150 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
21160 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
21170 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
21180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
21190 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
211a0 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  ed.  The memory 
211b0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
211c0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
211d0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
211e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
211f0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
21200 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
21210 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
21220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
21230 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
21240 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
21250 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
21260 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
21270 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  .** If a memory 
21280 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
21290 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
212a0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
212b0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
212c0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
212d0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
212e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
212f0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
21300 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
21310 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
21320 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
21330 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
21340 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
21350 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
21360 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
21370 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
21380 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
21390 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  M]..**.** Requir
213a0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38  ements:.** [H138
213b0 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48 31  03] [H13806] [H1
213c0 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b  3809] [H13812] [
213d0 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31 38 5d  H13815] [H13818]
213e0 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33 38 32   [H13821] [H1382
213f0 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b  4].** [H13827] [
21400 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13830].*/.const
21410 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21420 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
21430 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21440 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
21450 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
21460 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21470 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
21480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21490 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
214a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
214b0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
214c0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
214d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
214e0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
214f0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
21500 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21510 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
21520 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
21530 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
21540 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
21550 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
21560 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
21570 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
21580 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21590 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
215a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
215b0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
215c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
215d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
215e0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
215f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21600 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
21610 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21620 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
21630 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21650 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
21660 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
21670 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c  bject {H13300} <
21680 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a  S70300><S30100>.
21690 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
216a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
216b0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
216c0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
216d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
216e0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74  ..** If the stat
216f0 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
21700 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
21710 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
21720 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
21730 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
21740 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74  urned. If execut
21750 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
21760 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
21770 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
21780 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
21790 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
217a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
217b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
217c0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
217d0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
217e0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
217f0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
21800 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66   statement].  If
21810 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
21820 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hine has not.** 
21830 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
21840 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
21850 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
21860 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
21870 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
21880 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71   error or an [sq
21890 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
218a0 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a  | interrupt]..**
218b0 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
218c0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
218d0 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
218e0 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
218f0 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
21900 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e  n the circumstan
21910 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ces, and the.** 
21920 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74  [error code] ret
21930 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53  urned will be [S
21940 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
21950 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
21960 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48  :.** [H11302] [H
21970 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71  11304].*/.int sq
21980 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
21990 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
219a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
219b0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
219c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
219d0 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d   Object {H13330}
219e0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
219f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
21a00 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
21a10 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
21a20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21a30 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
21a40 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
21a50 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
21a60 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
21a70 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
21a80 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
21a90 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
21aa0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
21ab0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
21ac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21ad0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
21ae0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
21af0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
21b00 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
21b10 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
21b20 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
21b30 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ndings..**.** {H
21b40 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69  11332} The [sqli
21b50 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
21b60 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
21b70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21b80 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
21b90 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68        back to th
21ba0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
21bb0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
21bc0 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68  * {H11334} If th
21bd0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
21be0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
21bf0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
21c00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
21c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21c20 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
21c30 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
21c40 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
21c50 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
21c60 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
21c70 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
21c80 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
21c90 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
21ca0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
21cb0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
21cc0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
21cd0 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65   {H11336} If the
21ce0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
21cf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
21d00 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
21d10 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
21d20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21d30 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
21d40 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
21d50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
21d60 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
21d70 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
21d80 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
21d90 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68  *.** {H11338} Th
21da0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
21db0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
21dc0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
21dd0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
21de0 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
21df0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
21e00 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
21e10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21e20 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
21e30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
21e40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
21e50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
21e60 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
21e70 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
21e80 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c  tions {H16100} <
21e90 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20200>.** KEYWO
21ea0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
21eb0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
21ec0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
21ed0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
21ee0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
21ef0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
21f00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
21f10 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
21f20 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  s}.**.** These t
21f30 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
21f40 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
21f50 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
21f60 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
21f70 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
21f80 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
21f90 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
21fa0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
21fb0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
21fc0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
21fd0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
21fe0 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
21ff0 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
22000 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
22010 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
22020 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
22030 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
22040 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
22050 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
22060 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
22070 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
22080 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
22090 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
220a0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
220b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
220c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
220d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
220e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
220f0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
22100 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
22110 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
22120 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e  added.  If a sin
22130 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73  gle program uses
22140 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
22150 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
22160 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79  ction internally
22170 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74  , then SQL funct
22180 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
22190 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20  ed individually 
221a0 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  to.** each datab
221b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
221c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
221d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
221e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
221f0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
22200 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
22210 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c  edefined.  The l
22220 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
22230 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
22240 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
22250 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a  sive of.** the z
22260 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
22270 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
22280 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
22290 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
222a0 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
222b0 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
222c0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
222d0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
222e0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
222f0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
22300 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74  ERROR] being ret
22310 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
22320 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22330 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
22340 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
22350 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
22360 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
22370 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
22380 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d  s. If this param
22390 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
223a0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
223b0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
223c0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
223d0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
223e0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
223f0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
22400 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
22410 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
22420 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
22430 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
22440 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
22450 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
22460 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
22470 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69    Any SQL functi
22480 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
22490 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65  n should be able
224a0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b   to work.** work
224b0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
224c0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
224d0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
224e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
224f0 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
22500 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
22510 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
22520 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c  other.  It is al
22530 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f  lowed to.** invo
22540 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
22550 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
22560 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
22570 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
22580 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
22590 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
225a0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
225b0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
225c0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57  f eTextRep..** W
225d0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
225e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
225f0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
22600 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
22610 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
22620 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
22630 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
22640 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
22650 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
22660 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
22670 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
22680 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
22690 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
226a0 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
226b0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
226c0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
226d0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
226e0 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
226f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
22700 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
22710 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
22720 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
22730 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
22740 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
22750 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
22760 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
22770 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
22780 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
22790 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
227a0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
227b0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
227c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
227d0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
227e0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
227f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
22800 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
22810 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
22820 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
22830 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
22840 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
22850 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
22860 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
22870 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
22880 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
22890 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
228a0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
228b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  ** parameters. A
228c0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
228d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
228e0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
228f0 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
22900 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
22910 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
22920 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
22930 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
22940 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
22950 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
22960 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
22970 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
22980 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  tion callbacks..
22990 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d  **.** It is perm
229a0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
229b0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
229c0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
229d0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
229e0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
229f0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
22a00 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
22a10 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
22a20 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
22a30 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
22a40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
22a50 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
22a60 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
22a70 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73  tation most clos
22a80 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
22a90 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
22aa0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
22ab0 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e   is used.  A fun
22ac0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
22ad0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
22ae0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
22af0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
22b00 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
22b10 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
22b20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
22b30 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
22b40 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e  Arg.  A function
22b50 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
22b60 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
22b70 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
22b80 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
22b90 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
22ba0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
22bb0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
22bc0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
22bd0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41  ifferent.  .** A
22be0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
22bf0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
22c00 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
22c10 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
22c20 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
22c30 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
22c40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
22c50 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
22c60 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
22c70 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
22c80 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75   UTF16..**.** Bu
22c90 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
22ca0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
22cb0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
22cc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
22cd0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nctions..** The 
22ce0 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f  first applicatio
22cf0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
22d00 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20  on with a given 
22d10 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61  name overrides a
22d20 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66  ll.** built-in f
22d30 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20  unctions in the 
22d40 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
22d50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20  onnection] with 
22d60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
22d70 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 70  * Subsequent app
22d80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22d90 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68   functions of th
22da0 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79  e same name only
22db0 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72   override .** pr
22dc0 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ior application-
22dd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
22de0 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78  s that are an ex
22df0 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68  act match for th
22e00 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70  e.** number of p
22e10 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72  arameters and pr
22e20 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67  eferred encoding
22e30 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69  ..**.** An appli
22e40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
22e50 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
22e60 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
22e70 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
22e80 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
22e90 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
22ea0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
22eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22ec0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
22ed0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
22ee0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
22ef0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
22f00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
22f10 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
22f20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
22f30 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30   [H16103] [H1610
22f40 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36  6] [H16109] [H16
22f50 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48  112] [H16118] [H
22f60 31 36 31 32 31 5d 20 5b 48 31 36 31 32 34 5d 20  16121] [H16124] 
22f70 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36  [H16127].** [H16
22f80 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48  130] [H16133] [H
22f90 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20  16136] [H16139] 
22fa0 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20  [H16142].*/.int 
22fb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
22fc0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
22fd0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
22fe0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
22ff0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
23000 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
23010 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
23020 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
23030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
23040 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
23050 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
23060 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
23070 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
23080 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
23090 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
230a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
230b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
230c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
230d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
230e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
230f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
23100 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
23110 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
23120 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
23130 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
23140 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23150 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23160 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
23170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
23180 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
23190 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
231a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
231b0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a  ontext*).);../*.
231c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
231d0 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30  t Encodings {H10
231e0 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48  267} <S50200> <H
231f0 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  16100>.**.** The
23200 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
23210 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
23220 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
23230 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
23240 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
23250 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
23260 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
23270 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
23280 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
23290 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
232a0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
232b0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
232c0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
232d0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
232e0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
232f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
23300 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
23310 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
23320 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
23330 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
23340 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
23350 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
23360 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
23370 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
23380 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
23390 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
233a0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
233b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
233c0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
233d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
233e0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
233f0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
23400 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
23410 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
23420 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
23430 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
23440 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
23450 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
23460 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
23470 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
23480 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
23490 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
234a0 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
234b0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
234c0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
234d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
234e0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
234f0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
23500 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
23510 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
23520 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
23530 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23540 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
23550 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
23560 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
23570 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
23580 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
23590 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
235a0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
235b0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
235c0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
235d0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
235e0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
235f0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
23600 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
23610 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
23620 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
23630 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
23640 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
23650 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
23660 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23670 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
23680 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
23690 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
236a0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
236b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
236c0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
236d0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
236e0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
236f0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20  arameter Values 
23700 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30  {H15100} <S20200
23710 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  >.**.** The C-la
23720 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
23730 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
23740 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
23750 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
23760 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
23770 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
23780 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
23790 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
237a0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
237b0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
237c0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
237d0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
237e0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
237f0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
23800 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
23810 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23820 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
23830 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23840 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
23850 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
23860 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
23870 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
23880 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
23890 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
238a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
238b0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
238c0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
238d0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
238e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
238f0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
23900 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
23910 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
23920 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
23930 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
23940 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
23950 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
23960 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
23970 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
23980 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
23990 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
239a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
239b0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
239c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
239d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
239e0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
239f0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
23a00 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
23a10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23a20 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
23a30 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
23a40 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
23a50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
23a60 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
23a70 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
23a80 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
23a90 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
23aa0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
23ab0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
23ac0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
23ad0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23ae0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
23af0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
23b00 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
23b10 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
23b20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
23b30 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
23b40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23b50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
23b60 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
23b70 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
23b80 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
23b90 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
23ba0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
23bb0 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  e.  The.** sqlit
23bc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
23bd0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
23be0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
23bf0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
23c00 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
23c10 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
23c20 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
23c30 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
23c40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
23c50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
23c60 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
23c70 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
23c80 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
23c90 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
23ca0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
23cb0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
23cc0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
23cd0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
23ce0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
23cf0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
23d00 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
23d10 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
23d20 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
23d30 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
23d40 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
23d50 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
23d60 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
23d70 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
23d80 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
23d90 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
23da0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
23db0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
23dc0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
23dd0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
23de0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
23df0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
23e00 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
23e10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  ned..**.** Pleas
23e20 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
23e30 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
23e40 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
23e50 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
23e60 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
23e70 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
23e80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
23e90 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
23ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
23eb0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
23ec0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
23ed0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
23ee0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
23ef0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
23f00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
23f10 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
23f20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
23f30 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
23f40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
23f50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
23f60 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
23f70 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
23f80 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
23f90 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
23fa0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
23fb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
23fc0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
23fd0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
23fe0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d  nts:.** [H15103]
23ff0 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30   [H15106] [H1510
24000 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35  9] [H15112] [H15
24010 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48  115] [H15118] [H
24020 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a  15121] [H15124].
24030 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35  ** [H15127] [H15
24040 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48  130] [H15133] [H
24050 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  15136].*/.const 
24060 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
24070 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
24080 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
24090 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
240a0 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
240b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
240c0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
240d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
240e0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
240f0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
24100 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
24110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
24120 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24130 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
24140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
24150 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
24160 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
24170 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
24180 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
24190 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
241a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
241b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
241c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
241d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
241e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
241f0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
24200 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
24210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
24220 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
24230 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
24240 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
24250 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24260 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
24270 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
24280 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
242a0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
242b0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
242c0 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30  xt {H16210} <S20
242d0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  200>.**.** The i
242e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
242f0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
24300 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
24310 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
24320 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
24330 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
24340 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
24350 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
24360 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
24370 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
24380 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
24390 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61  lled for a.** pa
243a0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
243b0 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
243c0 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
243d0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
243e0 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79  t that.** memory
243f0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
24400 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f  pointer to it. O
24410 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
24420 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
24430 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
24440 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
24450 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
24460 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
24470 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61  index,.** the sa
24480 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
24490 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65  urned. The imple
244a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
244b0 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
244c0 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  se.** the return
244d0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
244e0 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
244f0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  .** SQLite autom
24500 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
24510 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
24520 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
24530 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
24540 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
24550 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
24560 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
24570 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
24580 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
24590 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
245a0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
245b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
245c0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
245d0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
245e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
245f0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
24600 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
24610 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
24620 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
24630 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
24640 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
24650 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
24660 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
24670 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
24680 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31  ents:.** [H16211
24690 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 31 36 32  ] [H16213] [H162
246a0 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a  15] [H16217].*/.
246b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
246c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
246d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
246e0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
246f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24700 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
24710 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d  nctions {H16240}
24720 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
24730 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
24740 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
24750 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
24760 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
24770 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
24780 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
24790 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
247a0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
247b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
247c0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
247d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
247e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
247f0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
24800 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
24810 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
24820 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
24830 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44  d function. {END
24840 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
24850 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
24860 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
24870 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
24880 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
24890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
248a0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
248b0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
248c0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33  ents:.** [H16243
248d0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
248e0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
248f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
24900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24910 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
24920 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
24930 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30  ns {H16250} <S60
24940 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  600><S20200>.**.
24950 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
24960 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
24970 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
24980 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
24990 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
249a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
249b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
249c0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
249d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
249e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
249f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
24a00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24a10 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
24a20 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
24a30 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
24a40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24a50 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
24a60 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  n..**.** Require
24a70 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35  ments:.** [H1625
24a80 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  3].*/.sqlite3 *s
24a90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
24aa0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
24ab0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
24ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
24ad0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
24ae0 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53  Data {H16270} <S
24af0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
24b00 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
24b10 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
24b20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
24b30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
24b40 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
24b50 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
24b60 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
24b70 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
24b80 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
24b90 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
24ba0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
24bb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
24bc0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
24bd0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
24be0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
24bf0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
24c00 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
24c10 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
24c20 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
24c30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
24c40 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
24c50 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
24c60 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
24c70 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
24c80 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
24c90 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
24ca0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
24cb0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
24cc0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
24cd0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
24ce0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
24cf0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
24d00 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
24d10 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
24d20 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
24d30 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
24d40 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
24d50 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
24d60 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
24d70 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
24d80 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
24d90 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
24da0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
24db0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
24dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24dd0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
24de0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24df0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
24e00 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
24e10 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
24e20 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
24e30 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
24e40 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
24e50 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
24e60 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
24e70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
24e80 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64  ion. If no metad
24e90 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
24ea0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
24eb0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
24ec0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
24ed0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
24ee0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
24ef0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
24f00 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
24f10 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
24f20 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
24f30 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
24f40 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
24f50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
24f60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24f70 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
24f80 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
24f90 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
24fa0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
24fb0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
24fc0 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
24fd0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
24fe0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
24ff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
25000 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
25010 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
25020 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
25030 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
25040 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
25050 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
25060 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
25070 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69  oyed..** If it i
25080 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
25090 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
250a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
250b0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
250c0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
250d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
250e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
250f0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
25100 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
25110 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
25120 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
25130 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
25140 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
25150 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
25160 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
25170 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
25180 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
25190 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
251a0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
251b0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
251c0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
251d0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
251e0 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61    The only guara
251f0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
25200 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
25210 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
25220 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
25230 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
25240 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
25250 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
25260 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
25270 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
25280 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
25290 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
252a0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
252b0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
252c0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
252d0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69  ues and SQL vari
252e0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ables..**.** The
252f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
25300 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
25310 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
25320 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
25330 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
25340 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52  running..**.** R
25350 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
25360 5b 48 31 36 32 37 32 5d 20 5b 48 31 36 32 37 34  [H16272] [H16274
25370 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48 31 36 32  ] [H16276] [H162
25380 37 37 5d 20 5b 48 31 36 32 37 38 5d 20 5b 48 31  77] [H16278] [H1
25390 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73  6279].*/.void *s
253a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
253b0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
253c0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
253d0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
253e0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
253f0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
25400 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
25410 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
25420 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
25430 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
25440 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
25450 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30  Behavior {H10280
25460 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30100>.**.**
25470 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
25480 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
25490 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
254a0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
254b0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
254c0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
254d0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
254e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
254f0 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
25500 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
25510 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
25520 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
25530 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
25540 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
25550 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
25560 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
25570 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
25580 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
25590 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
255a0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
255b0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
255c0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
255d0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
255e0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
255f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
25600 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
25610 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
25620 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
25630 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
25640 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
25650 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
25660 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
25670 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
25680 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
25690 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
256a0 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
256b0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
256c0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
256d0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
256e0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
256f0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
25700 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
25710 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
25720 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
25730 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
25740 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
25750 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
25760 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
25770 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
25780 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32  ion {H16400} <S2
25790 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0200>.**.** Thes
257a0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
257b0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
257c0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
257d0 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
257e0 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
257f0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
25800 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
25810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25820 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
25830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25840 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
25850 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
25860 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
25870 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
25880 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
25890 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
258a0 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
258b0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
258c0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
258d0 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
258e0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
258f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
25900 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
25910 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
25920 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
25930 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
25940 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
25950 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
25960 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
25970 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
25980 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
25990 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
259a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
259b0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
259c0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
259d0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
259e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
259f0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
25a00 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
25a10 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
25a20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
25a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25a40 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
25a50 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
25a60 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
25a70 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
25a80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25a90 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
25aa0 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
25ab0 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
25ac0 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
25ad0 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
25ae0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
25af0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
25b00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25b10 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
25b20 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
25b30 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
25b40 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
25b50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
25b60 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
25b70 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
25b80 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
25b90 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
25ba0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
25bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
25bc0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
25bd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
25be0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
25bf0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
25c00 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
25c10 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
25c20 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74  eption..** SQLit
25c30 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
25c40 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
25c50 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
25c60 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
25c70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
25c80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
25c90 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
25ca0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
25cb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
25cc0 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
25cd0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
25ce0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
25cf0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
25d00 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
25d10 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  -8. SQLite.** in
25d20 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
25d30 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
25d40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
25d50 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
25d60 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
25d70 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
25d80 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
25da0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
25db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
25dc0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
25dd0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
25de0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
25df0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
25e00 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
25e10 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
25e20 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
25e30 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
25e40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
25e50 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
25e60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
25e70 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
25e80 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
25e90 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
25ea0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
25eb0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
25ec0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
25ed0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
25ee0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
25ef0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
25f00 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
25f10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
25f20 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
25f30 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
25f40 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
25f50 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
25f60 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
25f70 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
25f80 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
25f90 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
25fa0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
25fb0 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
25fc0 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
25fd0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
25fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
25ff0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
26000 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
26010 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
26020 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
26030 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
26040 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
26050 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42  n a function.  B
26060 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
26070 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
26080 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41  SQLITE_ERROR.  A
26090 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
260a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
260b0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
260c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
260d0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
260e0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
260f0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
26100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26110 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
26120 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
26130 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
26140 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
26150 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
26160 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
26170 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72   is to long to r
26180 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
26190 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
261a0 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
261b0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
261c0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
261d0 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
261e0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
261f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
26200 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
26210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
26220 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
26230 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
26240 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
26250 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26260 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
26270 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
26280 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
26290 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
262a0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
262b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
262c0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
262d0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
262e0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
262f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
26300 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26310 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
26320 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
26330 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
26340 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
26350 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
26360 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26370 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
26380 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
26390 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
263a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
263b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
263c0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
263d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
263e0 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
263f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
26400 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
26410 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
26420 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
26430 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
26440 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
26450 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
26460 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
26470 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26480 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
26490 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
264a0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
264b0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
264c0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
264d0 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
264e0 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
264f0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
26500 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
26510 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61  ly..** SQLite ta
26520 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
26530 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
26540 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
26550 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
26560 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
26570 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
26580 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66  nterfaces..** If
26590 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
265a0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
265b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
265c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
265d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
265e0 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
265f0 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
26600 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
26610 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
26620 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
26630 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
26640 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to 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 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
26680 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
26690 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
266a0 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
266b0 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
266c0 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
266d0 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
266e0 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
266f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
26700 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
26710 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
26720 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
26730 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26740 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
26750 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
26760 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
26770 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
26780 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
26790 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
267a0 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
267b0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
267c0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
267d0 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
267e0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
267f0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
26800 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
26810 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
26820 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
26830 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a  * interfaces or.
26840 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
26850 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
26860 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
26870 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
26880 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
26890 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
268a0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
268b0 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
268c0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
268d0 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
268e0 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  it or call a des
268f0 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
26900 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
26910 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
26920 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
26930 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
26940 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26950 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
26960 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
26970 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
26980 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
26990 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
269a0 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
269b0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
269c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
269d0 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
269e0 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
269f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
26a00 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
26a10 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
26a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
26a30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
26a40 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
26a50 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
26a60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26a70 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
26a80 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
26a90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26aa0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
26ab0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
26ac0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
26ad0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
26ae0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
26af0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
26b00 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
26b10 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
26b20 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
26b30 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
26b40 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
26b50 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
26b60 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
26b70 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
26b80 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
26b90 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
26ba0 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74  harm..** A [prot
26bb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26bc0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
26bd0 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
26be0 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
26bf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26c00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
26c10 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
26c20 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
26c30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
26c40 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
26c50 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
26c60 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
26c70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
26c80 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
26c90 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
26ca0 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
26cb0 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
26cc0 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
26cd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26ce0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
26cf0 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
26d00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
26d10 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
26d20 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26d30 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
26d40 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30  ments:.** [H1640
26d50 33 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36  3] [H16406] [H16
26d60 34 30 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48  409] [H16412] [H
26d70 31 36 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20  16415] [H16418] 
26d80 5b 48 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34  [H16421] [H16424
26d90 5d 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48  ].** [H16427] [H
26da0 31 36 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20  16430] [H16433] 
26db0 5b 48 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39  [H16436] [H16439
26dc0 5d 20 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34  ] [H16442] [H164
26dd0 34 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20  45] [H16448].** 
26de0 5b 48 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34  [H16451] [H16454
26df0 5d 20 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34  ] [H16457] [H164
26e00 36 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a  60] [H16463].*/.
26e10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
26e20 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
26e30 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
26e40 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
26e50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
26e60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
26e70 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
26e80 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
26e90 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
26ea0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
26eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
26ec0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
26ed0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
26ee0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
26ef0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
26f00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
26f10 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
26f20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
26f30 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
26f40 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
26f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26f60 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
26f70 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
26f80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26f90 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
26fa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
26fb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
26fc0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
26fd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
26fe0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
26ff0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
27000 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
27010 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
27020 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27030 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
27040 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
27050 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27060 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
27070 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
27080 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
27090 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
270a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
270b0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
270c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
270d0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
270e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
270f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27100 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
27110 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
27120 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
27130 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
27140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
27150 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
27160 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
27170 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
27180 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
27190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
271a0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
271b0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
271c0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
271d0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
271e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
271f0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
27200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27210 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
27220 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48  ing Sequences {H
27230 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a  16600} <S20300>.
27240 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
27250 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
27260 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
27270 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
27280 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
27290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
272a0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
272b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
272c0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
272d0 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
272e0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
272f0 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
27300 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
27310 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
27320 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
27330 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27340 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
27350 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
27360 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
27370 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27380 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63  on16(). In all c
27390 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
273a0 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
273b0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
273c0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
273d0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
273e0 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20  ment may be one 
273f0 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
27400 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
27410 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
27420 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  LE] or [SQLITE_U
27430 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
27440 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
27450 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
27460 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
27470 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
27480 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
27490 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
274a0 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
274b0 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
274c0 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
274d0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
274e0 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
274f0 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
27500 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
27510 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69  16_ALIGNED] to i
27520 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20  ndicate that.** 
27530 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
27540 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
27550 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
27560 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
27570 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
27580 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
27590 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f  r of the host co
275a0 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20  mputer..**.** A 
275b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
275c0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
275d0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
275e0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
275f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
27600 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
27610 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
27620 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
27630 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
27640 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
27650 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
27660 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
27670 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61   Each time the a
27680 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
27690 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
276a0 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
276b0 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
276c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
276d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
276e0 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
276f0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
27700 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
27710 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27720 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
27730 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
27740 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  ()..**.** The re
27750 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
27760 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
27770 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
27780 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
27790 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
277a0 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
277b0 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
277c0 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
277d0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
277e0 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
277f0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
27800 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
27810 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
27820 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
27830 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54  stered. {END}  T
27840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
27850 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
27860 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
27870 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
27880 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
27890 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
278a0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
278b0 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
278c0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
278d0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
278e0 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
278f0 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
27900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27910 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27920 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
27930 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
27940 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
27950 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
27960 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
27970 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
27980 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
27990 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
279a0 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
279b0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
279c0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
279d0 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
279e0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
279f0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
27a00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
27a10 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
27a20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
27a30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
27a40 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69  v2()..** Collati
27a50 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
27a60 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
27a70 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
27a80 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
27a90 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
27aa0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
27ab0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
27ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27ad0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
27ae0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
27af0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  lose()]..**.** R
27b00 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
27b10 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 30 34  [H16603] [H16604
27b20 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 36 36  ] [H16606] [H166
27b30 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 48 31  09] [H16612] [H1
27b40 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d 20 5b  6615] [H16618] [
27b50 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 36 36  H16621].** [H166
27b60 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 48 31  24] [H16627] [H1
27b70 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6630].*/.int sql
27b80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
27b90 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
27ba0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
27bb0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
27bc0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
27bd0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
27be0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
27bf0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
27c00 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
27c10 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
27c20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
27c30 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
27c40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
27c50 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
27c60 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
27c70 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
27c80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
27c90 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
27ca0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
27cb0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
27cc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
27cd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
27ce0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
27cf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
27d00 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
27d10 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
27d20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
27d30 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
27d40 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
27d50 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
27d60 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
27d70 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
27d80 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53  acks {H16700} <S
27d90 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20  20300>.**.** To 
27da0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
27db0 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
27dc0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
27dd0 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
27de0 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
27df0 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
27e00 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
27e10 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
27e20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
27e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27e40 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77  ] to be called w
27e50 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
27e60 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
27e70 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
27e80 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  quired..**.** If
27e90 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
27ea0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
27eb0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
27ec0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
27ed0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
27ee0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
27ef0 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
27f00 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
27f10 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
27f20 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
27f30 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49  TF-8. {H16703} I
27f40 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
27f50 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
27f60 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
27f70 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
27f80 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
27f90 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
27fa0 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c   order..** A cal
27fb0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
27fc0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
27fd0 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
27fe0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
27ff0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
28000 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
28010 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
28020 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
28030 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
28040 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
28050 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28060 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
28070 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28080 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
28090 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
280a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
280b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
280c0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
280d0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
280e0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
280f0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
28100 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
28110 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
28120 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
28130 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
28140 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
28150 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
28160 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
28170 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
28180 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
28190 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
281a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a  ation sequence..
281b0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
281c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
281d0 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
281e0 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
281f0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
28200 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28210 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
28220 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
28230 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
28240 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28250 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
28260 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
28270 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 5d 20  ts:.** [H16702] 
28280 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37 30 36  [H16704] [H16706
28290 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
282a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
282b0 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
282c0 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
282d0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
282e0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
282f0 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
28300 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
28310 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
28320 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
28330 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
28340 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
28350 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
28360 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
28370 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
28380 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
28390 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
283a0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
283b0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
283c0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
283d0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
283e0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
283f0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
28400 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
28410 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
28420 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
28430 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
28440 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
28450 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28460 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
28470 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
28480 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
28490 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
284a0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
284b0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
284c0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
284d0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
284e0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
284f0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
28500 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
28510 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
28520 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
28530 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
28540 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
28550 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
28560 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
28570 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
28580 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
28590 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
285a0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
285b0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
285c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
285d0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
285e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
285f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28600 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
28610 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
28620 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
28630 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
28640 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
28650 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
28660 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
28670 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b  r A Short Time {
28680 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e  H10530} <S40410>
28690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
286a0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
286b0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
286c0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
286d0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
286e0 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
286f0 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
28700 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
28710 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
28720 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
28730 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
28740 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
28750 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
28760 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
28770 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
28780 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
28790 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
287a0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
287b0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
287c0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
287d0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
287e0 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
287f0 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
28800 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
28810 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
28820 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  urned..**.** SQL
28830 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
28840 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
28850 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
28860 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
28870 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
28880 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
28890 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ect..**.** Requi
288a0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33 33  rements: [H10533
288b0 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 69 6e  ] [H10536].*/.in
288c0 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
288d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
288e0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
288f0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
28900 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
28910 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30  s {H10310} <S200
28920 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  00>.**.** If thi
28930 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
28940 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
28950 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
28960 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
28970 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
28980 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
28990 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
289a0 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
289b0 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
289c0 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
289d0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
289e0 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
289f0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
28a00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
28a10 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
28a20 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
28a30 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
28a40 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
28a50 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
28a60 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
28a70 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  o modify this va
28a80 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64  riable once a [d
28a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28aa0 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  on].** has been 
28ab0 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69  opened.  It is i
28ac0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
28ad0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
28ae0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
28af0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
28b00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
28b10 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
28b20 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
28b30 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
28b40 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69  n call and remai
28b50 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72  n unchanged ther
28b60 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  eafter..*/.SQLIT
28b70 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
28b80 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
28b90 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
28ba0 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
28bb0 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
28bc0 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32  e {H12930} <S602
28bd0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
28be0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
28bf0 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e}.**.** The sql
28c00 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
28c10 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
28c20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
28c30 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
28c40 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
28c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
28c60 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
28c70 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
28c80 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
28c90 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
28ca0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
28cb0 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
28cc0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
28cd0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
28ce0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f  atement..** Auto
28cf0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
28d00 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
28d10 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
28d20 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
28d30 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
28d40 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
28d50 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
28d60 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
28d70 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
28d80 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
28d90 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
28da0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
28db0 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
28dc0 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
28dd0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
28de0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
28df0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
28e00 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
28e10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
28e20 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
28e30 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
28e40 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
28e50 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
28e60 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
28e70 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
28e80 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
28e90 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
28ea0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
28eb0 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
28ec0 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
28ed0 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
28ee0 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
28ef0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
28f00 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
28f10 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
28f20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
28f30 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
28f40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  fined..**.** Req
28f50 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39  uirements: [H129
28f60 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48 31  31] [H12932] [H1
28f70 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a  2933] [H12934].*
28f80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
28f90 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
28fa0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
28fb0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
28fc0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
28fd0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
28fe0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32  Statement {H1312
28ff0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S60600>.**.*
29000 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
29010 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
29020 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
29030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29040 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
29050 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
29060 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
29070 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74  longs.  The [dat
29080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29090 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
290a0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
290b0 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
290c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
290d0 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68  ion] that was th
290e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
290f0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
29100 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29110 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
29120 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
29130 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
29140 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
29150 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
29160 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  lace..**.** Requ
29170 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32  irements: [H1312
29180 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  3].*/.sqlite3 *s
29190 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
291a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
291b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
291c0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
291d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
291e0 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30  nt {H13140} <S60
291f0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
29200 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29210 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
29220 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
29230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
29240 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
29250 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
29260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29270 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
29280 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
29290 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
292a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
292b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
292c0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
292d0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
292e0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
292f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29300 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65   pDb.  If no pre
29310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
29320 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
29330 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
29340 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
29350 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
29360 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
29370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
29380 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
29390 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
293a0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
293b0 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
293c0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
293d0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
293e0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
293f0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
29400 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
29410 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
29420 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31 34 36  [H13143] [H13146
29430 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31 33 31  ] [H13149] [H131
29440 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73  52].*/.sqlite3_s
29450 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78  tmt *sqlite3_nex
29460 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a  t_stmt(sqlite3 *
29470 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  pDb, sqlite3_stm
29480 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29490 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
294a0 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
294b0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
294c0 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20  lbacks {H12950} 
294d0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
294e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
294f0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
29500 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
29510 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
29520 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
29530 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
29540 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
29550 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
29560 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
29570 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
29580 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
29590 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
295a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
295b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
295c0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
295d0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
295e0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
295f0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
29600 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
29610 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
29620 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
29630 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
29640 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
29650 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
29660 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
29670 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
29680 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
29690 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
296a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
296b0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
296c0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
296d0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
296e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
296f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
29700 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
29710 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
29720 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
29730 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
29740 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
29750 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
29760 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
29770 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
29780 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
29790 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
297a0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
297b0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
297c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
297d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  d..**.** The cal
297e0 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
297f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
29800 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
29810 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
29820 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
29830 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
29840 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
29850 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
29860 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
29870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29880 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
29890 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
298a0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
298b0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
298c0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
298d0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
298e0 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
298f0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
29900 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
29910 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
29920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29930 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
29940 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
29950 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
29960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29970 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
29980 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
29990 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
299a0 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  h..**.** Registe
299b0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
299c0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
299d0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
299e0 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
299f0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
29a00 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
29a10 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
29a20 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
29a30 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
29a40 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
29a50 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
29a60 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
29a70 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
29a80 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
29a90 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
29aa0 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  ccur..** The rol
29ab0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
29ac0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
29ad0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
29ae0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
29af0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
29b00 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
29b10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29b20 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65  s closed..** The
29b30 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
29b40 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
29b50 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
29b60 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20  on is.** rolled 
29b70 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63  back because a c
29b80 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
29b90 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f  eturned non-zero
29ba0 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63  ..** <todo> Chec
29bb0 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f  k on this </todo
29bc0 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  >.**.** Requirem
29bd0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31  ents:.** [H12951
29be0 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39  ] [H12952] [H129
29bf0 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31  53] [H12954] [H1
29c00 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31  2955].** [H12961
29c10 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39  ] [H12962] [H129
29c20 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a  63] [H12964].*/.
29c30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
29c40 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
29c50 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
29c60 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
29c70 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
29c80 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
29c90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
29ca0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
29cb0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
29cc0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
29cd0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
29ce0 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12970} <S60400>.
29cf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29d00 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
29d10 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
29d20 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
29d30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
29d40 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
29d50 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
29d60 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
29d70 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
29d80 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
29d90 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
29da0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
29db0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
29dc0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
29dd0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
29de0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
29df0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
29e00 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
29e10 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
29e20 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
29e30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
29e40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
29e50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
29e60 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
29e70 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
29e80 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
29e90 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69  leted..** The fi
29ea0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
29eb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
29ec0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
29ed0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
29ee0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
29ef0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65  e_hook()..** The
29f00 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
29f10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
29f20 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
29f30 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
29f40 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
29f50 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
29f60 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
29f70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
29f80 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
29f90 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
29fa0 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  d..** The third 
29fb0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
29fc0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
29fd0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
29fe0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
29ff0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
2a000 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
2a010 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
2a020 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61  row..** The fina
2a030 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2a040 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
2a050 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
2a060 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  ** In the case o
2a070 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
2a080 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
2a090 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
2a0a0 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
2a0b0 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2a0c0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2a0d0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2a0e0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2a0f0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2a100 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2a110 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2a120 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
2a130 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2a140 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2a150 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
2a160 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
2a170 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
2a180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a190 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
2a1a0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
2a1b0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2a1c0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2a1d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a1e0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2a1f0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2a200 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2a210 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2a220 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2a230 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
2a240 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
2a250 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2a260 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a270 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2a280 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2a290 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2a2a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2a2b0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2a2c0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2a2d0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2a2e0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
2a2f0 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
2a300 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2a310 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75  d, its pArg valu
2a320 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  e.** is returned
2a330 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
2a340 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
2a350 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2a360 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b  s:.** [H12971] [
2a370 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d  H12973] [H12975]
2a380 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37   [H12977] [H1297
2a390 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32  9] [H12981] [H12
2a3a0 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f  983] [H12986].*/
2a3b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2a3c0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2a3d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2a3e0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2a3f0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2a400 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2a410 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2a420 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2a430 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2a440 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2a450 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33  ger Cache {H1033
2a460 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b  0} <S30900>.** K
2a470 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
2a480 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20   cache} {shared 
2a490 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  cache mode}.**.*
2a4a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
2a4b0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2a4c0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2a4d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2a4e0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2a4f0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2a500 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
2a510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a520 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
2a530 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
2a540 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
2a550 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
2a560 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
2a570 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
2a580 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2a590 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  nt is false..**.
2a5a0 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
2a5b0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2a5c0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2a5d0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2a5e0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2a5f0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2a600 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2a610 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2a620 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2a630 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2a640 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2a650 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2a660 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2a670 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
2a680 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
2a690 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
2a6a0 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
2a6b0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2a6c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2a6d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2a6e0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
2a6f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2a700 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
2a710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a720 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
2a730 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
2a740 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
2a750 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
2a760 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
2a770 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
2a780 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
2a790 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
2a7a0 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
2a7b0 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
2a7c0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
2a7d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2a7e0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
2a7f0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
2a800 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
2a810 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
2a820 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
2a830 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2a840 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2a850 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2a860 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2a870 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2a880 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2a890 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2a8a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2a8b0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53  herwise..**.** S
2a8c0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2a8d0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2a8e0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2a8f0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2a900 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2a910 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2a920 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2a930 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2a940 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2a950 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2a960 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2a970 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2a980 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2a990 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71   Mode].**.** Req
2a9a0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33  uirements: [H103
2a9b0 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31  31] [H10336] [H1
2a9c0 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a  0337] [H10339].*
2a9d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2a9e0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2a9f0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2aa00 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2aa10 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2aa20 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53  mory {H17340} <S
2aa30 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2aa40 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2aa50 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2aa60 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2aa70 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
2aa80 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2aa90 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2aaa0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2aab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
2aac0 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
2aad0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
2aae0 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
2aaf0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2ab00 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2ab10 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2ab20 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2ab30 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2ab40 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2ab50 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2ab60 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2ab70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ab80 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2ab90 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2aba0 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2abb0 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2abc0 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2abd0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2abe0 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37  s: [H17341] [H17
2abf0 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  342].*/.int sqli
2ac00 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2ac10 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2ac20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2ac30 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2ac40 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c   Size {H17350} <
2ac50 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2ac60 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2ac70 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2ac80 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
2ac90 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
2aca0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2acb0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2acc0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2acd0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
2ace0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2acf0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2ad00 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2ad10 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2ad20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2ad30 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2ad40 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2ad50 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2ad60 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2ad70 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2ad80 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2ad90 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2ada0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rmed..**.** The 
2adb0 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
2adc0 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
2add0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2ade0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2adf0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2ae00 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2ae10 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2ae20 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2ae30 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2ae40 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2ae50 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2ae60 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2ae70 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2ae80 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
2ae90 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
2aea0 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
2aeb0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
2aec0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
2aed0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
2aee0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
2aef0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
2af00 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
2af10 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
2af20 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2af30 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2af40 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2af50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
2af60 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2af70 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2af80 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2af90 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2afa0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2afb0 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2afc0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2afd0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2afe0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2aff0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
2b000 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
2b010 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
2b020 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
2b030 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
2b040 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
2b050 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
2b060 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
2b070 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
2b080 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
2b090 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
2b0a0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
2b0b0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
2b0c0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
2b0d0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
2b0e0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
2b0f0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
2b100 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
2b110 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2b120 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
2b130 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
2b140 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
2b150 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2b160 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
2b170 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
2b180 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
2b190 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
2b1a0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
2b1b0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
2b1c0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
2b1d0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
2b1e0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
2b1f0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
2b200 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
2b210 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2b220 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48  :.** [H16351] [H
2b230 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20  16352] [H16353] 
2b240 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35  [H16354] [H16355
2b250 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f  ] [H16358].*/.vo
2b260 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
2b270 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
2b280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b290 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
2b2a0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
2b2b0 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31  n Of A Table {H1
2b2c0 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a  2850} <S60300>.*
2b2d0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2b2e0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2b2f0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2b300 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2b310 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2b320 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2b330 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2b340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b350 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2b360 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2b370 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2b380 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
2b390 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
2b3a0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
2b3b0 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
2b3c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2b3d0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
2b3e0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
2b3f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
2b400 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
2b410 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2b420 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
2b430 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
2b440 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
2b450 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
2b460 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
2b470 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
2b480 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
2b490 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
2b4a0 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
2b4b0 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
2b4c0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
2b4d0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
2b4e0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2b4f0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
2b500 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
2b510 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
2b520 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
2b530 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2b540 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2b550 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2b560 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2b570 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2b580 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2b590 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2b5a0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2b5b0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2b5c0 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2b5d0 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72  ** Metadata is r
2b5e0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
2b5f0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
2b600 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
2b610 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
2b620 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
2b630 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2b640 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
2b650 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
2b660 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
2b670 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2b680 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2b690 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2b6a0 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
2b6b0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d..**.** <blockq
2b6c0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2b6d0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2b6e0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
2b6f0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
2b700 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
2b710 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
2b720 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
2b730 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2b740 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
2b750 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
2b760 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2b770 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
2b780 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b790 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
2b7a0 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
2b7b0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2b7c0 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
2b7d0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2b7e0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
2b7f0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2b800 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2b810 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
2b820 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
2b830 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
2b840 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2b850 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2b860 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
2b870 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
2b880 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2b890 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
2b8a0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
2b8b0 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
2b8c0 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
2b8d0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
2b8e0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
2b8f0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
2b900 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
2b910 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
2b920 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
2b930 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
2b940 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2b950 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2b960 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2b970 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2b980 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2b990 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
2b9a0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2b9b0 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
2b9c0 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
2b9d0 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
2b9e0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2b9f0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
2ba00 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
2ba10 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
2ba20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2ba30 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2ba40 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
2ba50 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
2ba60 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
2ba70 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2ba80 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2ba90 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2baa0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2bab0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2bac0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2bad0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2bae0 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2baf0 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2bb00 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2bb10 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2bb20 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2bb30 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2bb40 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2bb50 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2bb60 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2bb70 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  e>.**.** This fu
2bb80 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
2bb90 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
2bba0 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
2bbb0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
2bbc0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
2bbd0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
2bbe0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
2bbf0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
2bc00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
2bc10 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
2bc20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2bc30 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
2bc40 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
2bc50 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
2bc60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bc70 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
2bc80 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
2bc90 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
2bca0 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
2bcb0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2bcc0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2bcd0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2bce0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2bcf0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2bd00 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2bd10 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
2bd20 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2bd30 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
2bd40 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
2bd50 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2bd60 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
2bd70 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
2bd80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
2bd90 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
2bda0 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
2bdb0 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
2bdc0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
2bdd0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
2bde0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
2bdf0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
2be00 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
2be10 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
2be20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
2be30 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
2be40 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
2be50 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
2be60 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
2be70 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
2be80 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
2be90 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
2bea0 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
2beb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2bec0 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
2bed0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2bee0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
2bef0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
2bf00 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2bf10 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2bf20 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
2bf30 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
2bf40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2bf50 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2bf60 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
2bf70 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
2bf80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bf90 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
2bfa0 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32  ion {H12600} <S2
2bfb0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2bfc0 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
2bfd0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
2bfe0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
2bff0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
2c000 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d  ..**.** {H12601}
2c010 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2c020 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2c030 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2c040 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20   to load an.**  
2c050 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65          SQLite e
2c060 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2c070 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2c080 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
2c090 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65  .** {H12602} The
2c0a0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2c0b0 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zProc..**.** {H1
2c0c0 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
2c0d0 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
2c0e0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
2c0f0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
2c100 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
2c110 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
2c120 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
2c130 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d  ..**.** {H12604}
2c140 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2c150 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2c160 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2c170 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2c180 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2c190 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2c1a0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2c1b0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2c1c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  ng..**.** {H1260
2c1d0 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  5} If an error o
2c1e0 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
2c1f0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
2c200 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2c210 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f    [sqlite3_load_
2c220 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
2c230 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
2c240 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  empt to.**      
2c250 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d      fill *pzErrM
2c260 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
2c270 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
2c280 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  d in memory.**  
2c290 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64          obtained
2c2a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2c2b0 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20  alloc()]. {END} 
2c2c0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
2c2d0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2c2e0 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68    should free th
2c2f0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2c300 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2c310 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ee()]..**.** {H1
2c320 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20  2606} Extension 
2c330 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
2c340 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
2c350 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c360 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2c370 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
2c380 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
2c390 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20  s API,.**       
2c3a0 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20     otherwise an 
2c3b0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2c3c0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
2c3d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2c3e0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
2c3f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
2c400 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
2c410 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
2c420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c430 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2c440 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
2c450 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
2c460 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
2c470 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
2c480 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c490 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
2c4a0 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
2c4b0 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
2c4c0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
2c4d0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
2c4e0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
2c4f0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
2c500 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
2c510 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2c520 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
2c530 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48  nsion Loading {H
2c540 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12620} <S20500>.
2c550 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20  **.** So as not 
2c560 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
2c570 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
2c580 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2c590 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
2c5a0 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
2c5b0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
2c5c0 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
2c5d0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
2c5e0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
2c5f0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
2c600 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
2c610 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
2c620 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
2c630 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
2c640 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
2c650 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2c660 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
2c670 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65   off..**.** Exte
2c680 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2c690 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2c6a0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
2c6b0 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31  3..**.** {H12621
2c6c0 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
2c6d0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2c6e0 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
2c6f0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
2c700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2c710 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2c720 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
2c730 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
2c740 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20  ==0 to turn.**  
2c750 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20          it back 
2c760 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a  off again..**.**
2c770 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73   {H12622} Extens
2c780 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
2c790 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ff by default..*
2c7a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2c7b0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
2c7c0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
2c7d0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
2c7e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
2c7f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
2c800 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b   An Extensions {
2c810 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e  H12640} <S20500>
2c820 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2c830 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
2c840 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
2c850 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
2c860 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
2c870 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
2c880 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
2c890 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
2c8a0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
2c8b0 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73  all new [databas
2c8c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20  e connections]. 
2c8d0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
2c8e0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
2c8f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2c900 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e   extension in an
2c910 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a   array that is.*
2c920 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2c930 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2c940 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20  )].  If you run 
2c950 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68  a memory leak ch
2c960 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72  ecker.** on your
2c970 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
2c980 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
2c990 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61  ecause of this a
2c9a0 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  rray, invoke.** 
2c9b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
2c9c0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
2c9d0 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f   prior to shutdo
2c9e0 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
2c9f0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
2ca00 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
2ca10 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
2ca20 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
2ca30 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
2ca40 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2ca50 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
2ca60 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
2ca70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ca80 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
2ca90 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e    is opened usin
2caa0 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
2cab0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2cac0 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2cad0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2cae0 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2caf0 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69  * {H12642} Dupli
2cb00 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
2cb10 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
2cb20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
2cb30 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tine.**         
2cb40 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
2cb50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
2cb60 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
2cb70 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ess..**.** {H126
2cb80 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
2cb90 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65   stores a pointe
2cba0 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69  r to the extensi
2cbb0 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a  on in an array.*
2cbc0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
2cbd0 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2cbe0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2cbf0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2cc00 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
2cc10 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2cc20 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2cc30 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2cc40 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2cc50 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2cc60 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2cc70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2cc80 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2cc90 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2cca0 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30  {H12660} <S20500
2ccb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2ccc0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2ccd0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2cce0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2ccf0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2cd00 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f  . {END}  It undo
2cd10 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
2cd20 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73   all prior.** [s
2cd30 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2cd40 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a  nsion()] calls..
2cd50 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54  **.** {H12661} T
2cd60 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
2cd70 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f  ables all previo
2cd80 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a  usly registered.
2cd90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2cda0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2cdb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d  ..**.** {H12662}
2cdc0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2cdd0 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
2cde0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
2cdf0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2ce00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ce10 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2ce20 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a  n(void);../*.***
2ce30 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
2ce40 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
2ce50 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
2ce60 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
2ce70 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
2ce80 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
2ce90 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2cea0 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
2ceb0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
2cec0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
2ced0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
2cee0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
2cef0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
2cf00 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
2cf10 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
2cf20 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
2cf30 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
2cf40 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
2cf50 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
2cf60 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2cf70 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
2cf80 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
2cf90 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
2cfa0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
2cfb0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
2cfc0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
2cfd0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
2cfe0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
2cff0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
2d000 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
2d010 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
2d020 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2d030 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
2d040 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2d050 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2d060 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
2d070 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
2d080 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2d090 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
2d0a0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
2d0b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2d0c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
2d0d0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
2d0e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2d0f0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
2d100 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32  ect {H18000} <S2
2d110 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
2d120 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
2d130 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  e.** EXPERIMENTA
2d140 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65  L.**.** A module
2d150 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76   is a class of v
2d160 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20  irtual tables.  
2d170 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64  Each module is d
2d180 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20  efined.** by an 
2d190 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
2d1a0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
2d1b0 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63  ure.  This struc
2d1c0 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a  ture consists.**
2d1d0 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
2d1e0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
2d1f0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
2d200 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
2d210 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
2d220 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2d230 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
2d240 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2d250 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
2d260 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
2d270 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
2d280 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
2d290 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
2d2a0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
2d2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2d2c0 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
2d2d0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
2d2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
2d2f0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
2d300 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
2d310 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
2d320 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
2d330 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
2d340 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
2d350 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
2d360 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
2d370 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
2d380 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
2d390 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
2d3a0 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
2d3b0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
2d3c0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2d3d0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
2d3e0 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
2d3f0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2d400 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
2d410 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
2d420 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2d430 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
2d440 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
2d450 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2d460 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
2d470 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
2d480 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2d490 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
2d4a0 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
2d4b0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
2d4c0 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
2d4d0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
2d4e0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2d4f0 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
2d500 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
2d510 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
2d520 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2d530 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
2d540 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2d550 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
2d560 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
2d570 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2d580 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d590 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
2d5a0 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
2d5b0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
2d5c0 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
2d5d0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
2d5e0 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
2d5f0 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
2d600 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
2d610 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
2d620 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
2d630 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2d640 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
2d650 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
2d660 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2d670 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
2d680 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2d690 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
2d6a0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
2d6b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2d6c0 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
2d6d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2d6e0 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
2d6f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2d700 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
2d710 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
2d720 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
2d730 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d740 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d750 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d760 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
2d770 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
2d780 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
2d790 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
2d7a0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
2d7b0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
2d7c0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
2d7d0 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
2d7e0 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20  mation {H18100} 
2d7f0 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
2d800 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e  ORDS: sqlite3_in
2d810 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45  dex_info.** EXPE
2d820 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2d830 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
2d840 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
2d850 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
2d860 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
2d870 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
2d880 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
2d890 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
2d8a0 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
2d8b0 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
2d8c0 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
2d8d0 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
2d8e0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
2d8f0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
2d900 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
2d910 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
2d920 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
2d930 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
2d940 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
2d950 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
2d960 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
2d970 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
2d980 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
2d990 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
2d9a0 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
2d9b0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d  **.** <pre>colum
2d9c0 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a  n OP expr</pre>.
2d9d0 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69  **.** where OP i
2d9e0 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
2d9f0 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
2da00 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  .  The particula
2da10 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
2da20 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
2da30 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68  traint[].op.  Th
2da40 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2da50 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
2da60 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
2da70 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43  t[].iColumn.  aC
2da80 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
2da90 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
2daa0 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
2dab0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
2dac0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
2dad0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
2dae0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
2daf0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
2db00 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
2db10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d  .**.** The optim
2db20 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
2db30 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
2db40 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
2db50 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
2db60 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
2db70 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
2db80 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
2db90 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
2dba0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
2dbb0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
2dbc0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
2dbd0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
2dbe0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
2dbf0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
2dc00 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
2dc10 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
2dc20 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
2dc30 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
2dc40 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
2dc50 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
2dc60 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
2dc70 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
2dc80 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   Information abo
2dc90 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
2dca0 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
2dcb0 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
2dcc0 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20  ** Each term of 
2dcd0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
2dce0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
2dcf0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2dd00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73  ..**.** The xBes
2dd10 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75  tIndex method mu
2dd20 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
2dd30 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
2dd40 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
2dd50 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
2dd60 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
2dd70 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67  xFilter.  If arg
2dd80 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
2dd90 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
2dda0 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
2ddb0 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
2ddc0 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
2ddd0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
2dde0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
2ddf0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
2de00 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61  gv.  If aConstra
2de10 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
2de20 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
2de30 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
2de40 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
2de50 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
2de60 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
2de70 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
2de80 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
2de90 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
2dea0 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20   The idxNum and 
2deb0 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
2dec0 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
2ded0 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74  assed into xFilt
2dee0 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  er..** sqlite3_f
2def0 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74 6f  ree() is used to
2df00 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
2df10 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
2df20 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
2df30 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
2df40 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
2df50 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74  utput from xFilt
2df60 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  er will occur in
2df70 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
2df80 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
2df90 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
2dfa0 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
2dfb0 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
2dfc0 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
2dfd0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
2dfe0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61  estimatedCost va
2dff0 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61  lue is an estima
2e000 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f  te of the cost o
2e010 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70  f doing the.** p
2e020 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70  articular lookup
2e030 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f  .  A full scan o
2e040 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e  f a table with N
2e050 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
2e060 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f  have.** a cost o
2e070 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73  f N.  A binary s
2e080 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65  earch of a table
2e090 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68   of N entries sh
2e0a0 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63  ould have a.** c
2e0b0 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61  ost of approxima
2e0c0 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a  tely log(N)..**.
2e0d0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2e0e0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
2e0f0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
2e100 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
2e110 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
2e120 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2e130 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  QLite..*/.struct
2e140 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2e150 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
2e160 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
2e170 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
2e180 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
2e190 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
2e1a0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
2e1b0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e1c0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
2e1d0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
2e1e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
2e1f0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
2e200 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
2e210 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
2e220 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
2e230 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
2e240 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
2e250 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
2e260 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
2e270 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
2e280 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
2e290 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
2e2a0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
2e2b0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
2e2c0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
2e2d0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
2e2e0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
2e2f0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
2e300 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
2e310 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
2e320 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
2e330 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
2e340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
2e350 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
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 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
2e380 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
2e390 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
2e3a0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
2e3b0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
2e3c0 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
2e3d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
2e3e0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
2e3f0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
2e400 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
2e410 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
2e420 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e430 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
2e440 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
2e450 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
2e460 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
2e470 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
2e480 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
2e490 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
2e4a0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
2e4b0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
2e4c0 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
2e4d0 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
2e4e0 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
2e4f0 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
2e500 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
2e510 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
2e520 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
2e530 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
2e540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e550 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
2e560 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
2e570 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
2e580 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
2e590 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
2e5a0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
2e5b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
2e5c0 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
2e5d0 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
2e5e0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
2e5f0 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
2e600 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
2e610 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
2e620 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
2e630 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
2e640 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
2e650 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
2e660 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
2e670 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
2e680 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
2e690 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
2e6a0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
2e6b0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2e6c0 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
2e6d0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2e6e0 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
2e6f0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2e700 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2e710 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
2e720 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2e730 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
2e740 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
2e750 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2e760 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
2e770 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2e780 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
2e790 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
2e7a0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
2e7b0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
2e7c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48  mplementation {H
2e7d0 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18200} <S20400>.
2e7e0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2e7f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2e800 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
2e810 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
2e820 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 0a  ule name with a.
2e830 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2e840 6e 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75 6c  nection].  Modul
2e850 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
2e860 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
2e870 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 6e 65  e.** creating ne
2e880 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  w virtual tables
2e890 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20   on the module, 
2e8a0 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 0a  or before using.
2e8b0 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 76  ** preexisting v
2e8c0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 66  irtual tables of
2e8d0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
2e8e0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2e8f0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
2e900 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
2e910 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
2e920 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
2e930 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2e940 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
2e950 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
2e960 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e970 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
2e980 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2e990 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
2e9a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
2e9b0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
2e9c0 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
2e9d0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
2e9e0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2e9f0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
2ea00 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
2ea10 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68  le *,    /* Meth
2ea20 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
2ea30 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20  le */.  void *  
2ea40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ea50 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
2ea60 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
2ea70 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
2ea80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2ea90 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
2eaa0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
2eab0 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c  ation {H18210} <
2eac0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20400>.** EXPER
2ead0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
2eae0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64  is routine is id
2eaf0 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b  entical to the [
2eb00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2eb10 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 20  odule()] method 
2eb20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74  above,.** except
2eb30 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20   that it allows 
2eb40 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
2eb50 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63  ction to be spec
2eb60 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20  ified. It is.** 
2eb70 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69  even more experi
2eb80 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20  mental than the 
2eb90 72 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74  rest of the virt
2eba0 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a  ual tables API..
2ebb0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
2ebc0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
2ebd0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
2ebe0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2ebf0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2ec00 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
2ec10 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
2ec20 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
2ec30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ec40 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
2ec50 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
2ec60 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
2ec70 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
2ec80 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ,    /* Methods 
2ec90 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
2eca0 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
2ecb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2ecc0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
2ecd0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
2ece0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
2ecf0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
2ed00 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
2ed10 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2ed20 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2ed30 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2ed40 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
2ed50 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c  bject {H18010} <
2ed60 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
2ed70 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
2ed80 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  b.** EXPERIMENTA
2ed90 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  L.**.** Every mo
2eda0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
2edb0 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
2edc0 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
2edd0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
2ede0 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  * to describe a 
2edf0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
2ee00 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  nce of the modul
2ee10 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  e.  Each subclas
2ee20 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
2ee30 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
2ee40 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
2ee50 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
2ee60 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  entation..** The
2ee70 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
2ee80 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
2ee90 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
2eea0 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
2eeb0 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  .** common to al
2eec0 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
2eed0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
2eee0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
2eef0 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
2ef00 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
2ef10 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
2ef20 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
2ef30 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2ef40 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45  mprintf()] to zE
2ef50 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
2ef60 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
2ef70 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
2ef80 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
2ef90 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
2efa0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2efb0 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
2efc0 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
2efd0 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
2efe0 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72  g.  After the er
2eff0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
2f000 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
2f010 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
2f020 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
2f030 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
2f040 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
2f050 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
2f060 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
2f070 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
2f080 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74   be zeroed.  Not
2f090 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65  e.** that sqlite
2f0a0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
2f0b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
2f0c0 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a  re used on the z
2f0d0 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20  ErrMsg field.** 
2f0e0 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61  since virtual ta
2f0f0 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c  bles are commonl
2f100 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  y implemented in
2f110 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73   loadable extens
2f120 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f  ions which.** do
2f130 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
2f140 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e   to sqlite3MPrin
2f150 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46  tf() or sqlite3F
2f160 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ree()..**.** Thi
2f170 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
2f180 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2f190 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2f1a0 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
2f1b0 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
2f1c0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2f1d0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2f1e0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
2f1f0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2f200 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
2f210 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
2f220 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
2f230 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
2f240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f250 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
2f260 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68  ternally */.  ch
2f270 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
2f280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f290 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
2f2a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
2f2b0 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
2f2c0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
2f2d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
2f2e0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
2f2f0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
2f300 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
2f310 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2f320 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a  Table Cursor Obj
2f330 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53  ect  {H18020} <S
2f340 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20400>.** KEYWOR
2f350 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
2f360 5f 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50 45 52  _cursor.** EXPER
2f370 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76  IMENTAL.**.** Ev
2f380 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
2f390 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
2f3a0 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
2f3b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
2f3c0 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
2f3d0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
2f3e0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
2f3f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
2f400 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
2f410 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
2f420 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
2f430 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
2f440 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
2f450 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
2f460 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
2f470 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
2f480 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
2f490 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
2f4a0 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
2f4b0 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
2f4c0 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
2f4d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
2f4e0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
2f4f0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
2f500 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
2f510 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
2f520 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
2f530 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
2f540 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
2f550 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
2f560 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
2f570 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2f580 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
2f590 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2f5a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
2f5b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2f5c0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
2f5d0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
2f5e0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
2f5f0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
2f600 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
2f610 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
2f620 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
2f630 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
2f640 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
2f650 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
2f660 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2f670 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
2f680 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
2f690 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30   {H18280} <S2040
2f6a0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
2f6b0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72  AL.**.** The xCr
2f6c0 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63  eate and xConnec
2f6d0 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d  t methods of a m
2f6e0 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f  odule use the fo
2f6f0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74  llowing API.** t
2f700 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
2f710 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
2f720 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
2f730 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
2f740 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
2f750 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
2f760 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ement..**.** Thi
2f770 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
2f780 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2f790 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2f7a0 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
2f7b0 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
2f7c0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2f7d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
2f7e0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
2f7f0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
2f800 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
2f810 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
2f820 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ble);../*.** CAP
2f830 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
2f840 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
2f850 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b   Virtual Table {
2f860 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18300} <S20400>
2f870 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2f880 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
2f890 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
2f8a0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
2f8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f8c0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
2f8d0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
2f8e0 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
2f8f0 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
2f900 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
2f910 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
2f920 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
2f930 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
2f940 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
2f950 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
2f960 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
2f970 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
2f980 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
2f990 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
2f9a0 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
2f9b0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
2f9c0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
2f9d0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
2f9e0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
2f9f0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
2fa00 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
2fa10 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
2fa20 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
2fa30 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
2fa40 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
2fa50 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
2fa60 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
2fa70 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
2fa80 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
2fa90 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
2faa0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
2fab0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
2fac0 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
2fad0 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
2fae0 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61  ded.** by virtua
2faf0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  l tables..**.** 
2fb00 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20  This API should 
2fb10 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61  be considered pa
2fb20 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  rt of the virtua
2fb30 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
2fb40 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65  e,.** which is e
2fb50 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2fb60 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
2fb70 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  e..*/.SQLITE_EXP
2fb80 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
2fb90 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
2fba0 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
2fbb0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
2fbc0 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
2fbd0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
2fbe0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
2fbf0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2fc00 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
2fc10 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
2fc20 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
2fc30 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
2fc40 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
2fc50 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
2fc60 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
2fc70 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
2fc80 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
2fc90 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
2fca0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
2fcb0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
2fcc0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
2fcd0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
2fce0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
2fcf0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
2fd00 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
2fd10 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
2fd20 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
2fd30 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
2fd40 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
2fd50 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
2fd60 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
2fd70 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
2fd80 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45  ent..**.****** E
2fd90 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
2fda0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
2fdb0 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
2fdc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f  *************.*/
2fdd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fde0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
2fdf0 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38   Open BLOB {H178
2fe00 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20  00} <S30230>.** 
2fe10 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
2fe20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
2fe30 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
2fe40 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
2fe50 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
2fe60 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
2fe70 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
2fe80 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2fe90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2fea0 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
2feb0 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65  rformed..** Obje
2fec0 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
2fed0 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20   are created by 
2fee0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
2fef0 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73  en()].** and des
2ff00 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2ff10 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
2ff20 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2ff30 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
2ff40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
2ff50 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
2ff60 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
2ff70 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
2ff80 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
2ff90 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
2ffa0 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  OB..** The [sqli
2ffb0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
2ffc0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2ffd0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
2ffe0 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65  the BLOB in byte
2fff0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
30000 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
30010 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
30020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30030 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
30040 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
30050 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33   {H17810} <S3023
30060 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
30070 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61  terfaces opens a
30080 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20   [BLOB handle | 
30090 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42  handle] to the B
300a0 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69  LOB located.** i
300b0 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75  n row iRow, colu
300c0 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c  mn zColumn, tabl
300d0 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61  e zTable in data
300e0 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20  base zDb;.** in 
300f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
30100 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20   same BLOB that 
30110 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65  would be selecte
30120 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
30130 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
30140 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
30150 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72  .zTable WHERE [r
30160 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a  owid] = iRow;.**
30170 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a   </pre> {END}.**
30180 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73  .** If the flags
30190 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
301a0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 65 20  n-zero, the the 
301b0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
301c0 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77  or read.** and w
301d0 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20  rite access. If 
301e0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
301f0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
30200 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
30210 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
30220 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
30230 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
30240 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
30250 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
30260 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
30270 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
30280 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
30290 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69   that.** is assi
302a0 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64 61  gned when the da
302b0 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63  tabase is connec
302c0 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43  ted using [ATTAC
302d0 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d  H]..** For the m
302e0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
302f0 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  e, the database 
30300 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a  name is "main"..
30310 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  ** For TEMP tabl
30320 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
30330 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
30340 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
30350 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
30360 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74  s returned and t
30370 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e  he new [BLOB han
30380 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a  dle] is written.
30390 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f  ** to *ppBlob. O
303a0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
303b0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
303c0 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 61 6c  rned and any val
303d0 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  ue written.** to
303e0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20   *ppBlob should 
303f0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74  not be used by t
30400 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68  he caller..** Th
30410 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
30420 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
30440 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
30450 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
30460 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
30470 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
30480 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
30490 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77  **.** If the row
304a0 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
304b0 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
304c0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
304d0 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
304e0 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
304f0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
30500 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
30510 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
30520 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
30530 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
30540 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
30550 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
30560 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
30570 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
30580 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
30590 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
305a0 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20   is open on..** 
305b0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
305c0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
305d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
305e0 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
305f0 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
30600 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
30610 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
30620 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
30630 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72  ]..** Changes wr
30640 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f  itten into a BLO
30650 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42  B prior to the B
30660 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65  LOB expiring are
30670 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b   not.** rollback
30680 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69   by the expirati
30690 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20  on of the BLOB. 
306a0 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69   Such changes wi
306b0 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ll eventually.**
306c0 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74   commit if the t
306d0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69  ransaction conti
306e0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
306f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  on..**.** Requir
30700 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38  ements:.** [H178
30710 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 48 31  13] [H17814] [H1
30720 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b  7816] [H17819] [
30730 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 34 5d  H17821] [H17824]
30740 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30750 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
30760 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
30770 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
30780 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
30790 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
307a0 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
307b0 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
307c0 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
307d0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
307e0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
307f0 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c  3REF: Close A BL
30800 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33  OB Handle {H1783
30810 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
30820 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e  * Closes an open
30830 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a   [BLOB handle]..
30840 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20  **.** Closing a 
30850 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65  BLOB shall cause
30860 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61   the current tra
30870 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d  nsaction to comm
30880 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61  it.** if there a
30890 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42  re no other BLOB
308a0 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72  s, no pending pr
308b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
308c0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61  s, and the.** da
308d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
308e0 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d  n is in [autocom
308f0 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66  mit mode]..** If
30900 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65   any writes were
30910 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f   made to the BLO
30920 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65  B, they might be
30930 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a   held in cache.*
30940 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73  * until the clos
30950 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74  e operation if t
30960 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45  hey will fit. {E
30970 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e  ND}.**.** Closin
30980 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
30990 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
309a0 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
309b0 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
309c0 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
309d0 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
309e0 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
309f0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
30a00 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
30a10 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e 79 20  .  {H17833} Any 
30a20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
30a30 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
30a40 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
30a50 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
30a60 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a  eturn value..**.
30a70 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63  ** The BLOB is c
30a80 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f  losed unconditio
30a90 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20  nally.  Even if 
30aa0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
30ab0 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  urns.** an error
30ac0 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20   code, the BLOB 
30ad0 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e  is still closed.
30ae0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
30af0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d  nts:.** [H17833]
30b00 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33   [H17836] [H1783
30b10 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
30b20 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c  3_blob_close(sql
30b30 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
30b40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
30b50 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
30b60 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b  f An Open BLOB {
30b70 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e  H17840} <S30230>
30b80 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
30b90 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
30ba0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
30bb0 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
30bc0 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68  open.** []BLOB h
30bd0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
30be0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ly argument..**.
30bf0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
30c00 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a  .** [H17843].*/.
30c10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
30c20 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
30c30 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
30c40 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
30c50 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
30c60 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31  ncrementally {H1
30c70 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7850} <S30230>.*
30c80 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
30c90 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
30ca0 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
30cb0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
30cc0 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
30cd0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
30ce0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
30cf0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
30d00 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
30d10 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
30d20 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
30d30 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
30d40 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74  .**.** If offset
30d50 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
30d60 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
30d70 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
30d80 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
30d90 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
30da0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
30db0 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e  a is read.  If N
30dc0 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a   or iOffset is.*
30dd0 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
30de0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
30df0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
30e00 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
30e10 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d  ..**.** An attem
30e20 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
30e30 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
30e40 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
30e50 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
30e60 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
30e70 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ABORT]..**.** On
30e80 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
30e90 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
30ea0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
30eb0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
30ec0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
30ed0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
30ee0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
30ef0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
30f00 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d  H17853] [H17856]
30f10 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36   [H17859] [H1786
30f20 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37  2] [H17863] [H17
30f30 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f  865] [H17868].*/
30f40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
30f50 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
30f60 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
30f70 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
30f80 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
30f90 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61  3REF: Write Data
30fa0 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63   Into A BLOB Inc
30fb0 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38  rementally {H178
30fc0 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  70} <S30230>.**.
30fd0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
30fe0 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74   is used to writ
30ff0 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f  e data into an o
31000 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
31010 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c  ] from a.** call
31020 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
31030 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
31040 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
31050 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a  rom the buffer Z
31060 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  .** into the ope
31070 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
31080 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
31090 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  et..**.** If the
310a0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
310b0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
310c0 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
310d0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
310e0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
310f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
31100 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
31110 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
31120 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
31130 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
31140 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
31150 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
31160 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
31170 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
31180 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20  of the BLOB; it 
31190 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
311a0 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
311b0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f  he size of a BLO
311c0 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  B using this API
311d0 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69  ..** If offset i
311e0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
311f0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
31200 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
31210 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
31220 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
31230 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
31240 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20  is written.  If 
31250 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
31260 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
31270 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
31280 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
31290 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20   written..**.** 
312a0 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
312b0 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
312c0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
312d0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
312e0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
312f0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
31300 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c  Writes to the BL
31310 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64  OB that occurred
31320 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
31330 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70  BLOB handle] exp
31340 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c  ired are not rol
31350 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a  led back by the.
31360 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  ** expiration of
31370 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f   the handle, tho
31380 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
31390 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68  ose changes migh
313a0 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f  t.** have been o
313b0 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
313c0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
313d0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f   expired the BLO
313e0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62  B handle.** or b
313f0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64  y other independ
31400 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  ent statements..
31410 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
31420 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
31430 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
31440 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
31450 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
31460 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
31470 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
31480 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
31490 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d  nts:.** [H17873]
314a0 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37   [H17874] [H1787
314b0 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37  5] [H17876] [H17
314c0 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48  877] [H17879] [H
314d0 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a  17882] [H17885].
314e0 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69  ** [H17888].*/.i
314f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
31500 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c  write(sqlite3_bl
31510 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ob *, const void
31520 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
31530 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
31540 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
31550 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f  al File System O
31560 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20  bjects {H11200} 
31570 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
31580 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
31590 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
315a0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
315b0 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
315c0 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
315d0 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
315e0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
315f0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
31600 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
31610 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
31620 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
31630 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
31640 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
31650 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
31660 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
31670 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
31680 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
31690 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
316a0 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
316b0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
316c0 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
316d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
316e0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
316f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31700 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
31710 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
31720 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63  ..** Names are c
31730 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a  ase sensitive..*
31740 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f  * Names are zero
31750 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
31760 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  8 strings..** If
31770 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
31780 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ch, a NULL point
31790 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
317a0 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69  ** If zVfsName i
317b0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
317c0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72  default VFS is r
317d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e  eturned..**.** N
317e0 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
317f0 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
31800 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
31810 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77  r()..** Each new
31820 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
31830 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
31840 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
31850 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65  g is set..** The
31860 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
31870 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
31880 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
31890 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f  ut injury..** To
318a0 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
318b0 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
318c0 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
318d0 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
318e0 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
318f0 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
31900 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
31910 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
31920 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
31930 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
31940 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
31950 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
31960 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
31970 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
31980 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
31990 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
319a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
319b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
319c0 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65  .**.** Unregiste
319d0 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
319e0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
319f0 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66  egister() interf
31a00 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ace..** If the d
31a10 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
31a20 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
31a30 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
31a40 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
31a50 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
31a60 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
31a70 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
31a80 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
31a90 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b  s:.** [H11203] [
31aa0 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d  H11206] [H11209]
31ab0 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31   [H11212] [H1121
31ac0 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73  5] [H11218].*/.s
31ad0 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
31ae0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
31af0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
31b00 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
31b10 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
31b20 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
31b30 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
31b40 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
31b50 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
31b60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31b70 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31  REF: Mutexes {H1
31b80 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7000} <S20000>.*
31b90 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
31ba0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
31bb0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
31bc0 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
31bd0 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74  zation. Though t
31be0 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
31bf0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
31c00 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
31c10 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
31c20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
31c30 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
31c40 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
31c50 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
31c60 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
31c70 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
31c80 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
31c90 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
31ca0 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
31cb0 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
31cc0 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
31cd0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
31ce0 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
31cf0 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
31d00 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  ime.  The follow
31d10 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
31d20 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
31d30 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
31d40 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
31d50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
31d60 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
31d70 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
31d80 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
31d90 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
31da0 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
31db0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
31dc0 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NOOP.** </ul>.**
31dd0 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  .** The SQLITE_M
31de0 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
31df0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
31e00 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  t of routines.**
31e10 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
31e20 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
31e30 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
31e40 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69  r use in.** a si
31e50 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
31e60 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
31e70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
31e80 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
31e90 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
31ea0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
31eb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
31ec0 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
31ed0 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53  te for use on OS
31ee0 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69  /2, Unix, and Wi
31ef0 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ndows..**.** If 
31f00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
31f10 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
31f20 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
31f30 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
31f40 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
31f50 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
31f60 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
31f70 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
31f80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31f90 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
31fa0 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
31fb0 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
31fc0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
31fd0 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
31fe0 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
31ff0 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
32000 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
32010 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
32020 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
32030 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
32040 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
32050 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
32060 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
32070 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
32080 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
32090 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
320a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
320b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ()..**.** {H1701
320c0 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
320d0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
320e0 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
320f0 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
32100 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
32110 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30  ter to it. {H170
32120 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e  12} If it return
32130 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
32140 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
32150 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
32160 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31  llocated. {H1701
32170 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  3} SQLite.** wil
32180 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61  l unwind its sta
32190 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ck and return an
321a0 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d   error. {H17014}
321b0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   The argument.**
321c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
321d0 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
321e0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
321f0 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
32200 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
32210 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
32220 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
32230 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
32240 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
32250 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
32260 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
32270 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
32280 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
32290 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
322a0 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
322b0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
322c0 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
322d0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
322e0 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
322f0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
32300 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
32310 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48  * </ul>.**.** {H
32320 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74  17015} The first
32330 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63   two constants c
32340 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
32350 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
32360 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
32370 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75  tex.  The new mu
32380 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
32390 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
323a0 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
323b0 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
323c0 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
323d0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
323e0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b  _FAST is used. {
323f0 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65  END}.** The mute
32400 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
32410 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
32420 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
32430 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
32440 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
32450 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
32460 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
32470 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
32480 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36  ant to.  {H17016
32490 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c  } But SQLite wil
324a0 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
324b0 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
324c0 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
324d0 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
324e0 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49  ds one.  {END} I
324f0 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72  f a faster non-r
32500 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a  ecursive mutex.*
32510 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32520 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e   is available on
32530 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f   the host platfo
32540 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75  rm, the mutex su
32550 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74  bsystem.** might
32560 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d   return such a m
32570 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65  utex in response
32580 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   to SQLITE_MUTEX
32590 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  _FAST..**.** {H1
325a0 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20  7017} The other 
325b0 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65  allowed paramete
325c0 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  rs to sqlite3_mu
325d0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68  tex_alloc() each
325e0 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
325f0 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
32600 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
32610 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20  ex. {END}  Four 
32620 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  static mutexes a
32630 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68  re.** used by th
32640 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
32650 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75  n of SQLite.  Fu
32660 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
32670 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61   SQLite.** may a
32680 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  dd additional st
32690 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53  atic mutexes.  S
326a0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
326b0 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  e for internal.*
326c0 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20  * use by SQLite 
326d0 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
326e0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c  ons that use SQL
326f0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ite mutexes shou
32700 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74  ld.** use only t
32710 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
32720 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  es returned by S
32730 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
32740 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55   or.** SQLITE_MU
32750 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a  TEX_RECURSIVE..*
32760 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f  *.** {H17018} No
32770 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f  te that if one o
32780 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  f the dynamic mu
32790 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28  tex parameters (
327a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
327b0 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d  T.** or SQLITE_M
327c0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
327d0 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c  is used then sql
327e0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
327f0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
32800 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20  different mutex 
32810 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20  on every call.  
32820 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72  {H17034} But for
32830 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d   the static.** m
32840 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20  utex types, the 
32850 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65  same mutex is re
32860 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20  turned on every 
32870 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a  call that has.**
32880 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e   the same type n
32890 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  umber..**.** {H1
328a0 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65  7019} The sqlite
328b0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72  3_mutex_free() r
328c0 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74  outine deallocat
328d0 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a  es a previously.
328e0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e  ** allocated dyn
328f0 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37  amic mutex. {H17
32900 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63  020} SQLite is c
32910 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
32920 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
32930 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
32940 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b   it allocates. {
32950 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61  A17021} The dyna
32960 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74  mic mutexes must
32970 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73   not be in.** us
32980 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  e when they are 
32990 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31  deallocated. {A1
329a0 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67  7022} Attempting
329b0 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
329c0 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
329d0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
329e0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
329f0 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20  {H17023} SQLite 
32a00 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65  never deallocate
32a10 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75  s.** a static mu
32a20 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  tex. {END}.**.**
32a30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
32a40 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
32a50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
32a60 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
32a70 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
32a80 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34  a mutex. {H17024
32a90 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
32aa0 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
32ab0 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
32ac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
32ad0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
32ae0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
32af0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
32b00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
32b10 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35  TE_BUSY. {H17025
32b20 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  }  The sqlite3_m
32b30 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
32b40 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51  face returns [SQ
32b50 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e  LITE_OK].** upon
32b60 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72   successful entr
32b70 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74  y.  {H17026} Mut
32b80 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
32b90 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
32ba0 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
32bb0 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
32bc0 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
32bd0 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
32be0 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75  * {H17027} In su
32bf0 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
32c00 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
32c10 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
32c20 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
32c30 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
32c40 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
32c50 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20  r.  {A17028} If 
32c60 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32c70 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
32c80 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  ny other.** kind
32c90 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74   of mutex more t
32ca0 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
32cb0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
32cc0 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d  ned..** {H17029}
32cd0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
32ce0 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75  er exhibit.** su
32cf0 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69  ch behavior in i
32d00 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75  ts own use of mu
32d10 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  texes..**.** Som
32d20 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
32d30 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
32d40 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
32d50 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
32d60 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
32d70 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
32d80 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
32d90 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
32da0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
32db0 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
32dc0 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
32dd0 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20  .  {H17030} The 
32de0 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79  SQLite core only
32df0 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71   ever uses.** sq
32e00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
32e10 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61  ) as an optimiza
32e20 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20  tion so this is 
32e30 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76  acceptable behav
32e40 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  ior..**.** {H170
32e50 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  31} The sqlite3_
32e60 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
32e70 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
32e80 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
32e90 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
32ea0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
32eb0 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d  hread.  {A17032}
32ec0 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   The behavior.**
32ed0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
32ee0 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
32ef0 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
32f00 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
32f10 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
32f20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
32f30 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31   allocated.  {H1
32f40 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c  7033} SQLite wil
32f50 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
32f60 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ther. {END}.**.*
32f70 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e  * If the argumen
32f80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  t to sqlite3_mut
32f90 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69  ex_enter(), sqli
32fa0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c  te3_mutex_try(),
32fb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   or.** sqlite3_m
32fc0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20  utex_leave() is 
32fd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
32fe0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72  then all three r
32ff0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76  outines.** behav
33000 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  e as no-ops..**.
33010 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
33020 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
33030 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33040 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
33050 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  ]..*/.sqlite3_mu
33060 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74  tex *sqlite3_mut
33070 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  ex_alloc(int);.v
33080 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
33090 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d  x_free(sqlite3_m
330a0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
330b0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
330c0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
330d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
330e0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f  tex_try(sqlite3_
330f0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
33100 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
33110 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
33120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33130 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64  EF: Mutex Method
33140 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30  s Object {H17120
33150 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58  } <S20130>.** EX
33160 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
33170 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
33180 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64  this structure d
33190 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c  efines the low-l
331a0 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  evel routines.**
331b0 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74   used to allocat
331c0 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65  e and use mutexe
331d0 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79  s..**.** Usually
331e0 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  , the default mu
331f0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
33200 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20  ons provided by 
33210 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75  SQLite are.** su
33220 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65  fficient, howeve
33230 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74  r the user has t
33240 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62  he option of sub
33250 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74  stituting a cust
33260 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  om.** implementa
33270 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c  tion for special
33280 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73  ized deployments
33290 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20   or systems for 
332a0 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20  which SQLite.** 
332b0 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
332c0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
332d0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74  ementation. In t
332e0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73  his case, the us
332f0 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e  er.** creates an
33300 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69  d populates an i
33310 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
33320 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73  structure to pas
33330 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
33340 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77  config() along w
33350 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
33360 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
33370 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  tion..** Additio
33380 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e  nally, an instan
33390 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
333a0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
333b0 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74   as an.** output
333c0 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71   variable when q
333d0 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74  uerying the syst
333e0 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  em for the curre
333f0 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  nt mutex.** impl
33400 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e  ementation, usin
33410 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
33420 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f  NFIG_GETMUTEX] o
33430 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ption..**.** The
33440 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
33450 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
33460 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
33470 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
33480 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69  rt of system ini
33490 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74  tialization by t
334a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
334b0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
334c0 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68  ..** {H17001} Th
334d0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75  e xMutexInit rou
334e0 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61  tine shall be ca
334f0 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  lled by SQLite o
33500 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  nce for each.** 
33510 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
33520 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  o [sqlite3_initi
33530 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
33540 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65  The xMutexEnd me
33550 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20  thod defined by 
33560 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69  this structure i
33570 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20  s invoked as.** 
33580 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73  part of system s
33590 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73  hutdown by the s
335a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
335b0 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a  ) function. The.
335c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
335d0 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64  n of this method
335e0 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20   is expected to 
335f0 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73  release all outs
33600 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75  tanding.** resou
33610 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79  rces obtained by
33620 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f   the mutex metho
33630 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ds implementatio
33640 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a  n, especially.**
33650 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20   those obtained 
33660 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69  by the xMutexIni
33670 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30  t method. {H1700
33680 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64  3} The xMutexEnd
33690 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
336a0 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
336b0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
336c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
336d0 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
336e0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
336f0 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64   seven methods d
33700 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
33710 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78  tructure (xMutex
33720 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78  Alloc,.** xMutex
33730 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65  Free, xMutexEnte
33740 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d  r, xMutexTry, xM
33750 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65  utexLeave, xMute
33760 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75  xHeld and.** xMu
33770 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c  texNotheld) impl
33780 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77  ement the follow
33790 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28  ing interfaces (
337a0 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a  respectively):.*
337b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
337c0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
337d0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c  tex_alloc()] </l
337e0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
337f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
33800 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
33810 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
33820 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f  utex_enter()] </
33830 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
33840 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
33850 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  y()] </li>.**   
33860 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
33870 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f  utex_leave()] </
33880 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
33890 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
338a0 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ld()] </li>.**  
338b0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
338c0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
338d0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   </li>.** </ul>.
338e0 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64  **.** The only d
338f0 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61  ifference is tha
33900 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c  t the public sql
33910 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f  ite3_XXX functio
33920 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a  ns enumerated.**
33930 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20   above silently 
33940 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63  ignore any invoc
33950 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73  ations that pass
33960 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
33970 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
33980 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64  valid mutex hand
33990 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  le. The implemen
339a0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d  tations of the m
339b0 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a  ethods defined.*
339c0 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  * by this struct
339d0 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75  ure are not requ
339e0 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74  ired to handle t
339f0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65  his case, the re
33a00 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73  sults.** of pass
33a10 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
33a20 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
33a30 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64  valid mutex hand
33a40 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  le are undefined
33a50 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20  .** (i.e. it is 
33a60 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72  acceptable to pr
33a70 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65  ovide an impleme
33a80 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67  ntation that seg
33a90 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20  faults if.** it 
33aa0 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c  is passed a NULL
33ab0 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79   pointer)..*/.ty
33ac0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
33ad0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
33ae0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
33af0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
33b00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
33b10 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
33b20 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
33b30 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
33b40 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
33b50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
33b60 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
33b70 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
33b80 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
33b90 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
33ba0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
33bb0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
33bc0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
33bd0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
33be0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
33bf0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
33c00 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
33c10 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
33c20 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
33c30 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
33c40 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
33c50 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
33c60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33c70 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
33c80 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
33c90 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e  H17080} <S20130>
33ca0 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
33cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
33cc0 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
33cd0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
33ce0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
33cf0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
33d00 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
33d10 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
33d20 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53  . {H17081} The S
33d30 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65  QLite core.** ne
33d40 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72  ver uses these r
33d50 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69  outines except i
33d60 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28  nside an assert(
33d70 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  ) and applicatio
33d80 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65  ns.** are advise
33d90 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20  d to follow the 
33da0 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65  lead of the core
33db0 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20  .  {H17082} The 
33dc0 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
33dd0 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
33de0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
33df0 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
33e00 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
33e10 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
33e20 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31  DEBUG flag.  {A1
33e30 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d  7087} External m
33e40 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
33e50 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79  ions.** are only
33e60 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
33e70 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69  vide these routi
33e80 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45  nes if SQLITE_DE
33e90 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65  BUG is.** define
33ea0 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20  d and if NDEBUG 
33eb0 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a  is not defined..
33ec0 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54  **.** {H17083} T
33ed0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
33ee0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65  ould return true
33ef0 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e   if the mutex in
33f00 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a   their argument.
33f10 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f  ** is held or no
33f20 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69  t held, respecti
33f30 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c  vely, by the cal
33f40 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a  ling thread..**.
33f50 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20  ** {X17084} The 
33f60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
33f70 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
33f80 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69  o provided versi
33f90 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
33fa0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63  routines that ac
33fb0 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20  tually work. If 
33fc0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
33fd0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  on does not prov
33fe0 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76  ide working.** v
33ff0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
34000 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68   routines, it sh
34010 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72  ould at least pr
34020 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74  ovide stubs that
34030 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72   always.** retur
34040 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f  n true so that o
34050 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20  ne does not get 
34060 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69  spurious asserti
34070 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
34080 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74  ** {H17085} If t
34090 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
340a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
340b0 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
340c0 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
340d0 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
340e0 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44   return 1.  {END
340f0 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75  } This seems cou
34100 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73  nter-intuitive s
34110 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20  ince.** clearly 
34120 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74  the mutex cannot
34130 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64   be held if it d
34140 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20  oes not exist.  
34150 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72  But the.** the r
34160 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20  eason the mutex 
34170 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
34180 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75  s because the bu
34190 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73  ild is not.** us
341a0 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e  ing mutexes.  An
341b0 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74  d we do not want
341c0 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f   the assert() co
341d0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
341e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
341f0 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20  mutex_held() to 
34200 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a  fail, so a non-z
34210 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a  ero return is.**
34220 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
34230 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b   thing to do.  {
34240 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69  H17086} The sqli
34250 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
34260 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
34270 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
34280 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
34290 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
342a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
342b0 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
342c0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
342d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
342e0 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
342f0 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
34300 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79  PI3REF: Mutex Ty
34310 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31  pes {H17001} <H1
34320 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7000>.**.** The 
34330 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
34340 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
34350 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
34360 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
34370 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
34380 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
34390 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
343a0 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75  set of static mu
343b0 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65  texes may change
343c0 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65   from one SQLite
343d0 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a   release to the.
343e0 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
343f0 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
34400 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ride the built-i
34410 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75  n mutex logic mu
34420 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65  st be.** prepare
34430 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65  d to accommodate
34440 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
34450 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23  ic mutexes..*/.#
34460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
34470 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
34480 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
34490 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
344a0 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
344b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
344c0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
344d0 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
344e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
344f0 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
34500 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
34510 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
34520 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
34530 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
34540 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  /* sqlite3_relea
34550 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23  se_memory() */.#
34560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
34570 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20  TEX_STATIC_PRNG 
34580 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
34590 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23  e3_random() */.#
345a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
345b0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20  TEX_STATIC_LRU  
345c0 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70       6  /* lru p
345d0 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66  age list */.#def
345e0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
345f0 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20  _STATIC_LRU2    
34600 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    7  /* lru page
34610 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   list */../*.** 
34620 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
34630 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72  ve the mutex for
34640 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
34650 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20  ection {H17002} 
34660 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H17000>.**.** T
34670 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
34680 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34690 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
346a0 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ex] object that 
346b0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61  .** serializes a
346c0 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61  ccess to the [da
346d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
346e0 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  n] given in the 
346f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e  argument.** when
34700 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
34710 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69  mode] is Seriali
34720 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  zed..** If the [
34730 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
34740 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  is Single-thread
34750 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   or Multi-thread
34760 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f   then this.** ro
34770 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
34780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
34790 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
347a0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
347b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
347c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77  ** CAPI3REF: Low
347d0 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f  -Level Control O
347e0 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  f Database Files
347f0 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30   {H11300} <S3080
34800 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31  0>.**.** {H11301
34810 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
34820 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
34830 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
34840 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20   direct call to 
34850 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74  the.** xFileCont
34860 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74  rol method for t
34870 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
34880 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
34890 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
348a0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
348b0 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69  atabase identifi
348c0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
348d0 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33   argument. {H113
348e0 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20  02} The.** name 
348f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
34900 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  is the name assi
34910 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61  gned to the data
34920 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c  base by the.** <
34930 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74  a href="lang_att
34940 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48  ach.html">ATTACH
34950 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  </a> SQL command
34960 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65   that opened the
34970 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48  .** database. {H
34980 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f  11303} To contro
34990 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  l the main datab
349a0 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68  ase file, use th
349b0 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a  e name "main".**
349c0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
349d0 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65  er. {H11304} The
349e0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
349f0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
34a00 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
34a10 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63  are passed direc
34a20 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74  tly through to t
34a30 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
34a40 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ird parameters o
34a50 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f  f.** the xFileCo
34a60 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b  ntrol method.  {
34a70 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75  H11305} The retu
34a80 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
34a90 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20  xFileControl.** 
34aa0 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74  method becomes t
34ab0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34ac0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
34ad0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20  .**.** {H11306} 
34ae0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
34af0 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65  rameter (zDbName
34b00 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  ) does not match
34b10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79   the name of any
34b20 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73  .** open databas
34b30 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c  e file, then SQL
34b40 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74  ITE_ERROR is ret
34b50 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20  urned. {H11307} 
34b60 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f  This error.** co
34b70 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62  de is not rememb
34b80 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f  ered and will no
34b90 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79  t be recalled by
34ba0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
34bb0 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  e()].** or [sqli
34bc0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b  te3_errmsg()]. {
34bd0 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65  A11308} The unde
34be0 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74  rlying xFileCont
34bf0 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74  rol method might
34c00 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  .** also return 
34c10 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b  SQLITE_ERROR.  {
34c20 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73  A11309} There is
34c30 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69   no way to disti
34c40 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a  nguish between.*
34c50 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a  * an incorrect z
34c60 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51  DbName and an SQ
34c70 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72  LITE_ERROR retur
34c80 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72  n from the under
34c90 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f  lying.** xFileCo
34ca0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45  ntrol method. {E
34cb0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ND}.**.** See al
34cc0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  so: [SQLITE_FCNT
34cd0 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a  L_LOCKSTATE].*/.
34ce0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  int sqlite3_file
34cf0 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33  _control(sqlite3
34d00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
34d10 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20  DbName, int op, 
34d20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
34d30 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67  API3REF: Testing
34d40 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34   Interface {H114
34d50 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a  00} <S30800>.**.
34d60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
34d70 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e  est_control() in
34d80 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
34d90 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65  to read out inte
34da0 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66  rnal.** state of
34db0 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69   SQLite and to i
34dc0 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74  nject faults int
34dd0 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73  o SQLite for tes
34de0 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73  ting.** purposes
34df0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
34e00 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65  ameter is an ope
34e10 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74  ration code that
34e20 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74   determines.** t
34e30 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69  he number, meani
34e40 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f  ng, and operatio
34e50 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75  n of all subsequ
34e60 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  ent parameters..
34e70 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
34e80 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20  face is not for 
34e90 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69  use by applicati
34ea0 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20  ons.  It exists 
34eb0 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65  solely.** for ve
34ec0 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72  rifying the corr
34ed0 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  ect operation of
34ee0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
34ef0 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a  ary.  Depending.
34f00 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51  ** on how the SQ
34f10 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20  Lite library is 
34f20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69  compiled, this i
34f30 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e  nterface might n
34f40 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  ot exist..**.** 
34f50 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
34f60 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64  he operation cod
34f70 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e  es, their meanin
34f80 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65  gs, the paramete
34f90 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c  rs.** they take,
34fa0 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64   and what they d
34fb0 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63  o are all subjec
34fc0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
34fd0 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55  out notice..** U
34fe0 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68  nlike most of th
34ff0 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68  e SQLite API, th
35000 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  is function is n
35010 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
35020 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73  .** operate cons
35030 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e  istently from on
35040 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
35050 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71   next..*/.int sq
35060 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
35070 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  ol(int op, ...);
35080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35090 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66  : Testing Interf
350a0 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f  ace Operation Co
350b0 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31  des {H11410} <H1
350c0 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1400>.**.** Thes
350d0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
350e0 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74  the valid operat
350f0 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74  ion code paramet
35100 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74  ers used.** as t
35110 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35120 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65  t to [sqlite3_te
35130 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a  st_control()]..*
35140 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d  *.** These param
35150 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20  eters and their 
35160 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62  meanings are sub
35170 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a  ject to change.*
35180 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  * without notice
35190 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20  .  These values 
351a0 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20  are for testing 
351b0 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a  purposes only..*
351c0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
351d0 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e  hould not use an
351e0 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  y of these param
351f0 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20  eters or the.** 
35200 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f  [sqlite3_test_co
35210 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
35220 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
35230 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
35240 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20  RNG_SAVE        
35250 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
35260 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
35270 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20  L_PRNG_RESTORE  
35280 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
35290 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
352a0 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20  CTRL_PRNG_RESET 
352b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
352c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
352d0 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54  ESTCTRL_BITVEC_T
352e0 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  EST             
352f0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
35300 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54  E_TESTCTRL_FAULT
35310 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20  _INSTALL        
35320 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
35330 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45  LITE_TESTCTRL_BE
35340 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b  NIGN_MALLOC_HOOK
35350 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65  S     10.#define
35360 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
35370 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20  _PENDING_BYTE   
35380 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
35390 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
353a0 69 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74  ite Runtime Stat
353b0 75 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30  us {H17200} <S60
353c0 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
353d0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
353e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
353f0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75  d to retrieve ru
35400 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66  ntime status inf
35410 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
35420 74 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63  t the preformanc
35430 65 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64  e of SQLite, and
35440 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72   optionally to r
35450 65 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20  eset various.** 
35460 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e  highwater marks.
35470 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
35480 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
35490 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  er code for.** t
354a0 68 65 20 73 70 65 63 69 66 69 63 20 70 61 72 61  he specific para
354b0 6d 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65  meter to measure
354c0 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e  .  Recognized in
354d0 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61  teger codes.** a
354e0 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b  re of the form [
354f0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45  SQLITE_STATUS_ME
35500 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49  MORY_USED | SQLI
35510 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a  TE_STATUS_...]..
35520 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76  ** The current v
35530 61 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61  alue of the para
35540 6d 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  meter is returne
35550 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74  d into *pCurrent
35560 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74  ..** The highest
35570 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20   recorded value 
35580 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  is returned in *
35590 70 48 69 67 68 77 61 74 65 72 2e 20 20 49 66 20  pHighwater.  If 
355a0 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67  the.** resetFlag
355b0 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
355c0 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72  he highest recor
355d0 64 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74  d value is reset
355e0 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68   after.** *pHigh
355f0 77 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e  water is written
35600 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72  . Some parameter
35610 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20  s do not record 
35620 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76  the highest.** v
35630 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65  alue.  For those
35640 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e   parameters.** n
35650 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65  othing is writte
35660 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74  n into *pHighwat
35670 65 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74  er and the reset
35680 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e  Flag is ignored.
35690 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65  .** Other parame
356a0 74 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79  ters record only
356b0 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d   the highwater m
356c0 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20  ark and not the 
356d0 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  current.** value
356e0 2e 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74  .  For these lat
356f0 74 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e  ter parameters n
35700 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65  othing is writte
35710 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74  n into *pCurrent
35720 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
35730 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c  tine returns SQL
35740 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73  ITE_OK on succes
35750 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f  s and a non-zero
35760 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
35770 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   on failure..**.
35780 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
35790 69 73 20 74 68 72 65 61 64 73 61 66 65 20 62 75  is threadsafe bu
357a0 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e  t is not atomic.
357b0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63    This routine c
357c0 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69  an.** called whi
357d0 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61 64 73  le other threads
357e0 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 68 65   are running the
357f0 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65 72 65   same or differe
35800 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  nt SQLite.** int
35810 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
35820 72 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  r the values ret
35830 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 72 65  urned in *pCurre
35840 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68  nt and.** *pHigh
35850 77 61 74 65 72 20 72 65 66 6c 65 63 74 20 74 68  water reflect th
35860 65 20 73 74 61 74 75 73 20 6f 66 20 53 51 4c 69  e status of SQLi
35870 74 65 20 61 74 20 64 69 66 66 65 72 65 6e 74 20  te at different 
35880 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a  points in time.*
35890 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f 73 73  * and it is poss
358a0 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  ible that anothe
358b0 72 20 74 68 72 65 61 64 20 6d 69 67 68 74 20 63  r thread might c
358c0 68 61 6e 67 65 20 74 68 65 20 70 61 72 61 6d 65  hange the parame
358d0 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65  ter.** in betwee
358e0 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68 65 6e  n the times when
358f0 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 20 2a   *pCurrent and *
35900 70 48 69 67 68 77 61 74 65 72 20 61 72 65 20 77  pHighwater are w
35910 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65  ritten..**.** Se
35920 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
35930 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f  _db_status()].*/
35940 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
35950 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
35960 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70 2c 20  _status(int op, 
35970 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c 20 69  int *pCurrent, i
35980 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72 2c 20  nt *pHighwater, 
35990 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
359a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
359b0 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74  : Status Paramet
359c0 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c 48 31  ers {H17250} <H1
359d0 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  7200>.** EXPERIM
359e0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
359f0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
35a00 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20 76 61  nts designate va
35a10 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 20 73  rious run-time s
35a20 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73  tatus parameters
35a30 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
35a40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
35a50 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a  ite3_status()]..
35a60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
35a70 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
35a80 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e  MEMORY_USED</dt>
35a90 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
35aa0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 75  ameter is the cu
35ab0 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20  rrent amount of 
35ac0 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 20 6f  memory checked o
35ad0 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ut.** using [sql
35ae0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
35af0 65 69 74 68 65 72 20 64 69 72 65 63 74 6c 79 20  either directly 
35b00 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e 20 20  or indirectly.  
35b10 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e  The.** figure in
35b20 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d 61 64  cludes calls mad
35b30 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e to [sqlite3_ma
35b40 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 20 61  lloc()] by the a
35b50 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e  pplication.** an
35b60 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  d internal memor
35b70 79 20 75 73 61 67 65 20 62 79 20 74 68 65 20 53  y usage by the S
35b80 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
35b90 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a  Scratch memory.*
35ba0 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  * controlled by 
35bb0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
35bc0 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75 78 69  CRATCH] and auxi
35bd0 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63 68 65  liary page-cache
35be0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72  .** memory contr
35bf0 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45  olled by [SQLITE
35c00 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
35c10 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  E] is not includ
35c20 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61  ed in.** this pa
35c30 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 61 6d  rameter.  The am
35c40 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 69 73  ount returned is
35c50 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68 65 20   the sum of the 
35c60 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69  allocation.** si
35c70 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65 64 20  zes as reported 
35c80 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d 65 74  by the xSize met
35c90 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  hod in [sqlite3_
35ca0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64  mem_methods].</d
35cb0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
35cc0 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f  ITE_STATUS_MALLO
35cd0 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  C_SIZE</dt>.** <
35ce0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
35cf0 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  r records the la
35d00 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  rgest memory all
35d10 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a  ocation request.
35d20 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ** handed to [sq
35d30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
35d40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
35d50 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 69 72  loc()] (or their
35d60 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 71 75  .** internal equ
35d70 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79  ivalents).  Only
35d80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
35d90 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70  ned in the.** *p
35da0 48 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65  Highwater parame
35db0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
35dc0 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20  status()] is of 
35dd0 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54  interest.  .** T
35de0 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e  he value written
35df0 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72   into the *pCurr
35e00 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  ent parameter is
35e10 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
35e20 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
35e30 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43  E_STATUS_PAGECAC
35e40 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20  HE_USED</dt>.** 
35e50 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
35e60 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  er returns the n
35e70 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 75  umber of pages u
35e80 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a  sed out of the.*
35e90 2a 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d  * [pagecache mem
35ea0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74  ory allocator] t
35eb0 68 61 74 20 77 61 73 20 63 6f 6e 66 69 67 75 72  hat was configur
35ec0 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51  ed using .** [SQ
35ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
35ee0 43 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20  CACHE].  The.** 
35ef0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
35f00 73 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20  s in pages, not 
35f10 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a  in bytes.</dd>.*
35f20 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
35f30 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45  STATUS_PAGECACHE
35f40 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a  _OVERFLOW</dt>.*
35f50 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
35f60 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65  eter returns the
35f70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35f80 20 6f 66 20 70 61 67 65 20 63 61 63 68 65 0a 2a   of page cache.*
35f90 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69  * allocation whi
35fa0 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ch could not be 
35fb0 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74 68  statisfied by th
35fc0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
35fd0 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62  _PAGECACHE].** b
35fe0 75 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20  uffer and where 
35ff0 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c  forced to overfl
36000 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ow to [sqlite3_m
36010 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a  alloc()].  The.*
36020 2a 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  * returned value
36030 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61   includes alloca
36040 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66  tions that overf
36050 6c 6f 77 65 64 20 62 65 63 61 75 73 65 20 74 68  lowed because th
36060 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20  ey.** where too 
36070 6c 61 72 67 65 20 28 74 68 65 79 20 77 65 72 65  large (they were
36080 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
36090 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20   "sz" parameter 
360a0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  to.** [SQLITE_CO
360b0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 29  NFIG_PAGECACHE])
360c0 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73   and allocations
360d0 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65 64   that overflowed
360e0 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73   because.** no s
360f0 70 61 63 65 20 77 61 73 20 6c 65 66 74 20 69 6e  pace was left in
36100 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e   the page cache.
36110 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
36120 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
36130 47 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74  GECACHE_SIZE</dt
36140 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36150 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20  rameter records 
36160 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f  the largest memo
36170 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
36180 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20  quest.** handed 
36190 74 6f 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65  to [pagecache me
361a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e  mory allocator].
361b0 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65    Only the value
361c0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65   returned in the
361d0 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20  .** *pHighwater 
361e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
361f0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20  lite3_status()] 
36200 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20  is of interest. 
36210 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77   .** The value w
36220 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
36230 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65  *pCurrent parame
36240 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ter is undefined
36250 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
36260 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53  >SQLITE_STATUS_S
36270 43 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e  CRATCH_USED</dt>
36280 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
36290 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
362a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c  he number of all
362b0 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 20 6f 75  ocations used ou
362c0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72  t of the.** [scr
362d0 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  atch memory allo
362e0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65  cator] configure
362f0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49  d using.** [SQLI
36300 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
36310 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72  H].  The value r
36320 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20 61 6c  eturned is in al
36330 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a  locations, not.*
36340 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 53 69 6e  * in bytes.  Sin
36350 63 65 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  ce a single thre
36360 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65  ad may only have
36370 20 6f 6e 65 20 73 63 72 61 74 63 68 20 61 6c 6c   one scratch all
36380 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74  ocation.** outst
36390 61 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 2c 20  anding at time, 
363a0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 61  this parameter a
363b0 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 68 65 20  lso reports the 
363c0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
363d0 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 61 74  s.** using scrat
363e0 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 68 65  ch memory at the
363f0 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e   same time.</dd>
36400 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
36410 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48  E_STATUS_SCRATCH
36420 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a  _OVERFLOW</dt>.*
36430 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
36440 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65  eter returns the
36450 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36460 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
36470 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
36480 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74   which could not
36490 20 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62   be statisfied b
364a0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  y the [SQLITE_CO
364b0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a  NFIG_SCRATCH].**
364c0 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72   buffer and wher
364d0 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72  e forced to over
364e0 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33  flow to [sqlite3
364f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
36500 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72   values.** retur
36510 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f 76 65 72  ned include over
36520 66 6c 6f 77 73 20 62 65 63 61 75 73 65 20 74 68  flows because th
36530 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f  e requested allo
36540 63 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a  cation was too.*
36550 2a 20 6c 61 72 67 65 72 20 28 74 68 61 74 20 69  * larger (that i
36560 73 2c 20 62 65 63 61 75 73 65 20 74 68 65 20 72  s, because the r
36570 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74  equested allocat
36580 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 72 20 74  ion was larger t
36590 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20  han the.** "sz" 
365a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 53 51  parameter to [SQ
365b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
365c0 54 43 48 5d 29 20 61 6e 64 20 62 65 63 61 75 73  TCH]) and becaus
365d0 65 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  e no scratch buf
365e0 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72  fer.** slots wer
365f0 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  e available..** 
36600 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
36610 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43  SQLITE_STATUS_SC
36620 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a  RATCH_SIZE</dt>.
36630 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
36640 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68  meter records th
36650 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79  e largest memory
36660 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
36670 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f  est.** handed to
36680 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79   [scratch memory
36690 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e   allocator].  On
366a0 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ly the value ret
366b0 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  urned in the.** 
366c0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61  *pHighwater para
366d0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
366e0 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f  3_status()] is o
366f0 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a  f interest.  .**
36700 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74   The value writt
36710 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75  en into the *pCu
36720 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20  rrent parameter 
36730 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  is undefined.</d
36740 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
36750 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45  ITE_STATUS_PARSE
36760 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20  R_STACK</dt>.** 
36770 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
36780 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 64  er records the d
36790 65 65 70 65 73 74 20 70 61 72 73 65 72 20 73 74  eepest parser st
367a0 61 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79  ack.  It is only
367b0 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  .** meaningful i
367c0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
367d0 69 6c 65 64 20 77 69 74 68 20 5b 59 59 54 52 41  iled with [YYTRA
367e0 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 54 48 5d  CKMAXSTACKDEPTH]
367f0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
36800 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74 75 73  **.** New status
36810 20 70 61 72 61 6d 65 74 65 72 73 20 6d 61 79 20   parameters may 
36820 62 65 20 61 64 64 65 64 20 66 72 6f 6d 20 74 69  be added from ti
36830 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23  me to time..*/.#
36840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
36850 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44  ATUS_MEMORY_USED
36860 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
36870 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
36880 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53 45 44  S_PAGECACHE_USED
36890 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
368a0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50   SQLITE_STATUS_P
368b0 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f  AGECACHE_OVERFLO
368c0 57 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51  W   2.#define SQ
368d0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
368e0 54 43 48 5f 55 53 45 44 20 20 20 20 20 20 20 20  TCH_USED        
368f0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
36900 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48  E_STATUS_SCRATCH
36910 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 20 34 0a  _OVERFLOW     4.
36920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
36930 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a  TATUS_MALLOC_SIZ
36940 45 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65  E          5.#de
36950 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
36960 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 20  US_PARSER_STACK 
36970 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
36980 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
36990 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 20 20  PAGECACHE_SIZE  
369a0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
369b0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52  QLITE_STATUS_SCR
369c0 41 54 43 48 5f 53 49 5a 45 20 20 20 20 20 20 20  ATCH_SIZE       
369d0 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
369e0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
369f0 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 75 73 20  nnection Status 
36a00 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 32 30 30  {H17500} <S60200
36a10 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
36a20 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  L.**.** This int
36a30 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
36a40 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69  o retrieve runti
36a50 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d  me status inform
36a60 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20  ation .** about 
36a70 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 61 62 61  a single [databa
36a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
36a90 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
36aa0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 64 61  ent is the.** da
36ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36ac0 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69  n object to be i
36ad0 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
36ae0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
36af0 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 61 72 61  t.** is the para
36b00 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 72 72 6f  meter to interro
36b10 67 61 74 65 2e 20 20 43 75 72 72 65 6e 74 6c 79  gate.  Currently
36b20 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77  , the only allow
36b30 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20  ed value.** for 
36b40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
36b50 65 74 65 72 20 69 73 20 5b 53 51 4c 49 54 45 5f  eter is [SQLITE_
36b60 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49  DBSTATUS_LOOKASI
36b70 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64  DE_USED]..** Add
36b80 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20  itional options 
36b90 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65  will likely appe
36ba0 61 72 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ar in future rel
36bb0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
36bc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72 72 65  .**.** The curre
36bd0 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  nt value of the 
36be0 72 65 71 75 65 73 74 65 64 20 70 61 72 61 6d 65  requested parame
36bf0 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69  ter is written i
36c00 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64  nto *pCur.** and
36c10 20 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73   the highest ins
36c20 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65  tantaneous value
36c30 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
36c40 20 2a 70 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a   *pHiwtr.  If.**
36c50 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 73   the resetFlg is
36c60 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
36c70 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74 61  highest instanta
36c80 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 0a 2a  neous value is.*
36c90 2a 20 72 65 73 65 74 20 62 61 63 6b 20 64 6f 77  * reset back dow
36ca0 6e 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  n to the current
36cb0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65   value..**.** Se
36cc0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
36cd0 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b  _status()] and [
36ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61  sqlite3_stmt_sta
36cf0 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  tus()]..*/.SQLIT
36d00 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
36d10 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  nt sqlite3_db_st
36d20 61 74 75 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  atus(sqlite3*, i
36d30 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72  nt op, int *pCur
36d40 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 2c 20 69  , int *pHiwtr, i
36d50 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f  nt resetFlg);../
36d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
36d70 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73  tatus Parameters
36d80 20 66 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f   for database co
36d90 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37 35 32  nnections {H1752
36da0 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45  0} <H17500>.** E
36db0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
36dc0 2a 20 53 74 61 74 75 73 20 76 65 72 62 73 20 66  * Status verbs f
36dd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  or [sqlite3_db_s
36de0 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tatus()]..**.** 
36df0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
36e00 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b  TE_DBSTATUS_LOOK
36e10 41 53 49 44 45 5f 55 53 45 44 3c 2f 64 74 3e 0a  ASIDE_USED</dt>.
36e20 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
36e30 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
36e40 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b  e number of look
36e50 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 73 6c 6f  aside memory slo
36e60 74 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ts currently.** 
36e70 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f 64 64  checked out.</dd
36e80 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
36e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 53  efine SQLITE_DBS
36ea0 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f  TATUS_LOOKASIDE_
36eb0 55 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a  USED     0.../*.
36ec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
36ed0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
36ee0 53 74 61 74 75 73 20 7b 48 31 37 35 35 30 7d 20  Status {H17550} 
36ef0 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S60200>.** EXPE
36f00 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45  RIMENTAL.**.** E
36f10 61 63 68 20 70 72 65 70 61 72 65 64 20 73 74 61  ach prepared sta
36f20 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69 6e 73  tement maintains
36f30 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c   various.** [SQL
36f40 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53  ITE_STMTSTATUS_S
36f50 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 73 5d 20  ORT | counters] 
36f60 74 68 61 74 20 6d 65 61 73 75 72 65 20 74 68 65  that measure the
36f70 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 69   number.** of ti
36f80 6d 65 73 20 69 74 20 68 61 73 20 70 65 72 66 6f  mes it has perfo
36f90 72 6d 65 64 20 73 70 65 63 69 66 69 63 20 6f 70  rmed specific op
36fa0 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 65 73 65  erations.  These
36fb0 20 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a 2a 2a   counters can.**
36fc0 20 62 65 20 75 73 65 64 20 74 6f 20 6d 6f 6e 69   be used to moni
36fd0 74 6f 72 20 74 68 65 20 70 65 72 66 6f 72 6d 61  tor the performa
36fe0 6e 63 65 20 63 68 61 72 61 63 74 65 72 69 73 74  nce characterist
36ff0 69 63 73 20 6f 66 20 74 68 65 20 70 72 65 70 61  ics of the prepa
37000 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
37010 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
37020 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   if the number o
37030 66 20 74 61 62 6c 65 20 73 74 65 70 73 20 67 72  f table steps gr
37040 65 61 74 6c 79 20 65 78 63 65 65 64 73 0a 2a 2a  eatly exceeds.**
37050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
37060 61 62 6c 65 20 73 65 61 72 63 68 65 73 20 6f 72  able searches or
37070 20 72 65 73 75 6c 74 20 72 6f 77 73 2c 20 74 68   result rows, th
37080 61 74 20 77 6f 75 6c 64 20 74 65 6e 64 20 74 6f  at would tend to
37090 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74 68 61   indicate.** tha
370a0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
370b0 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 69 6e  tatement is usin
370c0 67 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  g a full table s
370d0 63 61 6e 20 72 61 74 68 65 72 20 74 68 61 6e 0a  can rather than.
370e0 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20 0a 2a  ** an index.  .*
370f0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
37100 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ace is used to r
37110 65 74 72 69 65 76 65 20 61 6e 64 20 72 65 73 65  etrieve and rese
37120 74 20 63 6f 75 6e 74 65 72 20 76 61 6c 75 65 73  t counter values
37130 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65 70   from.** a [prep
37140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
37150 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
37160 6d 65 6e 74 20 69 73 20 74 68 65 20 70 72 65 70  ment is the prep
37170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
37180 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69  * object to be i
37190 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
371a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
371b0 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  t.** is an integ
371c0 65 72 20 63 6f 64 65 20 66 6f 72 20 61 20 73 70  er code for a sp
371d0 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 53  ecific [SQLITE_S
371e0 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 7c  TMTSTATUS_SORT |
371f0 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20   counter].** to 
37200 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  be interrogated.
37210 20 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74   .** The current
37220 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65   value of the re
37230 71 75 65 73 74 65 64 20 63 6f 75 6e 74 65 72 20  quested counter 
37240 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
37250 49 66 20 74 68 65 20 72 65 73 65 74 46 6c 67 20  If the resetFlg 
37260 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
37270 65 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65 73  e counter is res
37280 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 65 72  et to zero after
37290 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
372a0 63 65 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  ce call returns.
372b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
372c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
372d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
372e0 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a  _db_status()]..*
372f0 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
37300 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
37310 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 73 71  3_stmt_status(sq
37320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
37330 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 6c 67   op,int resetFlg
37340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37350 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d  EF: Status Param
37360 65 74 65 72 73 20 66 6f 72 20 70 72 65 70 61 72  eters for prepar
37370 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 7b 48  ed statements {H
37380 31 37 35 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a  17570} <H17550>.
37390 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
373a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 65 70  **.** These prep
373b0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 20  rocessor macros 
373c0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
373d0 6f 64 65 73 20 74 68 61 74 20 6e 61 6d 65 20 63  odes that name c
373e0 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73  ounter.** values
373f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
37400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
37410 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74  mt_status()] int
37420 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d  erface..** The m
37430 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
37440 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 73 20  arious counters 
37450 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
37460 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
37470 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41  t>SQLITE_STMTSTA
37480 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45  TUS_FULLSCAN_STE
37490 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
374a0 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  is is the number
374b0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 53   of times that S
374c0 51 4c 69 74 65 20 68 61 73 20 73 74 65 70 70 65  QLite has steppe
374d0 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20  d forward in.** 
374e0 61 20 74 61 62 6c 65 20 61 73 20 70 61 72 74 20  a table as part 
374f0 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20  of a full table 
37500 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d  scan.  Large num
37510 62 65 72 73 20 66 6f 72 20 74 68 69 73 20 63 6f  bers for this co
37520 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64  unter.** may ind
37530 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e 69 74  icate opportunit
37540 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  ies for performa
37550 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20  nce improvement 
37560 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65  through .** care
37570 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63  ful use of indic
37580 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
37590 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54  dt>SQLITE_STMTST
375a0 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a  ATUS_SORT</dt>.*
375b0 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68  * <dd>This is th
375c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72 74  e number of sort
375d0 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74   operations that
375e0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 2e 0a   have occurred..
375f0 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ** A non-zero va
37600 6c 75 65 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  lue in this coun
37610 74 65 72 20 6d 61 79 20 69 6e 64 69 63 61 74 65  ter may indicate
37620 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20   an opportunity 
37630 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e  to.** improvemen
37640 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 68  t performance th
37650 72 6f 75 67 68 20 63 61 72 65 66 75 6c 20 75 73  rough careful us
37660 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64  e of indices.</d
37670 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
37680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37690 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c  _STMTSTATUS_FULL
376a0 53 43 41 4e 5f 53 54 45 50 20 20 20 20 20 31 0a  SCAN_STEP     1.
376b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
376c0 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 20  TMTSTATUS_SORT  
376d0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 0a 2f              2../
376e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
376f0 75 73 74 6f 6d 20 50 61 67 65 20 43 61 63 68 65  ustom Page Cache
37700 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52   Object.** EXPER
37710 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
37720 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  e sqlite3_pcache
37730 20 74 79 70 65 20 69 73 20 6f 70 61 71 75 65 2e   type is opaque.
37740 20 20 49 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e    It is implemen
37750 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c  ted by.** the pl
37760 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20  uggable module. 
37770 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
37780 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67   has no knowledg
37790 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65  e of.** its size
377a0 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 74 72   or internal str
377b0 75 63 74 75 72 65 20 61 6e 64 20 6e 65 76 65 72  ucture and never
377c0 20 64 65 61 6c 73 20 77 69 74 68 20 74 68 65 0a   deals with the.
377d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  ** sqlite3_pcach
377e0 65 20 6f 62 6a 65 63 74 20 65 78 63 65 70 74 20  e object except 
377f0 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70  by holding and p
37800 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a  assing pointers.
37810 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 63 74  ** to the object
37820 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c  ..**.** See [sql
37830 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
37840 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ods] for additio
37850 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
37860 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
37870 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  ct sqlite3_pcach
37880 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  e sqlite3_pcache
37890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
378a0 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 44  F: Application D
378b0 65 66 69 6e 65 64 20 50 61 67 65 20 43 61 63 68  efined Page Cach
378c0 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  e..** EXPERIMENT
378d0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  AL.**.** The [sq
378e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
378f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
37900 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72  CHE], ...) inter
37910 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69  face can.** regi
37920 73 74 65 72 20 61 6e 20 61 6c 74 65 72 6e 61 74  ster an alternat
37930 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69  ive page cache i
37940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79  mplementation by
37950 20 70 61 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a   passing in an .
37960 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
37970 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  he sqlite3_pcach
37980 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 63 74  e_methods struct
37990 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74  ure. The majorit
379a0 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 65 61  y of the .** hea
379b0 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79  p memory used by
379c0 20 73 71 6c 69 74 65 20 69 73 20 75 73 65 64 20   sqlite is used 
379d0 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68  by the page cach
379e0 65 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 20  e to cache data 
379f0 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f  read .** from, o
37a00 72 20 72 65 61 64 79 20 74 6f 20 62 65 20 77 72  r ready to be wr
37a10 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 64 61  itten to, the da
37a20 74 61 62 61 73 65 20 66 69 6c 65 2e 20 42 79 20  tabase file. By 
37a30 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a  implementing a .
37a40 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63  ** custom page c
37a50 61 63 68 65 20 75 73 69 6e 67 20 74 68 69 73 20  ache using this 
37a60 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  API, an applicat
37a70 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20  ion can control 
37a80 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 73 65  more .** precise
37a90 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ly the amount of
37aa0 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64   memory consumed
37ab0 20 62 79 20 73 71 6c 69 74 65 2c 20 74 68 65 20   by sqlite, the 
37ac0 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a  way in which .**
37ad0 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 69 73 20   said memory is 
37ae0 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 72 65  allocated and re
37af0 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68 65 20  leased, and the 
37b00 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20 74 6f  policies used to
37b10 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20 65   .** determine e
37b20 78 61 63 74 6c 79 20 77 68 69 63 68 20 70 61 72  xactly which par
37b30 74 73 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  ts of a database
37b40 20 66 69 6c 65 20 61 72 65 20 63 61 63 68 65 64   file are cached
37b50 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77   and for .** how
37b60 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   long..**.** The
37b70 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
37b80 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 63   structure are c
37b90 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 6e 74 65  opied to an inte
37ba0 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79 20 73  rnal buffer by s
37bb0 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  qlite.** within 
37bc0 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  the call to [sql
37bd0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a 2a 2a  ite3_config]..**
37be0 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 29 20  .** The xInit() 
37bf0 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64  method is called
37c00 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
37c10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37c20 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a  initialize()].**
37c30 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f   (usually only o
37c40 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 6c  nce during the l
37c50 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 70  ifetime of the p
37c60 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73 20 70  rocess). It is p
37c70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 79 20  assed.** a copy 
37c80 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  of the sqlite3_p
37c90 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e 70 41  cache_methods.pA
37ca0 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63 61 6e  rg value. It can
37cb0 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 0a   be used to set.
37cc0 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 74 72  ** up global str
37cd0 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75 74 65  uctures and mute
37ce0 78 65 73 20 72 65 71 75 69 72 65 64 20 62 79 20  xes required by 
37cf0 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67 65 20  the custom page 
37d00 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d  cache .** implem
37d10 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 78 53  entation. The xS
37d20 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 6f 64  hutdown() method
37d30 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   is called from 
37d40 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71 6c 69  within .** [sqli
37d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c  te3_shutdown()],
37d60 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   if the applicat
37d70 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 69 73  ion invokes this
37d80 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62 65 20   API. It can be 
37d90 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65 61 6e  used.** to clean
37da0 20 75 70 20 61 6e 79 20 6f 75 74 73 74 61 6e 64   up any outstand
37db0 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20 62 65  ing resources be
37dc0 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73 68 75  fore process shu
37dd0 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 69 72  tdown, if requir
37de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43  ed..**.** The xC
37df0 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64 20 69  reate() method i
37e00 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72  s used to constr
37e10 75 63 74 20 61 20 6e 65 77 20 63 61 63 68 65 20  uct a new cache 
37e20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a 2a 2a  instance. The.**
37e30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
37e40 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 74 68 65  , szPage, is the
37e50 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
37e60 66 20 74 68 65 20 70 61 67 65 73 20 74 68 61 74  f the pages that
37e70 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 6c 6f   must.** be allo
37e80 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61 63  cated by the cac
37e90 68 65 2e 20 73 7a 50 61 67 65 20 77 69 6c 6c 20  he. szPage will 
37ea0 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f  not be a power o
37eb0 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20 73 65  f two. The.** se
37ec0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 62  cond argument, b
37ed0 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 74 72  Purgeable, is tr
37ee0 75 65 20 69 66 20 74 68 65 20 63 61 63 68 65 20  ue if the cache 
37ef0 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 77 69  being created wi
37f00 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f  ll.** be used to
37f10 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20   cache database 
37f20 70 61 67 65 73 20 72 65 61 64 20 66 72 6f 6d 20  pages read from 
37f30 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20 6f 6e  a file stored on
37f40 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 61 6c   disk, or.** fal
37f50 73 65 20 69 66 20 69 74 20 69 73 20 75 73 65 64  se if it is used
37f60 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72   for an in-memor
37f70 79 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20  y database. The 
37f80 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
37f90 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  tion.** does not
37fa0 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e 79 74   have to do anyt
37fb0 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62 61 73  hing special bas
37fc0 65 64 20 6f 6e 20 74 68 65 20 76 61 6c 75 65 20  ed on the value 
37fd0 6f 66 20 62 50 75 72 67 65 61 62 6c 65 2c 0a 2a  of bPurgeable,.*
37fe0 2a 20 69 74 20 69 73 20 70 75 72 65 6c 79 20 61  * it is purely a
37ff0 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a 2a 20  dvisory. .**.** 
38000 54 68 65 20 78 43 61 63 68 65 73 69 7a 65 28 29  The xCachesize()
38010 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 20 63   method may be c
38020 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 74 69 6d  alled at any tim
38030 65 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 73  e by SQLite to s
38040 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 67 65 73  et the.** sugges
38050 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 61 63 68  ted maximum cach
38060 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72 20 6f  e-size (number o
38070 66 20 70 61 67 65 73 20 73 74 6f 72 65 64 20 62  f pages stored b
38080 79 29 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20  y) the cache.** 
38090 69 6e 73 74 61 6e 63 65 20 70 61 73 73 65 64 20  instance passed 
380a0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
380b0 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 73 20 74  ument. This is t
380c0 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 69 67 75  he value configu
380d0 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  red using.** the
380e0 20 53 51 4c 69 74 65 20 22 5b 50 52 41 47 4d 41   SQLite "[PRAGMA
380f0 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 20 63 6f   cache_size]" co
38100 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 68 20 74  mmand. As with t
38110 68 65 20 62 50 75 72 67 65 61 62 6c 65 20 70 61  he bPurgeable pa
38120 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 68 65 20  rameter,.** the 
38130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
38140 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
38150 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 73 70  o do anything sp
38160 65 63 69 61 6c 20 77 69 74 68 20 74 68 69 73 0a  ecial with this.
38170 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20 69 73 20  ** value, it is 
38180 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
38190 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65 63 6f  *.** The xPageco
381a0 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73 68 6f  unt() method sho
381b0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 6e  uld return the n
381c0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 63  umber of pages c
381d0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72  urrently.** stor
381e0 65 64 20 69 6e 20 74 68 65 20 63 61 63 68 65 20  ed in the cache 
381f0 73 75 70 70 6c 69 65 64 20 61 73 20 61 6e 20 61  supplied as an a
38200 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 20  rgument..** .** 
38210 54 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 74  The xFetch() met
38220 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 66  hod is used to f
38230 65 74 63 68 20 61 20 70 61 67 65 20 61 6e 64 20  etch a page and 
38240 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
38250 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 20 27 70   to it. .** A 'p
38260 61 67 65 27 2c 20 69 6e 20 74 68 69 73 20 63 6f  age', in this co
38270 6e 74 65 78 74 2c 20 69 73 20 61 20 62 75 66 66  ntext, is a buff
38280 65 72 20 6f 66 20 73 7a 50 61 67 65 20 62 79 74  er of szPage byt
38290 65 73 20 61 6c 69 67 6e 65 64 20 61 74 20 61 6e  es aligned at an
382a0 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f 75 6e 64  .** 8-byte bound
382b0 61 72 79 2e 20 54 68 65 20 70 61 67 65 20 74 6f  ary. The page to
382c0 20 62 65 20 66 65 74 63 68 65 64 20 69 73 20 64   be fetched is d
382d0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
382e0 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 6d 69 6d   key. The.** mim
382f0 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 65 20 69  imum key value i
38300 73 20 31 2e 20 41 66 74 65 72 20 69 74 20 68 61  s 1. After it ha
38310 73 20 62 65 65 6e 20 72 65 74 72 69 65 76 65 64  s been retrieved
38320 20 75 73 69 6e 67 20 78 46 65 74 63 68 2c 20 74   using xFetch, t
38330 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 73 20 63  he page .** is c
38340 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
38350 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pinned..**.** If
38360 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70   the requested p
38370 61 67 65 20 69 73 20 61 6c 72 65 61 64 79 20 69  age is already i
38380 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  n the page cache
38390 2c 20 74 68 65 6e 20 61 20 70 6f 69 6e 74 65 72  , then a pointer
383a0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 61 63 68 65   to.** the cache
383b0 64 20 62 75 66 66 65 72 20 73 68 6f 75 6c 64 20  d buffer should 
383c0 62 65 20 72 65 74 75 72 6e 65 64 20 77 69 74 68  be returned with
383d0 20 69 74 73 20 63 6f 6e 74 65 6e 74 73 20 69 6e   its contents in
383e0 74 61 63 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20  tact. If the.** 
383f0 70 61 67 65 20 69 73 20 6e 6f 74 20 61 6c 72 65  page is not alre
38400 61 64 79 20 69 6e 20 74 68 65 20 63 61 63 68 65  ady in the cache
38410 2c 20 74 68 65 6e 20 74 68 65 20 65 78 70 65 63  , then the expec
38420 74 65 64 20 62 65 68 61 76 69 6f 75 72 20 6f 66  ted behaviour of
38430 20 74 68 65 0a 2a 2a 20 63 61 63 68 65 20 69 73   the.** cache is
38440 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
38450 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
38460 63 72 65 61 74 65 46 6c 61 67 20 70 61 72 61 6d  createFlag param
38470 65 74 65 72 20 70 61 73 73 65 64 0a 2a 2a 20 74  eter passed.** t
38480 6f 20 78 46 65 74 63 68 2c 20 61 63 63 6f 72 64  o xFetch, accord
38490 69 6e 67 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ing to the follo
384a0 77 69 6e 67 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a  wing table:.**.*
384b0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
384c0 31 20 77 69 64 74 68 3d 38 35 25 20 61 6c 69 67  1 width=85% alig
384d0 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20 20 20 3c  n=center>.**   <
384e0 74 72 3e 3c 74 68 3e 63 72 65 61 74 65 46 6c 61  tr><th>createFla
384f0 67 3c 74 68 3e 45 78 70 65 63 74 65 64 20 42 65  g<th>Expected Be
38500 68 61 76 69 6f 75 72 0a 2a 2a 20 20 20 3c 74 72  haviour.**   <tr
38510 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 4c 4c 20 73  ><td>0<td>NULL s
38520 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
38530 64 2e 20 4e 6f 20 6e 65 77 20 63 61 63 68 65 20  d. No new cache 
38540 65 6e 74 72 79 20 69 73 20 63 72 65 61 74 65 64  entry is created
38550 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 3e 31  ..**   <tr><td>1
38560 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46 6c 61  <td>If createFla
38570 67 20 69 73 20 73 65 74 20 74 6f 20 31 2c 20 74  g is set to 1, t
38580 68 69 73 20 69 6e 64 69 63 61 74 65 73 20 74 68  his indicates th
38590 61 74 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  at .**          
385a0 20 20 20 20 20 20 53 51 4c 69 74 65 20 69 73 20        SQLite is 
385b0 68 6f 6c 64 69 6e 67 20 70 69 6e 6e 65 64 20 70  holding pinned p
385c0 61 67 65 73 20 74 68 61 74 20 63 61 6e 20 62 65  ages that can be
385d0 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a 20 20 20 20   unpinned.**    
385e0 20 20 20 20 20 20 20 20 20 20 20 20 62 79 20 77              by w
385f0 72 69 74 69 6e 67 20 74 68 65 69 72 20 63 6f 6e  riting their con
38600 74 65 6e 74 73 20 74 6f 20 74 68 65 20 64 61 74  tents to the dat
38610 61 62 61 73 65 20 66 69 6c 65 20 28 61 0a 2a 2a  abase file (a.**
38620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38630 72 65 6c 61 74 69 76 65 6c 79 20 65 78 70 65 6e  relatively expen
38640 73 69 76 65 20 6f 70 65 72 61 74 69 6f 6e 29 2e  sive operation).
38650 20 49 6e 20 74 68 69 73 20 73 69 74 75 61 74 69   In this situati
38660 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  on the.**       
38670 20 20 20 20 20 20 20 20 20 63 61 63 68 65 20 69           cache i
38680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61  mplementation ha
38690 73 20 74 77 6f 20 63 68 6f 69 63 65 73 3a 20 69  s two choices: i
386a0 74 20 63 61 6e 20 72 65 74 75 72 6e 20 4e 55 4c  t can return NUL
386b0 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  L,.**           
386c0 20 20 20 20 20 69 6e 20 77 68 69 63 68 20 63 61       in which ca
386d0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
386e0 74 74 65 6d 70 74 20 74 6f 20 75 6e 70 69 6e 20  ttempt to unpin 
386f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20  one or more .** 
38700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 70                 p
38710 61 67 65 73 20 62 65 66 6f 72 65 20 72 65 2d 72  ages before re-r
38720 65 71 75 65 73 74 69 6e 67 20 74 68 65 20 73 61  equesting the sa
38730 6d 65 20 70 61 67 65 2c 20 6f 72 20 69 74 20 63  me page, or it c
38740 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
38750 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 61 20       allocate a 
38760 6e 65 77 20 70 61 67 65 20 61 6e 64 20 72 65 74  new page and ret
38770 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
38780 20 69 74 2e 20 49 66 20 61 20 6e 65 77 0a 2a 2a   it. If a new.**
38790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
387a0 70 61 67 65 20 69 73 20 61 6c 6c 6f 63 61 74 65  page is allocate
387b0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 69 72 73  d, then the firs
387c0 74 20 73 69 7a 65 6f 66 28 76 6f 69 64 2a 29 20  t sizeof(void*) 
387d0 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20  bytes of.**     
387e0 20 20 20 20 20 20 20 20 20 20 20 69 74 20 28 61             it (a
387f0 74 20 6c 65 61 73 74 29 20 6d 75