/ Hex Artifact Content
Login

Artifact 0f756e9e8db9d491d0f17ea9c07952974975e43d:


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 35 20 32 30 30 39 2f 30  n,v 1.435 2009/0
05f0: 33 2f 31 36 20 31 33 3a 33 37 3a 30 32 20 64 72  3/16 13:37:02 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 23 64  R | (17<<8))..#d
4010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4020: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4030: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4040: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4050: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4060: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4070: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
4080: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
4090: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
40a0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
40b0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
40c0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
40d0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
40e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
40f0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
4100: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
4110: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
4120: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
4130: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
4140: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
4150: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
4160: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
4170: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
4180: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
4190: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
41a0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
41b0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
41c0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
41d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
41e0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
41f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
4200: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
4210: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
4220: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
4230: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
4240: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
4250: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
4260: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
4270: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
4280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
4290: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
42a0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
42b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
42c0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
42d0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
42e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
42f0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4300: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
4310: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
4320: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4330: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
4340: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
4350: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
4360: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
4370: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
4380: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
4390: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
43a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
43b0: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
43c0: 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  08000.#define SQ
43d0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
43e0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
43f0: 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  10000../*.** CAP
4400: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
4410: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
4420: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
4430: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
4440: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
4450: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
4460: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4470: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
4480: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
4490: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
44a0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
44b0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
44c0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
44d0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
44e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
44f0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
4500: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
4510: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
4520: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
4530: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
4540: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
4550: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
4560: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
4570: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
4580: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
4590: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
45a0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
45b0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
45c0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
45d0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
45e0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
45f0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
4600: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
4610: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
4620: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
4630: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
4640: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
4650: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
4660: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
4670: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
4680: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
4690: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
46a0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
46b0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
46c0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
46d0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
46e0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
46f0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
4700: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
4710: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
4720: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
4730: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
4740: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
4750: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
4760: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
4770: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
4780: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4790: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
47a0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
47b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
47c0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
47d0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
47e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
47f0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
4800: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
4810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4820: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
4830: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
4840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4850: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
4860: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
4870: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4880: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
4890: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
48a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
48b0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
48c0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
48d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
48e0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
48f0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
4900: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4910: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
4920: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
4930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
4940: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
4950: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
4960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4970: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
4980: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
4990: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
49a0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
49b0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
49c0: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
49d0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
49e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
49f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
4a00: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
4a10: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
4a20: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
4a30: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
4a40: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
4a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
4a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4a80: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
4a90: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
4aa0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
4ab0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
4ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
4ad0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
4ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4af0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4b10: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4b20: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4b30: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4b40: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
4b50: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
4b60: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
4b70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
4b80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
4b90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
4ba0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4bb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
4bc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
4bd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4be0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4bf0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
4c00: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
4c10: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4c20: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
4c30: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
4c40: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
4c50: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
4c60: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
4c70: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
4c80: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
4c90: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
4ca0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
4cb0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
4cc0: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
4cd0: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
4ce0: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
4cf0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
4d00: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
4d10: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
4d20: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
4d30: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
4d40: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4d50: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
4d60: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
4d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d80: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
4d90: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
4da0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
4db0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
4dc0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
4dd0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
4de0: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
4df0: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
4e00: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
4e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
4e20: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
4e30: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
4e40: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
4e50: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
4e60: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
4e70: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
4e80: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
4e90: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
4ea0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
4eb0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
4ec0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
4ed0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
4ee0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
4ef0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
4f00: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
4f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4f20: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
4f30: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
4f40: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
4f50: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
4f60: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
4f70: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
4f80: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
4f90: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
4fa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
4fb0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
4fc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4fd0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
4fe0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
4ff0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
5000: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5010: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
5020: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
5030: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
5040: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
5050: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
5060: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
5070: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
5080: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
5090: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
50a0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
50b0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
50c0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
50d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
50e0: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
50f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
5100: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
5110: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
5120: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
5130: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
5140: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
5150: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
5160: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
5170: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
5180: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
5190: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
51a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
51b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
51c0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
51d0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
51e0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
51f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
5200: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
5210: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
5220: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
5230: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
5240: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
5250: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
5260: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
5270: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
5280: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
5290: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
52a0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
52b0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
52c0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
52d0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
52e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
52f0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
5300: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5310: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
5320: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
5330: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
5340: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
5350: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5360: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5370: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5380: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5390: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
53a0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
53c0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
53d0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
53e0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
53f0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
5400: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
5410: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
5420: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
5430: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
5440: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
5450: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
5460: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
5470: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
5480: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
5490: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
54a0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
54b0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
54c0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
54d0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
54e0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
54f0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
5500: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
5510: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
5520: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
5530: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
5540: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
5550: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
5560: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
5570: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
5580: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
5590: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
55a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
55b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
55c0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
55d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
55e0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
55f0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
5600: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
5610: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
5620: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
5630: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
5640: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
5650: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
5660: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
5670: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
5680: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
5690: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
56a0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
56b0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
56c0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
56d0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
56e0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
56f0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
5700: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
5710: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
5720: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
5730: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
5740: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
5750: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
5760: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
5770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
5780: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
5790: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
57a0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
57b0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
57c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
57d0: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
57e0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
57f0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
5800: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
5810: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
5820: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
5830: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
5840: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
5850: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
5860: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
5870: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
5880: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
5890: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
58a0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
58b0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
58c0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
58d0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
58e0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
58f0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
5900: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
5910: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
5920: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
5930: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
5940: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
5950: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
5960: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
5970: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
5980: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
5990: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
59a0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
59b0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
59c0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
59d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
59e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
59f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
5a00: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
5a20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
5a40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5a60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
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 31 36  E_IOCAP_ATOMIC16
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 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5ac0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ae0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
5af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5b00: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
5b10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
5b20: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
5b30: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
5b40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5b60: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
5b70: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
5b80: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ba0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5bb0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
5bc0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
5bd0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
5be0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
5bf0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
5c00: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
5c10: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5c20: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5c30: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c50: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
5c60: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
5c70: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
5c80: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
5c90: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
5ca0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5cb0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5cc0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5cd0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5ce0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5cf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5d00: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5d10: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5d20: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5d30: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5d40: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5d50: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5d60: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
5d70: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
5d80: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
5d90: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
5da0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
5db0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
5dc0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
5dd0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
5de0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
5df0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails 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 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
5e20: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
5e30: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
5e40: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5e50: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
5e60: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
5e70: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
5e80: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
5e90: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
5ea0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
5eb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
5ec0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
5ed0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
5ee0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
5ef0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
5f00: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5f10: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
5f20: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
5f30: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
5f40: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
5f50: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
5f60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5f70: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
5f80: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
5f90: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
5fa0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
5fb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
5fc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
5fd0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
5fe0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
5ff0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
6000: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
6010: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6020: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
6030: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
6040: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
6050: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
6060: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
6070: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
6080: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
6090: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
60a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
60b0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
60c0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
60d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
60e0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
60f0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
6100: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
6110: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6120: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6130: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6140: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6150: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6160: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6170: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6180: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6190: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
61a0: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
61b0: 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20  pcodes {H11310} 
61c0: 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
61d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
61e0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
61f0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
6200: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
6210: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
6220: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6230: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
6240: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
6250: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
6260: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
6270: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
6280: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
6290: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
62a0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
62b0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
62c0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
62d0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
62e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
62f0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
6300: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
6310: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
6320: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6330: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
6340: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
6350: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6360: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
6370: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
6380: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
6390: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
63a0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
63b0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
63c0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
63d0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
63e0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
63f0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
6400: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
6410: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6430: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6440: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
6460: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
6470: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6480: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
6490: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69  ILE      3.#defi
64a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
64b0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
64c0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
64d0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
64e0: 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33   {H17110} <S2013
64f0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  0>.**.** The mut
6500: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
6510: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
6520: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6530: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
6540: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
6550: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
6560: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
6570: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
6580: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
6590: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
65a0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
65b0: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
65c0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
65d0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
65e0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
65f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
6600: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
6610: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
6620: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
6630: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6640: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
6650: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
6660: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6670: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20  nterface Object 
6680: 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30  {H11140} <S20100
6690: 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  >.**.** An insta
66a0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
66b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
66c0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
66d0: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
66e0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
66f0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
6700: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
6710: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
6720: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
6730: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
6740: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
6750: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
6760: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
6770: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
6780: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
6790: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
67a0: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
67b0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
67c0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
67d0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
67e0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
67f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
6800: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
6810: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
6820: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
6830: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
6840: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
6850: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
6860: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
6870: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
6880: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
6890: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
68a0: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
68b0: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
68c0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
68d0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
68e0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
68f0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
6900: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
6910: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
6920: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
6930: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
6940: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
6950: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
6960: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
6970: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
6980: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
6990: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
69a0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
69b0: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
69c0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
69d0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
69e0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
69f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
6a00: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
6a10: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
6a20: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
6a30: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
6a40: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
6a50: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
6a60: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
6a70: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
6a80: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
6a90: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
6aa0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
6ab0: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
6ac0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
6ad0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
6ae0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
6af0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
6b00: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
6b10: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
6b20: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
6b30: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
6b40: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
6b50: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
6b60: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
6b70: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
6b80: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
6b90: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
6ba0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
6bb0: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
6bc0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
6bd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
6be0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
6bf0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
6c00: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
6c10: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
6c20: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
6c30: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
6c40: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
6c50: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
6c60: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
6c70: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
6c80: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
6c90: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
6ca0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
6cb0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
6cc0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
6cd0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
6ce0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
6cf0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
6d00: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72  e().  SQLite fur
6d10: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
6d20: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
6d30: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
6d40: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
6d50: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
6d60: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
6d70: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
6d80: 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a  ous sentense,.**
6d90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6da0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
6db0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
6dc0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
6dd0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
6de0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
6df0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
6e00: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
6e10: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6e20: 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69  meter is xOpen i
6e30: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
6e40: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
6e50: 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f  ust invite its o
6e60: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
6e70: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
6e80: 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a   Whenever the .*
6e90: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
6ea0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
6eb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
6ec0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
6ed0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
6ee0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
6ef0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
6f00: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
6f10: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6f20: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
6f30: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
6f40: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
6f50: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6f60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
6f70: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
6f80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
6f90: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
6fa0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
6fb0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
6fc0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
6fd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
6fe0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
6ff0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
7000: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
7010: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
7020: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
7030: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
7040: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
7050: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
7060: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
7070: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
7080: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
7090: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
70a0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
70b0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
70c0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
70d0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
70e0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
70f0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
7100: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7110: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7120: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
7130: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7140: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
7150: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7160: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
7170: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7180: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
7190: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
71a0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
71b0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
71c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
71d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
71e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
71f0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
7200: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7210: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
7220: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
7230: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
7240: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
7250: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
7260: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
7270: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
7280: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
7290: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
72a0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
72b0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
72c0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
72d0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
72e0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
72f0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
7300: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
7310: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
7320: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
7330: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
7340: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
7350: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
7360: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
7370: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7380: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
7390: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
73a0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
73b0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
73c0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
73d0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
73e0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
73f0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
7400: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
7410: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
7420: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
7430: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
7440: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
7450: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
7460: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
7470: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7480: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
7490: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
74a0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
74b0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
74c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74d0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
74e0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
74f0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
7500: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
7510: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
7520: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7530: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7540: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
7550: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
7560: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
7570: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
7580: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  s..**.** The [SQ
7590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
75a0: 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  IVE] flag means 
75b0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
75c0: 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72  be opened.** for
75d0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
75e0: 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73  s.  This flag is
75f0: 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c   set for all fil
7600: 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72  es except.** for
7610: 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
7620: 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41  se file..**.** A
7630: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
7640: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
7650: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
7660: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
7670: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
7680: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
7690: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
76a0: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
76b0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
76c0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
76d0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
76e0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
76f0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
7700: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
7710: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66   in..**.** The f
7720: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7730: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7740: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7750: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
7760: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
7770: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
7780: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
7790: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
77a0: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
77b0: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
77c0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
77d0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
77e0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
77f0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
7800: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
7810: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
7820: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
7830: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
7840: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
7850: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
7860: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
7870: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
7880: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
7890: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
78a0: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
78b0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
78c0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
78d0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
78e0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
78f0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
7900: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
7910: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
7920: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
7930: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
7940: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
7950: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
7960: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
7970: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
7980: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
7990: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
79a0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
79b0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
79c0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
79d0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
79e0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
79f0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
7a00: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
7a10: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
7a20: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
7a30: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
7a40: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
7a50: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
7a60: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
7a70: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
7a80: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
7a90: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
7aa0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
7ab0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
7ac0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
7ad0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
7ae0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
7af0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
7b00: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
7b10: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
7b20: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
7b30: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
7b40: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
7b50: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
7b60: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
7b70: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
7b80: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
7b90: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
7ba0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
7bb0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
7bc0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
7bd0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7be0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
7bf0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
7c00: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
7c10: 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65  me..**.*/.typede
7c20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7c30: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
7c40: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7c50: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
7c60: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
7c70: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
7c80: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
7c90: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
7ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
7cb0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
7cc0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
7cd0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
7ce0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
7cf0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
7d00: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
7d10: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
7d20: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
7d30: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
7d40: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
7d50: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
7d60: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
7d70: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7d80: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
7d90: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
7da0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
7db0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
7dc0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
7dd0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
7de0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7df0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
7e00: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
7e10: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
7e20: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
7e30: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7e40: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
7e50: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7e60: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
7e70: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
7e80: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
7e90: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7ea0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
7eb0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
7ec0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
7ed0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
7ee0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ef0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
7f00: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
7f10: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
7f20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
7f30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
7f40: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
7f50: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
7f60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
7f70: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
7f80: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
7f90: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
7fa0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
7fb0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
7fc0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
7fd0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
7fe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
7ff0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
8000: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
8010: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
8020: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
8030: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
8040: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
8050: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
8060: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
8070: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
8080: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
8090: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
80a0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
80b0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
80c0: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  /* New fields
80d0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
80e0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
80f0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
8100: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
8110: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
8120: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
8130: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ns. */.};../*.**
8140: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
8150: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
8160: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31   VFS method {H11
8170: 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a  190} <H11140>.**
8180: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8190: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
81a0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
81b0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
81c0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
81d0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
81e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
81f0: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
8200: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
8210: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
8220: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
8230: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
8240: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
8250: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
8260: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
8270: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
8280: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
8290: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
82a0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
82b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
82c0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
82d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
82e0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
82f0: 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  le is both reada
8300: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
8310: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8320: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
8330: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8340: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
8350: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
8360: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66  eadable..*/.#def
8370: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8380: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
8390: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
83a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a  ESS_READWRITE 1.
83b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
83c0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
83d0: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
83e0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
83f0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
8400: 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30   {H10130} <S2000
8410: 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
8420: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
8430: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
8440: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
8450: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
8460: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
8470: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
8480: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
8490: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
84a0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
84b0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
84c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
84d0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
84e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
84f0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
8500: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
8510: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
8520: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
8530: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
8540: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
8550: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
8560: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
8570: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
8580: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8590: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
85a0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
85b0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
85c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
85d0: 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65  ).  Only an effe
85e0: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
85f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8600: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
8610: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
8620: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
8630: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
8640: 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d  no-ops..**.** Am
8650: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
8660: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
8670: 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76  lize() shall inv
8680: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
8690: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
86a0: 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68  arly, sqlite3_sh
86b0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c  utdown().** shal
86c0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
86d0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
86e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
86f0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
8700: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
8710: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
8720: 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65  ..** If for some
8730: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
8740: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8750: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
8760: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
8770: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
8780: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
8790: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
87a0: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
87b0: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
87c0: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
87d0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
87e0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
87f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
8800: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
8810: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
8820: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
8830: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
8840: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
8850: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
8860: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
8870: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
8880: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
8890: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
88a0: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
88b0: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
88c0: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
88d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
88e0: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
88f0: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
8900: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
8910: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
8920: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
8930: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
8940: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
8950: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
8960: 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65  already.  Howeve
8970: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
8980: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
8990: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
89a0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
89b0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
89c0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
89d0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
89e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
89f0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
8a00: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
8a10: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
8a20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8a30: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
8a40: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
8a50: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
8a60: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
8a70: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
8a80: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
8a90: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
8aa0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
8ab0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
8ac0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
8ad0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
8ae0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
8af0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
8b00: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
8b10: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
8b20: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
8b30: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
8b40: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
8b50: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
8b60: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
8b70: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
8b80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
8b90: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
8ba0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
8bb0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
8bc0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
8bd0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
8be0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
8bf0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
8c00: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
8c10: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
8c20: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
8c30: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
8c40: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
8c50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
8c60: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
8c70: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
8c80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
8c90: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
8ca0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
8cb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
8cc0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
8cd0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
8ce0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
8cf0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
8d00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
8d10: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
8d20: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
8d30: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
8d40: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
8d50: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
8d60: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
8d70: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
8d80: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
8d90: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
8da0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
8db0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
8dc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
8dd0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
8de0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
8df0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
8e00: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
8e10: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
8e20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
8e30: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
8e40: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
8e50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
8e60: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
8e70: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
8e80: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
8e90: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
8ea0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
8eb0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
8ec0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8ed0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
8ee0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
8ef0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
8f00: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
8f10: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
8f20: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
8f30: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
8f40: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
8f50: 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f  unix, windows, o
8f60: 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r os/2..** When 
8f70: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
8f80: 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67  platforms (using
8f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
8fa0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
8fb0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
8fc0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8fd0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
8fe0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
8ff0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
9000: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9010: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9020: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
9030: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
9040: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9060: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
9070: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
9080: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
9090: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
90a0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
90b0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
90c0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
90d0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
90e0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
90f0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9100: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9110: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9120: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9130: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9140: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9150: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9160: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9170: 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14100} <S20000>
9180: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
9190: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
91a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
91b0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
91c0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
91d0: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
91e0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
91f0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9200: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9210: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9220: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9230: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9240: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9250: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9260: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
9270: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
9280: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
9290: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
92a0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
92b0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
92c0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
92d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
92e0: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
92f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9300: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9310: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9320: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9330: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9340: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9350: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
9360: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
9370: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
9380: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
9390: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
93a0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
93b0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
93c0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
93d0: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
93e0: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
93f0: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
9400: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
9410: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9420: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
9430: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
9440: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
9450: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
9460: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
9470: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
9480: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
9490: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
94a0: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
94b0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
94c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
94d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
94e0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
94f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9500: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
9510: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
9520: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
9530: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
9540: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
9550: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
9560: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
9570: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
9580: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
9590: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
95a0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
95b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
95c0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
95d0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
95e0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
95f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
9600: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
9610: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
9620: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
9630: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
9640: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9650: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  ]..** If the opt
9660: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
9670: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
9680: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
9690: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
96a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
96b0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
96c0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
96d0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
96e0: 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31  * [H14103] [H141
96f0: 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31  06] [H14120] [H1
9700: 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b  4123] [H14126] [
9710: 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d  H14129] [H14132]
9720: 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31   [H14135].** [H1
9730: 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b  4138] [H14141] [
9740: 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d  H14144] [H14147]
9750: 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35   [H14150] [H1415
9760: 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34  3] [H14156] [H14
9770: 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d  159].** [H14162]
9780: 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36   [H14165] [H1416
9790: 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  8].*/.SQLITE_EXP
97a0: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
97b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
97c0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
97d0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
97e0: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
97f0: 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30  ections  {H14200
9800: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
9810: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
9820: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
9830: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9840: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
9850: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
9860: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
9870: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
9880: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
9890: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
98a0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
98b0: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
98c0: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
98d0: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
98e0: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
98f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
9900: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
9910: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
9920: 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
9930: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
9940: 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20  erface can only 
9950: 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74  be used immediat
9960: 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65  ely after.** the
9970: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9980: 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20  tion is created 
9990: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
99a0: 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  pen()],.** [sqli
99b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
99c0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
99d0: 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  v2()].  .**.** T
99e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
99f0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
9a00: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
9a10: 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66    is the.** conf
9a20: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d  iguration verb -
9a30: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
9a40: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
9a50: 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f  what.** aspect o
9a60: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
9a70: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
9a80: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
9a90: 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f  .** The only cho
9aa0: 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c  ice for this val
9ab0: 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42  ue is [SQLITE_DB
9ac0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
9ad0: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
9ae0: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
9af0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
9b00: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
9b10: 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ite..** Addition
9b20: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70  al arguments dep
9b30: 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e  end on the verb.
9b40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
9b50: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d  nts:.** [H14203]
9b60: 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30   [H14206] [H1420
9b70: 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34  9] [H14212] [H14
9b80: 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  215].*/.SQLITE_E
9b90: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
9ba0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
9bb0: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
9bc0: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
9bd0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
9be0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
9bf0: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
9c00: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
9c10: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
9c20: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
9c30: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
9c40: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
9c50: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
9c60: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
9c70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
9c80: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9c90: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
9ca0: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
9cb0: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
9cc0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
9cd0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
9ce0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
9cf0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
9d00: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
9d10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
9d20: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
9d30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
9d40: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
9d50: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
9d60: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
9d70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
9d80: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
9d90: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
9da0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
9db0: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
9dc0: 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c  tion, an.** appl
9dd0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
9de0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
9df0: 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ve memory alloca
9e00: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a  tion subsystem.*
9e10: 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  * for SQLite to 
9e20: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
9e30: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
9e40: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
9e50: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
9e60: 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69  comes with a bui
9e70: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
9e80: 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a  ocator that is.*
9e90: 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  * perfectly adeq
9ea0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
9eb0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
9ec0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
9ed0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
9ee0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
9ef0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
9f00: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
9f10: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
9f20: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
9f30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
9f40: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
9f50: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
9f60: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
9f70: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
9f80: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
9f90: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
9fa0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
9fb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
9fc0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
9fd0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
9fe0: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
9ff0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
a000: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
a010: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
a020: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
a030: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
a040: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
a050: 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c  Free, and xReall
a060: 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  oc methods must 
a070: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
a080: 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28   malloc(), free(
a090: 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29  ), and realloc()
a0a0: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
a0b0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62  the standard lib
a0c0: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  rary..**.** xSiz
a0d0: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
a0e0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
a0f0: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
a100: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
a110: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
a120: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
a130: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
a140: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
a150: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
a160: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
a170: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
a180: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
a190: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
a1a0: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
a1b0: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
a1c0: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
a1d0: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
a1e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a1f0: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
a200: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
a210: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
a220: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
a230: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
a240: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
a250: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
a260: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
a270: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
a280: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
a290: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
a2a0: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
a2b0: 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  of 2..**.** The 
a2c0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
a2d0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
a2e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
a2f0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
a300: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
a310: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
a320: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
a330: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
a340: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
a350: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
a360: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
a370: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
a380: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
a390: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
a3a0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
a3b0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
a3c0: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
a3d0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
a3e0: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
a3f0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
a400: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
a410: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
a420: 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  wn..*/.typedef s
a430: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
a440: 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
a450: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
a460: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
a470: 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
a480: 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
a490: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
a4a0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
a4b0: 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
a4c0: 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
a4d0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
a4e0: 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
a4f0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
a500: 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
a510: 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
a520: 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
a530: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
a540: 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
a550: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
a560: 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
a570: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
a580: 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
a590: 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
a5a0: 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
a5b0: 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
a5c0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
a5d0: 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
a5e0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
a5f0: 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
a600: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
a610: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
a620: 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
a630: 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
a640: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
a650: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
a660: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
a670: 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
a680: 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
a690: 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
a6a0: 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
a6b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a6c0: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
a6d0: 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c  tions {H10160} <
a6e0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
a6f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a700: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
a710: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
a720: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
a730: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
a740: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
a750: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
a760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a770: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a780: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
a790: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
a7a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
a7b0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
a7c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
a7d0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
a7e0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
a7f0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
a800: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
a810: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
a820: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
a830: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
a840: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
a850: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
a860: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
a870: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
a880: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
a890: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
a8a0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
a8b0: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
a8c0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
a8d0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
a8e0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
a8f0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
a900: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
a910: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
a920: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
a930: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
a940: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
a950: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
a960: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
a970: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
a980: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
a990: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
a9a0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
a9b0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
a9c0: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
a9d0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
a9e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
a9f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
aa00: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
aa10: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
aa20: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
aa30: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
aa40: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
aa50: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
aa60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
aa70: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
aa80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
aa90: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
aaa0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
aab0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
aac0: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
aad0: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
aae0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
aaf0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
ab00: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
ab10: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
ab20: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
ab30: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
ab40: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
ab50: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
ab60: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
ab70: 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
ab80: 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
ab90: 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
aba0: 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
abb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
abc0: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
abd0: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
abe0: 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75  ng mode].** docu
abf0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
ac00: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
ac10: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
ac20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ac30: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
ac40: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
ac50: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
ac60: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
ac70: 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e    This option en
ac80: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
ac90: 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
aca0: 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
acb0: 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
acc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
acd0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
ace0: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
acf0: 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
ad00: 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
ad10: 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
ad20: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ad30: 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
ad40: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
ad50: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
ad60: 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
ad70: 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
ad80: 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
ad90: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
ada0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
adb0: 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
adc0: 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
add0: 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
ade0: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
adf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ae00: 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
ae10: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ae20: 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
ae30: 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
ae40: 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65  same time..** Se
ae50: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
ae60: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61   mode] documenta
ae70: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
ae80: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
ae90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
aea0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
aeb0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
aec0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
aed0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
aee0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
aef0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
af00: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
af10: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
af20: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
af30: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
af40: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
af50: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
af60: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
af70: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
af80: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
af90: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
afa0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
afb0: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
afc0: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
afd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
afe0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
aff0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b000: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
b010: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b020: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
b030: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
b040: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
b050: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b060: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
b070: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
b080: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
b090: 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
b0a0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
b0b0: 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
b0c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
b0d0: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
b0e0: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
b0f0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
b100: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
b110: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
b120: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
b130: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
b140: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
b150: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
b160: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
b170: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
b180: 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a   example.</dd>.*
b190: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b1a0: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
b1b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b1c0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
b1d0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
b1e0: 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
b1f0: 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
b200: 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
b210: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
b220: 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
b230: 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
b240: 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
b250: 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73  istics. When dis
b260: 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
b270: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
b280: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a  rfaces become .*
b290: 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  * non-operationa
b2a0: 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
b2b0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b2c0: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
b2d0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b2e0: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
b2f0: 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
b300: 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
b310: 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20  ap_limit()].**  
b320: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
b330: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
b340: 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ul>.** </dd>.**.
b350: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b360: 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
b370: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b380: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
b390: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
b3a0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
b3b0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
b3c0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
b3d0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
b3e0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
b3f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
b400: 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69  emory, the.** si
b410: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
b420: 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ch buffer (sz), 
b430: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
b440: 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20  f buffers (N).  
b450: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
b460: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
b470: 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65  tiple of 16. The
b480: 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68   sz parameter sh
b490: 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79  ould be a few by
b4a0: 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68  tes.** larger th
b4b0: 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63  an the actual sc
b4c0: 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75  ratch space requ
b4d0: 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61  ired due interna
b4e0: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54  l overhead..** T
b4f0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
b500: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
b510: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
b520: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
b530: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
b540: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
b550: 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
b560: 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
b570: 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20   buffer at once 
b580: 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a  per thread, so.*
b590: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
b5a0: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65  t to the expecte
b5b0: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
b5c0: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 68   of threads.  Th
b5d0: 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65  e sz.** paramete
b5e0: 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69  r should be 6 ti
b5f0: 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  mes the size of 
b600: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
b610: 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
b620: 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 65  ** Scratch buffe
b630: 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20 70  rs are used as p
b640: 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 65  art of the btree
b650: 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69   balance operati
b660: 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62  on.  If.** The b
b670: 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65  tree balancer ne
b680: 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d  eds additional m
b690: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
b6a0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
b6b0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 66  .** scratch buff
b6c0: 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72  ers or if no scr
b6d0: 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61 63  atch buffer spac
b6e0: 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  e is specified, 
b6f0: 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67  then SQLite.** g
b700: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
b710: 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74  malloc()] to obt
b720: 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  ain the memory i
b730: 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a  t needs.</dd>.**
b740: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
b750: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
b760: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b770: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
b780: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
b790: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
b7a0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
b7b0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
b7c0: 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
b7d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
b7e0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
b7f0: 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
b800: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
b810: 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
b820: 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
b830: 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
b840: 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
b850: 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
b860: 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
b870: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
b880: 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
b890: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
b8a0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
b8b0: 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
b8c0: 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  to the.** memory
b8d0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
b8e0: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
b8f0: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
b900: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
b910: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
b920: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
b930: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
b940: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
b950: 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  8.  The first.**
b960: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
b970: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
b980: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
b990: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
b9a0: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
b9b0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
b9c0: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
b9d0: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
b9e0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
b9f0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
ba00: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
ba10: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
ba20: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
ba30: 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61  e.  If additiona
ba40: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
ba50: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
ba60: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
ba70: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
ba80: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
ba90: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
baa0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
bab0: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
bac0: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
bad0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  ace..** The impl
bae0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
baf0: 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65   use one or more
bb00: 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72   of the N buffer
bb10: 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65  s to hold .** me
bb20: 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
bb30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64  information. </d
bb40: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
bb50: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
bb60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bb70: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
bb80: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
bb90: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
bba0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
bbb0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
bbc0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
bbd0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
bbe0: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
bbf0: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
bc00: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
bc10: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
bc20: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
bc30: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
bc40: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
bc50: 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  nts: A pointer t
bc60: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
bc70: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
bc80: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
bc90: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
bca0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
bcb0: 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a  ation size.  If.
bcc0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  ** the first poi
bcd0: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
bce0: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
bcf0: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
bd00: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
bd10: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
bd20: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
bd30: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
bd40: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
bd50: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
bd60: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
bd70: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
bd80: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
bd90: 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f    If the.** memo
bda0: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
bdb0: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
bdc0: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
bdd0: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
bde0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
bdf0: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
be00: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
be10: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
be20: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
be30: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
be40: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
be50: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
be60: 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a  ion needs.</dd>.
be70: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
be80: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
be90: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
bea0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
beb0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
bec0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
bed0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
bee0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
bef0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
bf00: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
bf10: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
bf20: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
bf30: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
bf40: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
bf50: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
bf60: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
bf70: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
bf80: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
bf90: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
bfa0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
bfb0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bfc0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bfd0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bfe0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bff0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c000: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c010: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c020: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c030: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
c040: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
c050: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
c060: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
c070: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
c080: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
c090: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
c0a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
c0b0: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
c0c0: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
c0d0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
c0e0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
c0f0: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
c100: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
c110: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
c120: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
c130: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  g, for example.<
c140: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c150: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
c160: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
c170: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c180: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
c190: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
c1a0: 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
c1b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f   memory allcatio
c1c0: 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69  n lookaside opti
c1d0: 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66  mization.  The f
c1e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
c1f0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
c200: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
c210: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
c220: 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
c230: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
c240: 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
c250: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
c260: 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  onnection.</dd>.
c270: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c280: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
c290: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c2a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
c2b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
c2c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
c2d0: 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
c2e0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
c2f0: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  ds] object.  Thi
c300: 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
c310: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c320: 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
c330: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
c340: 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69  mentation.  SQLi
c350: 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
c360: 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
c370: 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
c380: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
c390: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
c3a0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c3b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c3c0: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
c3d0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c3e0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c3f0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c400: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c410: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
c420: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
c430: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
c440: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
c450: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
c460: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
c470: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
c480: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
c490: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
c4a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
c4b0: 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
c4c0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
c4d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
c4e0: 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
c4f0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
c500: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
c510: 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
c520: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
c530: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c540: 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
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: 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
c590: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
c5a0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c5c0: 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
c5d0: 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* 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 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
c610: 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
c620: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
c630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c640: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
c650: 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
c660: 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
c670: 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
c680: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
c690: 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
c6a0: 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
c6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c6c0: 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
c6d0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
c6e0: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c700: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
c710: 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
c720: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
c730: 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
c740: 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
c750: 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
c760: 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
c770: 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
c780: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
c790: 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
c7a0: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
c7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c7c0: 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
c7d0: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
c7e0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
c7f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c800: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
c810: 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
c820: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
c830: 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  s* */../*.** CAP
c840: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
c850: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
c860: 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0170} <S20000>.*
c870: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c880: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
c890: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
c8a0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
c8b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c8c0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
c8d0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
c8e0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
c8f0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
c900: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
c910: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
c920: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
c930: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
c940: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
c950: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
c960: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
c970: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c980: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
c990: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
c9a0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
c9b0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
c9c0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
c9d0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c9e0: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
c9f0: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
ca00: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
ca10: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
ca20: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
ca30: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
ca40: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
ca50: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
ca60: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
ca70: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
ca80: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
ca90: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
caa0: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
cab0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cac0: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
cad0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
cae0: 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
caf0: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
cb00: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
cb10: 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
cb20: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
cb30: 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
cb40: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
cb50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cb60: 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
cb70: 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
cb80: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cb90: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
cba0: 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
cbb0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
cbc0: 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
cbd0: 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
cbe0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 72  memory.  The fir
cbf0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  st.** argument m
cc00: 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
cc10: 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
cc20: 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
cc30: 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62  e lookaside.** b
cc40: 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
cc50: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
cc60: 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f  oc()].  The seco
cc70: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
cc80: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
cc90: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
cca0: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
ccb0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
ccc0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
ccd0: 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
cce0: 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
ccf0: 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
cd00: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
cd10: 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
cd20: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
cd30: 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
cd40: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
cd50: 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e   arguments.</dd>
cd60: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
cd70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
cd80: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
cd90: 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
cda0: 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
cdb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cdc0: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
cdd0: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
cde0: 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30  lt Codes {H12200
cdf0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
ce00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
ce10: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
ce20: 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
ce30: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
ce40: 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
ce50: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
ce60: 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
ce70: 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  e. The extended 
ce80: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
ce90: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
cea0: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
ceb0: 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
cec0: 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69  lity considerati
ced0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ons..**.** Requi
cee0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
cef0: 32 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2f  201] [H12202].*/
cf00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
cf10: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
cf20: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
cf30: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
cf40: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
cf50: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32  nsert Rowid {H12
cf60: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
cf70: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
cf80: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
cf90: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
cfa0: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
cfb0: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
cfc0: 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
cfd0: 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f  "rowid"]. The ro
cfe0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
cff0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
d000: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
d010: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
d020: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
d030: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
d040: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
d050: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
d060: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
d070: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a  ed columns. If.*
d080: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
d090: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
d0a0: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
d0b0: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
d0c0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
d0d0: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
d0e0: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
d0f0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
d100: 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
d110: 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
d120: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
d130: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
d140: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
d150: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
d160: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
d170: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
d180: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
d190: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
d1a0: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
d1b0: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
d1c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d1d0: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
d1e0: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
d1f0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
d200: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
d210: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b  gger, then the [
d220: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
d230: 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73  serted.** row is
d240: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
d250: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
d260: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
d270: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
d280: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
d290: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c  gger terminates,
d2a0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
d2b0: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
d2c0: 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74  ine.** reverts t
d2d0: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65  o the last value
d2e0: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65   inserted before
d2f0: 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72   the trigger fir
d300: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e  ed..**.** An [IN
d310: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
d320: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
d330: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
d340: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
d350: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
d360: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
d370: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
d380: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
d390: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20   routine.  Thus 
d3a0: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
d3b0: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
d3c0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
d3d0: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
d3e0: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
d3f0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
d400: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
d410: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
d420: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
d430: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
d440: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20   When INSERT OR 
d450: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
d460: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
d470: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
d480: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
d490: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
d4a0: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
d4b0: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
d4c0: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
d4d0: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
d4e0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
d4f0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
d500: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
d510: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
d520: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
d530: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
d540: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
d550: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
d560: 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
d570: 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
d580: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
d590: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
d5a0: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
d5b0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
d5c0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
d5d0: 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48  :.** [H12221] [H
d5e0: 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  12223].**.** If 
d5f0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
d600: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
d610: 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
d620: 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
d630: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
d640: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
d650: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d660: 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
d670: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
d680: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
d690: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
d6a0: 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
d6b0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
d6c0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
d6d0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
d6e0: 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
d6f0: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
d700: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
d710: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
d720: 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
d730: 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
d740: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
d750: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
d760: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
d770: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d780: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
d790: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
d7a0: 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53  fied {H12240} <S
d7b0: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
d7c0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
d7d0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
d7e0: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
d7f0: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
d800: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
d810: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
d820: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
d830: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
d840: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
d850: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
d860: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
d870: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
d880: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c  arameter..** Onl
d890: 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
d8a0: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
d8b0: 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
d8c0: 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
d8d0: 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
d8e0: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
d8f0: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
d900: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
d910: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
d920: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
d930: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
d940: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d950: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
d960: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
d970: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
d980: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
d990: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
d9a0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
d9b0: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
d9c0: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
d9d0: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
d9e0: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
d9f0: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
da00: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
da10: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
da20: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
da30: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
da40: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
da50: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
da60: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
da70: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
da80: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
da90: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
daa0: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
dab0: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
dac0: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
dad0: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
dae0: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
daf0: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
db00: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
db10: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
db20: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
db30: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
db40: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
db50: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
db60: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
db70: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
db80: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
db90: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
dba0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
dbb0: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
dbc0: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
dbd0: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
dbe0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
dbf0: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
dc00: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
dc10: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
dc20: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
dc30: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
dc40: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
dc50: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
dc60: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
dc70: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
dc80: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
dc90: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
dca0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
dcb0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
dcc0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
dcd0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
dce0: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
dcf0: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
dd00: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
dd10: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
dd20: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
dd30: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
dd40: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
dd50: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
dd60: 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
dd70: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
dd80: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
dd90: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
dda0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
ddb0: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
ddc0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
ddd0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
dde0: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
ddf0: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
de00: 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69  op level.  Withi
de10: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
de20: 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
de30: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
de40: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
de50: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
de60: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
de70: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
de80: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
de90: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
dea0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
deb0: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
dec0: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
ded0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
dee0: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
def0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
df00: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
df10: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
df20: 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
df30: 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
df40: 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
df50: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
df60: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
df70: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
df80: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
df90: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
dfa0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
dfb0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
dfc0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
dfd0: 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69 73  le.  Doing so is
dfe0: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
dff0: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
e000: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
e010: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
e020: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
e030: 6c 65 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  le.  Because of 
e040: 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
e050: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
e060: 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
e070: 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
e080: 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
e090: 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
e0a0: 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
e0b0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e0c0: 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
e0d0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
e0e0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
e0f0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
e100: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
e110: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
e120: 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
e130: 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
e140: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
e150: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
e160: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
e170: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
e180: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
e190: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 4f  E 1" instead.  O
e1a0: 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e  r recompile usin
e1b0: 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
e1c0: 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f  _OMIT_TRUNCATE_O
e1d0: 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d  PTIMIZATION] com
e1e0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e1f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a   to disable the.
e200: 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  ** optimization 
e210: 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a  on all queries..
e220: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
e230: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20  ts:.** [H12241] 
e240: 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49  [H12243].**.** I
e250: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
e260: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
e270: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
e280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e290: 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
e2a0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
e2b0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
e2c0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
e2d0: 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
e2e0: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
e2f0: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
e300: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e310: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
e320: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
e330: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
e340: 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32  s Modified {H122
e350: 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a  60} <S10600>.**.
e360: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e370: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
e380: 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
e390: 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53  es caused by INS
e3a0: 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f  ERT,.** UPDATE o
e3b0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
e3c0: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
e3d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e3e0: 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
e3f0: 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63  ** The count inc
e400: 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
e410: 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67  s from all trigg
e420: 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  er contexts.  Ho
e430: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
e440: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
e450: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
e460: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52  d to implement R
e470: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
e480: 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
e490: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
e4a0: 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50  cessing, or DROP
e4b0: 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e   table processin
e4c0: 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65  g..** The change
e4d0: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73  s are counted as
e4e0: 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61   soon as the sta
e4f0: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
e500: 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d  s them is.** com
e510: 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
e520: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
e530: 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  e is passed to [
e540: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
e550: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
e560: 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
e570: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
e580: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
e590: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
e5a0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
e5b0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
e5c0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
e5d0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
e5e0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
e5f0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
e600: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
e610: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
e620: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
e630: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
e640: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20  e.)  Because of 
e650: 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
e660: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
e670: 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
e680: 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
e690: 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
e6a0: 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
e6b0: 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
e6c0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e6d0: 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
e6e0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
e6f0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
e700: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
e710: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
e720: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
e730: 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
e740: 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
e750: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
e760: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
e770: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
e780: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
e790: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
e7a0: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20  E 1" instead.   
e7b0: 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69  Or recompile usi
e7c0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
e7d0: 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f  E_OMIT_TRUNCATE_
e7e0: 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f  OPTIMIZATION] co
e7f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
e800: 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  n to disable the
e810: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
e820: 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e   on all queries.
e830: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
e840: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
e850: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
e860: 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
e870: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
e880: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
e890: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e8a0: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e8b0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e8c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e8d0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e8e0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e8f0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
e900: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
e910: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
e920: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
e930: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
e940: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
e950: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e960: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
e970: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
e980: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
e990: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
e9a0: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
e9b0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e9c0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
e9d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
e9e0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
e9f0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
ea00: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
ea10: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
ea20: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
ea30: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
ea40: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
ea50: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
ea60: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
ea70: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
ea80: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
ea90: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
eaa0: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
eab0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
eac0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
ead0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
eae0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
eaf0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
eb00: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
eb10: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
eb20: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
eb30: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
eb40: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
eb50: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
eb60: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
eb70: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
eb80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eb90: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
eba0: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
ebb0: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
ebc0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
ebd0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
ebe0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
ebf0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
ec00: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
ec10: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
ec20: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ec30: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
ec40: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ec50: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
ec60: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
ec70: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
ec80: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ec90: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
eca0: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
ecb0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
ecc0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
ecd0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ece0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
ecf0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
ed00: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
ed10: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
ed20: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
ed30: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
ed40: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
ed50: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
ed60: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
ed70: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
ed80: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
ed90: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ally..**.** A ca
eda0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
edb0: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
edc0: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
edd0: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
ede0: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
edf0: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
ee00: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
ee10: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
ee20: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d  nts:.** [H12271]
ee30: 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20   [H12272].**.** 
ee40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
ee50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
ee60: 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
ee70: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
ee80: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
ee90: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
eea0: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
eeb0: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
eec0: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
eed0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
eee0: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
eef0: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
ef00: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
ef10: 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
ef20: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
ef30: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
ef40: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
ef50: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
ef60: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
ef70: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
ef80: 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
ef90: 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
efa0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
efb0: 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
efc0: 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
efd0: 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
efe0: 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
eff0: 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
f000: 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
f010: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
f020: 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
f030: 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
f040: 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
f050: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
f060: 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
f070: 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
f080: 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
f090: 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
f0a0: 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
f0b0: 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
f0c0: 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
f0d0: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
f0e0: 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
f0f0: 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
f100: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
f110: 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
f120: 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
f130: 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
f140: 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
f150: 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
f160: 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
f170: 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
f180: 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
f190: 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
f1a0: 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
f1b0: 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
f1c0: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
f1d0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f1e0: 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
f1f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
f200: 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
f210: 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
f220: 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
f230: 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  t SQL..**.** Req
f240: 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35  uirements: [H105
f250: 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a  11] [H10512].**.
f260: 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
f270: 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
f280: 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
f290: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
f2a0: 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
f2b0: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
f2c0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
f2d0: 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
f2e0: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
f2f0: 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
f300: 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
f310: 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
f320: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
f330: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
f340: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
f350: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
f360: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
f370: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
f380: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
f390: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
f3a0: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
f3b0: 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30  {H12310} <S40400
f3c0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
f3d0: 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
f3e0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
f3f0: 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
f400: 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
f410: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
f420: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
f430: 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
f440: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
f450: 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
f460: 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
f470: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
f480: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
f490: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
f4a0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
f4b0: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
f4c0: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
f4d0: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
f4e0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
f4f0: 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  . If the busy ca
f500: 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
f510: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
f520: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
f530: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
f540: 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
f550: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f560: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
f570: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
f580: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
f590: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
f5a0: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
f5b0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
f5c0: 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54  sy_handler().  T
f5d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f5e0: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
f5f0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
f600: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
f610: 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
f620: 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
f630: 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
f640: 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
f650: 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a  event.  If the.*
f660: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
f670: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
f680: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
f690: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
f6a0: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
f6b0: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
f6c0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
f6d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f6e0: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
f6f0: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
f700: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
f710: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
f720: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
f730: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
f740: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
f750: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
f760: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
f770: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
f780: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
f790: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
f7a0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
f7b0: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
f7c0: 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
f7d0: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
f7e0: 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  . If SQLite dete
f7f0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
f800: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
f810: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
f820: 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
f830: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
f840: 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
f850: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
f860: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
f870: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
f880: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
f890: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
f8a0: 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
f8b0: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
f8c0: 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
f8d0: 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
f8e0: 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
f8f0: 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
f900: 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
f910: 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
f920: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
f930: 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
f940: 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
f950: 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
f960: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
f970: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
f980: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
f990: 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
f9a0: 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
f9b0: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
f9c0: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
f9d0: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
f9e0: 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
f9f0: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
fa00: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
fa10: 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
fa20: 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
fa30: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fa40: 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
fa50: 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
fa60: 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
fa70: 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
fa80: 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
fa90: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
faa0: 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
fab0: 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
fac0: 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
fad0: 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
fae0: 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
faf0: 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
fb00: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
fb10: 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
fb20: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
fb30: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
fb40: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
fb50: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
fb60: 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
fb70: 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
fb80: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
fb90: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
fba0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
fbb0: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
fbc0: 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
fbd0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
fbe0: 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
fbf0: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
fc00: 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
fc10: 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
fc20: 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
fc30: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
fc40: 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
fc50: 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
fc60: 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
fc70: 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
fc80: 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
fc90: 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
fca0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
fcb0: 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
fcc0: 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
fcd0: 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
fce0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
fcf0: 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
fd00: 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
fd10: 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
fd20: 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
fd30: 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
fd40: 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
fd50: 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
fd60: 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
fd70: 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
fd80: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
fd90: 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
fda0: 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
fdb0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
fdc0: 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
fdd0: 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
fde0: 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
fdf0: 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
fe00: 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
fe10: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
fe20: 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
fe30: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
fe40: 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
fe50: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
fe60: 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
fe70: 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
fe80: 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
fe90: 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
fea0: 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  portant..**.** T
feb0: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
fec0: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
fed0: 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
fee0: 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
fef0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ff00: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
ff10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
ff20: 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
ff30: 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
ff40: 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63  er.  Note that c
ff50: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
ff60: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
ff70: 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
ff80: 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
ff90: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
ffa0: 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
ffb0: 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
ffc0: 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
ffd0: 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
ffe0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
fff0: 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
10000 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
10010 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
10020 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
10030 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
10040 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
10050 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
10060 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33  * [H12311] [H123
10070 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31  12] [H12314] [H1
10080 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a  2316] [H12318].*
10090 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64  *.** A busy hand
100a0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
100b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
100c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
100d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
100e0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
100f0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
10100 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
10110 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
10120 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
10130 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
10140 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
10150 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
10160 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34  y Timeout {H1234
10170 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
10180 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
10190 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
101a0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
101b0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
101c0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
101d0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
101e0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
101f0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
10200 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a  .  The handler.*
10210 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
10220 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
10230 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "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 0a 2a 2a 20 68 61 76 65  sleeping.** have
10260 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48   accumulated. {H
10270 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73  12343} After "ms
10280 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
10290 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
102a0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
102b0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
102c0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
102d0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
102e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
102f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
10300 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
10310 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
10320 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
10330 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
10340 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
10350 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
10360 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
10370 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
10380 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
10390 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
103a0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
103b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
103c0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
103d0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
103e0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
103f0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
10400 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
10410 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10420 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
10430 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
10440 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
10450 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
10460 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
10470 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
10480 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48  :.** [H12341] [H
10490 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a  12343] [H12344].
104a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
104b0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
104c0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
104d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
104e0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
104f0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
10500 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30   Queries {H12370
10510 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10000>.**.**
10520 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
10530 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
10540 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
10550 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
10560 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
10570 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
10580 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
10590 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
105a0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
105b0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
105c0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
105d0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
105e0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
105f0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
10600 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
10610 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
10620 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
10630 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
10640 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
10650 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
10660 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
10670 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
10680 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
10690 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
106a0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
106b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
106c0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
106d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
106e0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
106f0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
10700 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
10710 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
10720 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
10730 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
10740 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
10750 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
10760 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
10770 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
10780 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
10790 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
107a0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
107b0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
107c0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
107d0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
107e0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
107f0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
10800 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
10810 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
10820 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
10830 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
10840 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
10850 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
10860 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
10870 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
10880 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
10890 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
108a0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
108b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
108c0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
108d0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
108e0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
108f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
10900 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
10910 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
10920 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
10930 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
10940 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
10950 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
10960 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
10970 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
10980 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
10990 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
109a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
109b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
109c0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
109d0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
109e0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
109f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
10a00 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
10a10 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
10a20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
10a30 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
10a40 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
10a50 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
10a60 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
10a70 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
10a80 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
10a90 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
10aa0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
10ab0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
10ac0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
10ad0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
10ae0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
10af0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
10b00 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
10b10 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
10b20 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
10b30 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
10b40 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
10b50 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
10b60 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
10b70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
10b80 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
10b90 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
10ba0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
10bb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10bc0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
10bd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
10be0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
10bf0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
10c00 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
10c10 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
10c20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
10c30 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
10c40 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10c50 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
10c60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
10c70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te>.**.** The sq
10c80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
10c90 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
10ca0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
10cb0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
10cc0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
10cd0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
10ce0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
10cf0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
10d00 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
10d10 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  er.  It returns 
10d20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
10d30 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
10d40 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
10d50 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
10d60 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c  ** After the cal
10d70 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61  ling function ha
10d80 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
10d90 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20   the result, it 
10da0 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74  should.** pass t
10db0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
10dc0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  e result table t
10dd0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
10de0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
10df0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
10e00 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
10e10 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
10e20 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
10e30 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
10e40 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
10e50 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
10e60 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
10e70 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
10e80 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
10e90 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
10ea0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
10eb0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
10ec0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
10ed0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
10ee0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
10ef0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
10f00 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
10f10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
10f20 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
10f30 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
10f40 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
10f50 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
10f60 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
10f70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
10f80 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
10f90 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
10fa0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
10fb0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
10fc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
10fd0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
10fe0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
10ff0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
11000 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
11010 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
11020 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
11030 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
11040 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
11050 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
11060 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
11070 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
11080 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
11090 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
110a0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b  _errcode()] or [
110b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
110c0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
110d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37  ments:.** [H1237
110e0 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32  1] [H12373] [H12
110f0 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48  374] [H12376] [H
11100 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a  12379] [H12382].
11110 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
11120 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
11130 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
11140 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
11150 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
11160 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
11170 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
11180 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
11190 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
111a0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
111b0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
111c0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
111d0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
111e0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
111f0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
11200 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
11210 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
11220 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
11230 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
11240 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
11250 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
11260 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
11270 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
11280 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11290 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
112a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
112b0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
112c0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
112d0 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d  nctions {H17400}
112e0 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30   <S70000><S20000
112f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
11300 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61  utines are worka
11310 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
11320 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
11330 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
11340 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
11350 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
11360 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70  * The sqlite3_mp
11370 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
11380 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
11390 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
113a0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
113b0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
113c0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
113d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
113e0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
113f0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
11400 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
11410 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
11420 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
11430 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74  e()].  Both rout
11440 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
11450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
11460 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11470 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
11480 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
11490 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
114a0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
114b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49   string..**.** I
114c0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
114d0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
114e0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
114f0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
11500 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
11510 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
11520 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
11530 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
11540 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
11550 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11560 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
11570 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
11580 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11590 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
115a0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
115b0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
115c0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
115d0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
115e0 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
115f0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
11600 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
11610 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
11620 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
11630 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
11640 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
11650 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
11660 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
11670 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
11680 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
11690 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
116a0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
116b0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
116c0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
116d0 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
116e0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
116f0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
11700 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
11710 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
11720 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
11730 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
11740 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
11750 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
11760 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
11770 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
11780 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
11790 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
117a0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
117b0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
117c0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
117d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
117e0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
117f0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
11800 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
11810 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
11820 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
11830 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
11840 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
11850 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
11860 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
11870 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
11880 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
11890 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
118a0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
118b0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
118c0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
118d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
118e0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
118f0 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
11900 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
11910 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
11920 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
11930 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
11940 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
11950 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
11960 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
11970 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
11980 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
11990 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
119a0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
119b0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
119c0 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69  *.** The %q opti
119d0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
119e0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
119f0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
11a00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
11a10 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
11a20 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
11a30 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
11a40 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
11a50 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
11a60 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
11a70 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
11a80 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f   literal.  By do
11a90 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
11aa0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
11ab0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
11ac0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
11ad0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
11ae0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
11af0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
11b00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
11b10 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
11b20 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
11b30 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
11b40 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
11b50 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11b60 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
11b70 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
11b80 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
11b90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
11ba0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
11bb0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
11bc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
11bd0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
11be0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
11bf0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
11c00 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
11c10 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
11c20 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
11c30 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
11c40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
11c50 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
11c60 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
11c70 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
11c80 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11c90 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
11ca0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
11cb0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
11cc0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
11cd0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
11ce0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
11cf0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
11d00 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
11d10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
11d20 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
11d30 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
11d40 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
11d50 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
11d60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
11d70 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
11d80 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
11d90 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
11da0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
11db0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
11dc0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
11dd0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
11de0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11df0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
11e00 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
11e10 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
11e20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
11e30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
11e40 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
11e50 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
11e60 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
11e70 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
11e80 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
11e90 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
11ea0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
11eb0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
11ec0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
11ed0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20  l..**.** The %Q 
11ee0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
11ef0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
11f00 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
11f10 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
11f20 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
11f30 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
11f40 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
11f50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
11f60 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
11f70 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
11f80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
11f90 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
11fa0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
11fb0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
11fc0 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20  uotes) in place 
11fd0 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e  of the %Q option
11fe0 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  .  So, for examp
11ff0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
12000 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
12010 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
12020 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
12030 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
12040 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
12050 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
12060 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
12070 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
12080 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
12090 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
120a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
120b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
120c0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
120d0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
120e0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
120f0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
12100 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
12110 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
12120 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
12130 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
12140 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
12150 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
12160 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
12170 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
12180 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
12190 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
121a0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
121b0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
121c0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
121d0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
121e0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
121f0 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
12200 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
12210 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48  :.** [H17403] [H
12220 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a  17406] [H17407].
12230 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
12240 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
12250 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
12260 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
12270 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
12280 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
12290 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
122a0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
122b0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
122c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
122d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
122e0 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30  Subsystem {H1730
122f0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
12300 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
12310 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68  e  uses these th
12320 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
12330 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
12340 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
12350 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12360 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
12370 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
12380 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
12390 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
123a0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
123b0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
123c0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
123d0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
123e0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
123f0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
12400 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
12410 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12420 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
12430 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
12440 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
12450 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
12460 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
12470 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
12480 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
12490 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  r..** If sqlite3
124a0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
124b0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
124c0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
124d0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
124e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
124f0 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61  er.  If the para
12500 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
12510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
12520 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
12530 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
12540 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
12550 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
12560 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  er..**.** Callin
12570 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
12580 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
12590 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
125a0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
125b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
125c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
125d0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
125e0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
125f0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
12600 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
12610 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
12620 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
12630 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
12640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
12650 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
12660 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
12670 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
12680 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
12690 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
126a0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
126b0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
126c0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
126d0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
126e0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
126f0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
12700 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
12710 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
12720 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
12730 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
12740 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
12750 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
12760 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
12770 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
12780 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
12790 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
127a0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
127b0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
127c0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
127d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
127e0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
127f0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
12800 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
12810 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
12820 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
12830 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
12840 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12850 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
12860 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
12870 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
12880 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
12890 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
128a0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
128b0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
128c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
128d0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
128e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
128f0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
12900 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
12910 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
12920 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
12930 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
12940 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
12950 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
12960 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
12970 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
12980 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
12990 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
129a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
129b0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
129c0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
129d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
129e0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
129f0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
12a00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
12a10 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
12a20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12a30 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
12a40 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c()..** sqlite3_
12a50 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
12a60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12a70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12a80 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
12a90 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
12aa0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
12ab0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
12ac0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
12ad0 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
12ae0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
12af0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
12b00 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
12b10 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
12b20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
12b30 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
12b40 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
12b50 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
12b60 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
12b70 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
12b80 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
12b90 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
12ba0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
12bb0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
12bc0 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
12bd0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
12be0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
12bf0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
12c00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
12c10 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
12c20 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
12c30 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
12c40 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
12c50 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
12c60 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
12c70 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
12c80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d  ntation of the m
12c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ca0 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a   subsystem uses.
12cb0 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  ** the malloc(),
12cc0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
12cd0 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62  ree() provided b
12ce0 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  y the standard C
12cf0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31   library..** {H1
12d00 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
12d10 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12d20 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
12d30 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53   SQLITE_MEMORY_S
12d40 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43  IZE=<i>NNN</i> C
12d50 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d60 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e  cro (where <i>NN
12d70 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69  N</i>.** is an i
12d80 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51  nteger), then SQ
12d90 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
12da0 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74  atic array of at
12db0 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e   least.** <i>NNN
12dc0 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
12dd0 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74  ze and uses that
12de0 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f   array for all o
12df0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a  f its dynamic.**
12e00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e10 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
12e20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   Additional memo
12e30 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
12e40 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  ions.** may be a
12e50 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
12e60 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
12e70 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
12e80 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
12e90 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
12ea0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
12eb0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
12ec0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
12ed0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
12ee0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
12ef0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
12f00 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
12f10 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
12f20 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
12f30 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
12f40 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
12f50 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
12f60 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
12f70 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
12f80 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
12f90 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
12fa0 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
12fb0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
12fc0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
12fd0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
12fe0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
12ff0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
13000 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
13010 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
13020 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
13030 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
13040 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
13050 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
13060 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
13070 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13080 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
13090 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
130a0 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
130b0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
130c0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
130d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
130e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
130f0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
13100 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
13110 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30   [H17303] [H1730
13120 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37  4] [H17305] [H17
13130 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48  306] [H17310] [H
13140 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20  17312] [H17315] 
13150 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37  [H17318].** [H17
13160 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48  321] [H17322] [H
13170 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65  17323].**.** The
13180 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
13190 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
131a0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
131b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
131c0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
131d0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
131e0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
131f0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
13200 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
13210 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13220 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
13230 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
13240 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
13250 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
13260 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13270 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
13280 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
13290 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
132a0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
132b0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
132c0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
132d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
132e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
132f0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
13300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
13310 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
13320 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
13330 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
13340 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
13350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13360 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
13370 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b  tor Statistics {
13380 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e  H17370} <S30210>
13390 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
133a0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
133b0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
133c0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
133d0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
133e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
133f0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
13400 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
13410 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
13420 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
13430 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
13440 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
13450 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
13460 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13470 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31  ents:.** [H17371
13480 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33  ] [H17373] [H173
13490 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a  74] [H17375].*/.
134a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
134b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
134c0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
134d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
134e0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
134f0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
13500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13510 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
13520 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
13530 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30  {H17390} <S20000
13540 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
13550 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
13560 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
13570 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
13580 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
13590 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
135a0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
135b0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
135c0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
135d0 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
135e0 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
135f0 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
13600 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
13610 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
13620 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
13630 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
13640 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
13650 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
13660 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
13670 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
13680 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
13690 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
136a0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
136b0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  urposes..**.** A
136c0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
136d0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
136e0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
136f0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
13700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
13710 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
13720 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
13730 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
13740 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
13750 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
13760 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
13770 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
13780 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
13790 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
137a0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
137b0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
137c0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
137d0 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
137e0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
137f0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
13800 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
13810 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
13820 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
13830 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
13840 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
13850 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
13860 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
13870 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d  nts:.** [H17392]
13880 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
13890 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
138a0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
138b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
138c0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
138d0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
138e0 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30  ks {H12500} <S70
138f0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100>.**.** This 
13900 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
13910 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
13920 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
13930 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
13940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13950 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
13960 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13970 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
13980 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
13990 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
139a0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
139b0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
139c0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
139d0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
139e0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
139f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
13a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
13a10 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
13a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
13a30 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
13a40 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
13a50 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
13a60 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
13a70 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
13a80 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
13a90 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
13aa0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
13ab0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
13ac0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
13ad0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
13ae0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
13af0 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
13b00 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
13b10 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
13b20 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
13b30 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
13b40 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
13b50 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
13b60 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
13b70 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
13b80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
13b90 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
13ba0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
13bb0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
13bc0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
13bd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
13be0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
13bf0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
13c00 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
13c10 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
13c20 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
13c30 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
13c40 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
13c50 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
13c60 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
13c70 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
13c80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
13c90 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
13ca0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
13cb0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
13cc0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
13cd0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
13ce0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
13cf0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13d00 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
13d10 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
13d20 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
13d30 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
13d40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
13d50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
13d60 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
13d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
13d80 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
13d90 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
13da0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
13db0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
13dc0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
13dd0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
13de0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
13df0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
13e00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
13e10 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
13e20 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
13e30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13e40 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
13e50 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
13e60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13e70 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
13e80 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
13e90 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
13ea0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
13eb0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
13ec0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
13ed0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
13ee0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
13ef0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
13f00 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
13f10 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
13f20 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
13f30 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
13f40 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
13f50 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
13f60 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
13f70 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
13f80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13f90 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
13fa0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
13fb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
13fc0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
13fd0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
13fe0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
13ff0 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
14000 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
14010 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
14020 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
14030 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
14040 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
14050 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14060 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
14070 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
14080 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
14090 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
140a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
140b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
140c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
140d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
140e0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
140f0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
14100 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
14110 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
14120 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
14130 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
14140 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14150 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
14160 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14170 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
14180 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
14190 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
141a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
141b0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
141c0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
141d0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
141e0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
141f0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
14200 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
14210 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
14220 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
14230 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
14240 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
14250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
14260 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
14270 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
14280 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
14290 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
142a0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
142b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
142c0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
142d0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
142e0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
142f0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
14300 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
14310 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
14320 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
14330 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
14340 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
14350 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
14360 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
14370 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
14380 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
14390 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
143a0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
143b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
143c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
143d0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
143e0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
143f0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
14400 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
14410 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
14420 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
14430 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
14440 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
14450 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
14460 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
14470 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
14480 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
14490 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
144a0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
144b0 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
144c0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
144d0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
144e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
144f0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
14500 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
14510 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
14520 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
14530 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
14540 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62  ous call.  Disab
14550 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
14560 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
14570 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
14580 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
14590 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
145a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
145b0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
145c0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
145d0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
145e0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
145f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
14600 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
14610 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
14620 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
14630 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
14640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
14650 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
14660 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
14670 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
14680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14690 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
146a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
146b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
146c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71  ..**.** When [sq
146d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
146e0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
146f0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
14700 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
14710 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
14720 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
14730 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14740 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
14750 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
14760 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
14770 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
14780 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
14790 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
147a0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
147b0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
147c0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
147d0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  step()]..**.** N
147e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
147f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14800 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
14810 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
14820 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
14830 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
14840 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
14850 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
14860 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
14870 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
14880 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
14890 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
148a0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35  ements:.** [H125
148b0 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31  01] [H12502] [H1
148c0 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b  2503] [H12504] [
148d0 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d  H12505] [H12506]
148e0 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31   [H12507] [H1251
148f0 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b  0].** [H12511] [
14900 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d  H12512] [H12520]
14910 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32   [H12521] [H1252
14920 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
14930 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
14940 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
14950 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
14960 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14970 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
14980 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
14990 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
149a0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
149b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
149c0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
149d0 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
149e0 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
149f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
14a00 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
14a10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14a20 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
14a30 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
14a40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
14a50 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
14a60 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
14a70 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
14a80 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
14a90 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
14aa0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
14ab0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
14ac0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
14ad0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
14ae0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
14af0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
14b00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
14b10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14b20 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
14b30 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
14b40 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
14b50 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
14b60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
14b70 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
14b80 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
14b90 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
14ba0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
14bb0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
14bc0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
14bd0 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
14be0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
14bf0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
14c00 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
14c10 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
14c20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
14c30 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
14c40 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
14c50 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
14c60 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
14c70 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
14c80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
14c90 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
14ca0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
14cb0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
14cc0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
14cd0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
14ce0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
14cf0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
14d00 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
14d10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14d20 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
14d30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
14d40 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
14d50 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
14d60 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
14d70 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
14d80 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
14d90 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
14da0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
14db0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
14dc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
14dd0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
14de0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
14df0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
14e00 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
14e10 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
14e20 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
14e30 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
14e40 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
14e50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
14e60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
14e70 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
14e80 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
14e90 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
14ea0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
14eb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
14ec0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14ed0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
14ee0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
14ef0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
14f00 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
14f10 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
14f20 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
14f30 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
14f40 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
14f50 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
14f60 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
14f70 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  L code..**.** Re
14f80 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
14f90 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d  H12551] [H12552]
14fa0 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35   [H12553] [H1255
14fb0 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  4].*/./*********
14fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14fe0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
14ff0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
15000 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
15010 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
15020 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
15030 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
15040 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15060 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
15070 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
15080 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15090 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
150a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
150b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
150c0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
150d0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
150e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
150f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15100 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
15110 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
15120 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
15130 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15150 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
15160 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
15170 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
15180 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
15190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
151a0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
151b0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
151c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
151d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
151e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
151f0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
15200 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
15210 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
15220 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
15230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15240 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
15250 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
15260 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
15270 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15280 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
15290 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
152a0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
152b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
152c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
152d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
152e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
152f0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
15300 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
15310 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15320 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15330 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
15340 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
15350 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15360 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15370 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
15380 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
15390 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
153a0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
153b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
153c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
153d0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
153e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
153f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15400 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15410 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15420 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
15430 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
15440 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15460 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
15470 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
15480 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
15490 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
154a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
154b0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
154c0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
154d0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
154e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
154f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15500 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
15510 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
15520 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
15530 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15550 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
15560 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
15570 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
155a0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
155b0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
155c0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
155d0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
155e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
155f0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
15600 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
15610 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
15620 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
15630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15640 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
15650 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
15660 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
15670 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
15690 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
156a0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
156b0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
156c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
156d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
156e0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
156f0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
15700 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
15710 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
15720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
15730 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
15740 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
15750 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
15760 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15770 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
15780 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
15790 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
157a0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
157b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
157c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
157d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
157e0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
157f0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
15800 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15810 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
15820 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
15830 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
15840 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15850 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15860 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
15870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
15880 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15890 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
158a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
158b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
158c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
158d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
158e0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
158f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15900 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
15910 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
15920 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
15930 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
15940 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15950 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
15960 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
15970 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
15980 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
15990 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
159a0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
159b0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
159c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
159d0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
159e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
159f0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
15a00 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
15a10 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
15a20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15a30 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
15a40 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
15a50 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
15a60 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
15a70 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
15a80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
15a90 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
15aa0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
15ab0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
15ac0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
15ad0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
15ae0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
15af0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
15b00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15b10 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
15b20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
15b30 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
15b40 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
15b50 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
15b60 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
15b70 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
15b80 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
15b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
15ba0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
15bb0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
15bc0 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
15bd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
15be0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
15bf0 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
15c00 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
15c10 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
15c20 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
15c30 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
15c40 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
15c50 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
15c60 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
15c70 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
15c80 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
15c90 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
15ca0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15cb0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
15cc0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
15cd0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
15ce0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
15cf0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
15d00 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
15d10 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
15d20 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
15d30 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
15d40 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
15d50 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
15d60 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
15d70 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
15d80 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
15d90 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
15da0 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31  .** [H12281] [H1
15db0 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b  2282] [H12283] [
15dc0 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d  H12284] [H12285]
15dd0 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38   [H12287] [H1228
15de0 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b  8] [H12289].** [
15df0 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54  H12290].*/.SQLIT
15e00 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
15e10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
15e20 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
15e30 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
15e40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
15e50 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
15e60 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
15e70 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
15e80 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
15e90 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
15ea0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
15eb0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
15ec0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
15ed0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
15ee0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
15ef0 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30  ks {H12910} <S60
15f00 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  400>.**.** This 
15f10 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
15f20 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
15f30 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
15f40 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
15f50 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
15f60 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
15f70 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
15f80 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
15f90 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
15fa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
15fb0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
15fc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
15fd0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
15fe0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
15ff0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
16000 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
16010 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
16020 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
16030 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
16040 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
16050 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
16060 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
16070 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
16080 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
16090 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
160a0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
160b0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
160c0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
160d0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
160e0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75  gress handler mu
160f0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
16100 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
16110 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
16120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
16130 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
16140 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
16150 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
16160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16170 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
16180 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
16190 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
161a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
161b0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
161c0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
161d0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
161e0 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ph..**.** Requir
161f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
16200 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31  11] [H12912] [H1
16210 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b  2913] [H12914] [
16220 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d  H12915] [H12916]
16230 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31   [H12917] [H1291
16240 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  8].**.*/.void sq
16250 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
16260 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
16270 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
16280 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
16290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
162a0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
162b0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
162c0 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
162d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
162e0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
162f0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
16300 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
16310 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
16320 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
16330 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
16340 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
16350 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
16360 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
16370 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
16380 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
16390 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
163a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
163b0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
163c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
163d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
163e0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
163f0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
16400 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
16410 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
16420 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
16430 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
16440 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
16450 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
16460 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
16470 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
16480 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
16490 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
164a0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
164b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
164c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
164d0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
164e0 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
164f0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
16500 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
16510 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
16520 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
16530 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
16540 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
16550 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
16560 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
16570 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
16580 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
16590 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
165a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
165b0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
165c0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
165d0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
165e0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
165f0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
16600 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
16610 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
16620 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
16630 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
16640 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
16650 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
16660 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
16670 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
16680 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
16690 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
166a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
166b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
166c0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
166d0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
166e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
166f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16700 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
16710 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
16720 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
16730 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
16740 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
16750 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
16760 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
16770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16780 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
16790 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
167a0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
167b0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
167c0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
167d0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
167e0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
167f0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
16800 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
16810 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
16820 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
16830 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
16840 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
16850 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
16860 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
16870 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
16880 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
16890 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
168a0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
168b0 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  gs:.**.** <dl>.*
168c0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
168d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
168e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
168f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
16900 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
16910 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
16920 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
16930 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
16940 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
16950 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
16960 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
16970 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
16980 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
16990 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
169a0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
169b0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
169c0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
169d0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
169e0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
169f0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
16a00 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
16a10 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
16a20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
16a30 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
16a40 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
16a50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
16a60 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
16a70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
16a80 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
16a90 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
16aa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
16ab0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
16ac0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
16ad0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
16ae0 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
16af0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
16b00 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
16b10 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
16b20 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
16b30 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
16b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
16b50 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
16b60 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  6().</dd>.** </d
16b70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
16b80 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
16b90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16ba0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
16bb0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
16bc0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
16bd0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
16be0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
16bf0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
16c00 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
16c10 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
16c20 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
16c30 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
16c40 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
16c50 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
16c60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
16c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
16c80 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
16c90 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
16ca0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16cb0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
16cc0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
16cd0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
16ce0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
16cf0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
16d00 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
16d10 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
16d20 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
16d30 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a  t-time.  If the.
16d40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
16d50 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
16d60 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
16d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16d80 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
16d90 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
16da0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
16db0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
16dc0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
16dd0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
16de0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
16df0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
16e00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
16e10 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
16e20 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
16e30 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
16e40 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
16e50 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
16e60 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
16e70 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
16e80 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
16e90 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
16ea0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16eb0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
16ec0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
16ed0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
16ee0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
16ef0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
16f00 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
16f10 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
16f20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
16f30 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
16f40 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
16f50 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
16f60 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
16f70 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
16f80 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
16f90 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
16fa0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
16fb0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
16fc0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
16fd0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
16fe0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
16ff0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
17000 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
17010 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
17020 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
17030 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
17040 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
17050 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
17060 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
17070 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
17080 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
17090 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
170a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
170b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
170c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
170d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
170e0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
170f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
17100 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
17110 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
17120 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
17130 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
17140 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
17150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
17160 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
17170 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17180 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
17190 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
171a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
171b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
171c0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
171d0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
171e0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
171f0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
17200 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
17210 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
17220 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
17230 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
17240 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
17250 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
17260 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
17270 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
17280 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
17290 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
172a0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
172b0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
172c0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
172d0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
172e0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
172f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
17300 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
17310 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
17320 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30 31  ents:.** [H12701
17330 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32 37  ] [H12702] [H127
17340 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48 31  03] [H12704] [H1
17350 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20 5b  2706] [H12707] [
17360 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31 5d  H12709] [H12711]
17370 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48 31  .** [H12712] [H1
17380 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20 5b  2713] [H12714] [
17390 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39 5d  H12717] [H12719]
173a0 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37 32   [H12721] [H1272
173b0 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  3].*/.int sqlite
173c0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
173d0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
173e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
173f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
17400 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
17410 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
17420 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
17430 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
17440 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
17450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
17460 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
17470 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
17480 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
17490 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
174a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
174b0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
174c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
174d0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
174e0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
174f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
17500 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
17510 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
17520 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
17530 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
17540 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
17550 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
17560 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
17570 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
17580 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
17590 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
175a0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
175b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
175c0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
175d0 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53  ages {H12800} <S
175e0 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60200>.**.** The
175f0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
17600 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
17610 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
17620 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
17630 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
17640 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
17650 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17660 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
17670 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
17680 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
17690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
176a0 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
176b0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
176c0 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
176d0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
176e0 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
176f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
17700 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
17710 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
17720 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ned.  The sqlite
17730 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
17740 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
17750 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
17760 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
17770 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
17780 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
17790 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
177a0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
177b0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
177c0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
177d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
177e0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
177f0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
17800 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
17810 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
17820 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
17830 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
17840 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
17850 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
17860 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
17870 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
17880 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
17890 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
178a0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
178b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
178c0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
178d0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
178e0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
178f0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
17900 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
17910 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
17920 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
17930 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
17940 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
17950 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
17960 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  s..**.** When th
17970 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
17980 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
17990 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
179a0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
179b0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
179c0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
179d0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
179e0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
179f0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
17a00 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
17a10 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
17a20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
17a30 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
17a40 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
17a50 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
17a60 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
17a70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
17a80 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
17a90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
17aa0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
17ab0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
17ac0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
17ad0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
17ae0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17af0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
17b00 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
17b10 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
17b20 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
17b30 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
17b40 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
17b50 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
17b60 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
17b70 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
17b80 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
17b90 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
17ba0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
17bb0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
17bc0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
17bd0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
17be0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
17bf0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
17c00 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
17c10 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
17c20 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
17c30 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
17c40 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
17c50 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
17c60 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
17c70 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
17c80 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ot be set..**.**
17c90 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
17ca0 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32 38  * [H12801] [H128
17cb0 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48 31  02] [H12803] [H1
17cc0 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b  2807] [H12808] [
17cd0 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H12809].*/.int s
17ce0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
17cf0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
17d00 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
17d10 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
17d20 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
17d30 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
17d40 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
17d50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
17d60 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
17d70 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17d80 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
17d90 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
17da0 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a  000} <H13010>.**
17db0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
17dc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
17dd0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
17de0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
17df0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
17e00 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
17e10 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
17e20 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
17e30 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
17e40 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
17e50 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
17e60 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
17e70 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
17e80 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
17e90 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
17ea0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
17eb0 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
17ec0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
17ed0 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
17ee0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
17ef0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
17f00 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
17f10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17f20 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
17f30 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
17f40 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
17f50 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
17f60 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
17f70 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
17f80 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
17f90 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
17fa0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
17fb0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
17fc0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
17fd0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
17fe0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
17ff0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
18000 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
18010 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
18020 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
18030 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
18040 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
18050 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
18060 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
18070 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
18080 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
18090 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
180a0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
180b0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
180c0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
180d0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
180e0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
180f0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
18100 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
18110 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
18120 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
18130 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53  mits {H12760} <S
18140 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20600>.**.** Thi
18150 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
18160 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
18170 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
18180 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
18190 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
181a0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
181b0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
181c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
181d0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
181e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
181f0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
18200 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
18210 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
18220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
18230 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
18240 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
18250 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
18260 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
18270 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
18280 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
18290 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
182a0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
182b0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
182c0 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
182d0 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
182e0 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  limit..**.** If 
182f0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
18300 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
18310 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
18320 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46   unchanged..** F
18330 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
18340 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
18350 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
18360 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
18370 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
18380 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61  und].** set by a
18390 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
183a0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
183b0 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69  ro named .** [li
183c0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
183d0 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20  X_XYZ]..** (The 
183e0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
183f0 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
18400 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
18410 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
18420 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
18430 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
18440 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
18450 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
18460 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
18470 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
18480 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
18490 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
184a0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
184b0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
184c0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
184d0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
184e0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
184f0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
18500 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
18510 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
18520 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
18530 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
18540 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
18550 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
18560 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
18570 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
18580 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
18590 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
185a0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
185b0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
185c0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
185d0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
185e0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
185f0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
18600 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
18610 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
18620 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
18630 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
18640 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
18650 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
18660 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
18670 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
18680 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
18690 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
186a0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
186b0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
186c0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
186d0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
186e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
186f0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
18700 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
18710 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
18720 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
18730 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
18740 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
18750 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
18760 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
18770 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
18780 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
18790 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
187a0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
187b0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
187c0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
187d0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
187e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
187f0 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31  .** [H12762] [H1
18800 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a  2766] [H12769].*
18810 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
18820 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
18830 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
18840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18850 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
18860 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48  it Categories {H
18870 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a  12790} <H12760>.
18880 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
18890 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c  mit category} {l
188a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
188b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
188c0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
188d0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
188e0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
188f0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
18900 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
18910 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
18920 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
18930 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
18940 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
18950 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
18960 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
18970 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
18980 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
18990 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
189a0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
189b0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
189c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
189d0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
189e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
189f0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
18a00 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
18a10 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
18a20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18a30 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
18a40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18a50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
18a60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18a70 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
18a80 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
18a90 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
18aa0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
18ab0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
18ac0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
18ad0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
18ae0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
18af0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
18b00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18b10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
18b20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
18b30 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
18b40 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
18b50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18b60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
18b70 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
18b80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
18b90 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
18ba0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
18bb0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
18bc0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18bd0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
18be0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
18bf0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18c00 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
18c10 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
18c20 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
18c30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18c40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
18c50 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
18c60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18c70 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
18c80 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
18c90 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
18ca0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
18cb0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
18cc0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
18cd0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18ce0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
18cf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18d00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18d10 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
18d20 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
18d30 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18d40 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
18d50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18d60 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18d70 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
18d80 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
18d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18da0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
18db0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
18dc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18dd0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
18de0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
18df0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
18e00 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
18e10 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
18e20 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18e30 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
18e40 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
18e50 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18e60 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
18e70 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
18e80 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
18e90 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
18ea0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
18eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ec0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
18ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18ee0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
18ef0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
18f00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18f10 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
18f20 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
18f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f40 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
18f50 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
18f60 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
18f70 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
18f80 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
18f90 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
18fa0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
18fb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
18fc0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
18fd0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
18fe0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
18ff0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
19000 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
19010 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
19020 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
19030 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
19040 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
19050 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
19060 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
19070 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
19080 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
19090 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a           9../*.*
190a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
190b0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
190c0 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20  tement {H13010} 
190d0 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10000>.** KEYW
190e0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
190f0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
19100 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
19110 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
19120 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
19130 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
19140 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
19150 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
19160 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
19170 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
19180 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
19190 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
191a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
191b0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
191c0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71  rior call to [sq
191d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
191e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
191f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
19200 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
19210 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19220 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
19230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
19240 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
19250 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
19260 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
19270 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
19280 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
19290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
192a0 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
192b0 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
192c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
192d0 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
192e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
192f0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
19300 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
19310 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
19320 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
19330 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
19340 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
19350 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
19360 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20  or. If nByte is 
19370 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
19380 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
19390 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
193a0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
193b0 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
193c0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
193d0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
193e0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
193f0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
19400 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
19410 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
19420 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
19430 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
19440 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
19450 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
19460 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
19470 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
19480 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
19490 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
194a0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
194b0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
194c0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
194d0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
194e0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
194f0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
19500 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
19510 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
19520 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
19530 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
19540 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
19550 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  ytes..**.** *pzT
19560 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
19570 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
19580 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
19590 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
195a0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
195b0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
195c0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
195d0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
195e0 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
195f0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
19600 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
19610 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
19620 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
19630 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
19640 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
19650 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
19660 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
19670 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
19680 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
19690 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
196a0 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  ()].  If there i
196b0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
196c0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
196d0 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
196e0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
196f0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
19700 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
19710 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
19720 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
19730 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
19740 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33  to NULL..** {A13
19750 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  018} The calling
19760 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
19770 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
19780 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
19790 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
197a0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
197b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
197c0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
197d0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
197e0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
197f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
19800 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
19810 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
19820 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
19830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19840 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
19850 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
19860 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
19870 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
19880 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
19890 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
198a0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
198b0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
198c0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
198d0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
198e0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
198f0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
19900 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
19910 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
19920 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19930 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
19940 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
19950 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
19960 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
19970 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
19980 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
19990 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
199a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
199b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
199c0 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
199d0 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
199e0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
199f0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
19a00 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
19a10 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
19a20 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
19a30 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19a40 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
19a50 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
19a60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19a70 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
19a80 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
19a90 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
19aa0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
19ab0 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
19ac0 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
19ad0 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
19ae0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
19af0 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
19b00 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
19b10 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
19b20 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
19b30 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
19b40 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
19b50 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
19b60 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
19b70 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74   is.** now a fat
19b80 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
19b90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
19ba0 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
19bb0 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
19bc0 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
19bd0 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b  ay.  Note: use [
19be0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
19bf0 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65  ] to find the te
19c00 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72  xt.** of the par
19c10 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20  sing error that 
19c20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53  results in an [S
19c30 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65  QLITE_SCHEMA] re
19c40 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  turn..** </li>.*
19c50 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65  *.** <li>.** Whe
19c60 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
19c70 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
19c80 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
19c90 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
19ca0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
19cb0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
19cc0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
19cd0 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   The legacy beha
19ce0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
19cf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19d00 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
19d10 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
19d20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
19d30 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
19d40 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
19d50 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
19d60 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
19d70 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64  _reset()] in ord
19d80 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  er.** to find th
19d90 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
19da0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
19db0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
19dc0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
19dd0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
19de0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
19df0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
19e00 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
19e10 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
19e20 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71   </ol>.**.** Req
19e30 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
19e40 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20  13011] [H13012] 
19e50 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34  [H13013] [H13014
19e60 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30  ] [H13015] [H130
19e70 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31  16] [H13019] [H1
19e80 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20  3021].**.*/.int 
19e90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
19ea0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
19eb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
19ec0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
19ed0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
19ee0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
19ef0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
19f00 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
19f10 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
19f20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
19f30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
19f40 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
19f50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
19f60 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
19f70 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
19f80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
19f90 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
19fa0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
19fb0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
19fc0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
19fd0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
19fe0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
19ff0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1a000 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1a010 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1a020 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1a030 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1a040 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1a050 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1a060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1a070 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1a080 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1a090 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1a0a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1a0b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1a0c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a0d0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1a0e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1a0f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1a100 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1a110 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1a120 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1a130 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a140 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a150 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a160 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1a170 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a180 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1a190 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1a1a0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1a1b0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1a1c0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1a1d0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1a1e0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1a1f0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1a200 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1a210 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1a220 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1a230 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1a240 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1a250 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1a260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1a270 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1a280 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1a290 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1a2a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1a2b0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1a2c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1a2d0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1a2e0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1a2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a300 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1a310 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1a320 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1a330 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1a340 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1a350 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a360 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1a370 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1a380 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1a390 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1a3a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1a3b0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1a3c0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48  Statement SQL {H
1a3d0 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a  13100} <H13000>.
1a3e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1a3f0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1a400 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1a410 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1a420 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1a430 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1a440 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1a450 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1a460 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1a470 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1a480 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1a490 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a4a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1a4b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1a4c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1a4d0 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b  s:.** [H13101] [
1a4e0 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d  H13102] [H13103]
1a4f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1a500 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1a510 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1a520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a530 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1a540 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1a550 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
1a560 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1a570 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1a580 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1a590 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a5a0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1a5b0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1a5c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a5d0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1a5e0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1a5f0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1a600 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1a610 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1a620 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1a630 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1a640 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
1a650 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1a660 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1a670 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1a680 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1a690 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1a6a0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1a6b0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1a6c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1a6d0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1a6e0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1a6f0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1a700 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1a710 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1a720 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a730 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1a740 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1a750 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1a760 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1a770 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1a780 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1a790 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1a7a0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1a7b0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1a7c0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1a7d0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1a7e0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1a7f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a800 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1a810 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1a820 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1a830 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1a840 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1a850 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1a860 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1a870 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1a880 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1a890 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1a8a0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1a8b0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1a8c0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1a8d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1a8e0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1a8f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1a900 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1a910 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1a920 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1a930 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1a940 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1a950 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1a960 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1a970 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1a980 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1a990 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1a9a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1a9b0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1a9c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1a9d0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1a9e0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1a9f0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1aa00 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1aa10 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1aa20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1aa30 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1aa40 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1aa50 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1aa60 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1aa70 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1aa80 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1aa90 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1aaa0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1aab0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1aac0 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1aad0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1aae0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1aaf0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ab00 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1ab10 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1ab20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1ab30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ab40 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1ab50 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1ab60 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1ab70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ab80 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1ab90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1aba0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1abb0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1abc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1abd0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1abe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1abf0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1ac00 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1ac10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ac20 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1ac30 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1ac40 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1ac50 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1ac60 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1ac70 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1ac80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1ac90 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1aca0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1acb0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1acc0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1acd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1ace0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1acf0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1ad00 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1ad10 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1ad20 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1ad30 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1ad40 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
1ad50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
1ad60 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1ad70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1ad80 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1ad90 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1ada0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1adb0 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
1adc0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1add0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1ade0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1adf0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1ae00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1ae10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1ae20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1ae30 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1ae40 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1ae50 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1ae60 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1ae70 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1ae80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1ae90 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1aea0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1aeb0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1aec0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1aed0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1aee0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1aef0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1af00 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1af10 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1af20 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1af30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1af40 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1af50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1af60 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1af70 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1af80 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1af90 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1afa0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
1afb0 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
1afc0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
1afd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
1afe0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
1aff0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1b000 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
1b010 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
1b020 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
1b030 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
1b040 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
1b050 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
1b060 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
1b070 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b080 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1b090 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1b0a0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1b0b0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1b0c0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
1b0d0 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
1b0e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1b0f0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1b100 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1b110 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1b120 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1b130 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
1b140 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
1b150 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
1b160 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1b170 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73  l,.** and VVV is
1b180 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69   an alpha-numeri
1b190 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
1b1a0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  . The values of 
1b1b0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1b1c0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1b1d0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1b1e0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1b1f0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1b200 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1b210 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1b220 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1b230 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1b240 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1b250 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1b260 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1b270 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1b280 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1b290 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1b2a0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1b2b0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1b2c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b2d0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1b2e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
1b2f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1b300 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1b310 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1b320 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68  to be set..** Th
1b330 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1b340 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1b350 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65  index of 1.  Whe
1b360 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
1b370 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1b380 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
1b390 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
1b3a0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
1b3b0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
1b3c0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
1b3d0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
1b3e0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54  occurrence..** T
1b3f0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
1b400 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
1b410 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
1b420 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
1b430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1b440 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
1b450 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1b460 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1b470 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1b480 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1b490 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1b4a0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1b4b0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1b4c0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1b4d0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
1b4e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
1b4f0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
1b500 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1b510 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
1b520 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1b530 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1b540 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1b550 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
1b560 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
1b570 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1b580 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1b590 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1b5a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1b5b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1b5c0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1b5d0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
1b5e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
1b5f0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
1b600 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1b610 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1b620 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ers..** If the f
1b630 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1b640 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1b650 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1b660 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1b670 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1b680 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1b690 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1b6a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1b6b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1b6c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1b6d0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1b6e0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1b6f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1b700 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1b710 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1b720 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1b730 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1b740 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1b750 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1b760 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1b770 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1b780 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1b790 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1b7a0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1b7b0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1b7c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1b7d0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1b7e0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1b7f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1b800 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
1b810 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1b820 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1b830 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1b840 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1b850 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1b860 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1b870 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1b880 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1b890 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b8a0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1b8b0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
1b8c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1b8d0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1b8e0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1b8f0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1b900 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1b910 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62  zeroes.  A zerob
1b920 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1b930 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1b940 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1b950 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1b960 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1b970 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1b980 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1b990 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1b9a0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1b9b0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1b9c0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1b9d0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1b9e0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1b9f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1ba00 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1ba10 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1ba20 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  ..** A negative 
1ba30 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1ba40 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1ba50 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1ba60 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1ba70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1ba80 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1ba90 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1baa0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1bab0 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1bac0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1bad0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1bae0 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1baf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1bb00 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1bb10 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1bb20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1bb30 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1bb40 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1bb50 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1bb60 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1bb70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1bb80 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1bb90 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1bba0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1bbb0 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1bbc0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1bbd0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1bbe0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1bbf0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1bc00 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1bc10 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1bc20 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1bc30 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
1bc40 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1bc50 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1bc60 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1bc70 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1bc80 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1bc90 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1bca0 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1bcb0 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1bcc0 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1bcd0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1bce0 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1bcf0 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1bd00 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1bd10 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1bd20 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1bd30 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1bd40 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1bd50 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1bd60 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1bd70 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1bd80 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1bd90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1bda0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1bdb0 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1bdc0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1bdd0 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1bde0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1bdf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1be00 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1be10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1be20 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1be30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1be40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1be50 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
1be60 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30  ments:.** [H1350
1be70 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33  6] [H13509] [H13
1be80 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48  512] [H13515] [H
1be90 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20  13518] [H13521] 
1bea0 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37  [H13524] [H13527
1beb0 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48  ].** [H13530] [H
1bec0 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20  13533] [H13536] 
1bed0 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32  [H13539] [H13542
1bee0 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35  ] [H13545] [H135
1bef0 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a  48] [H13551].**.
1bf00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1bf10 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1bf20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1bf30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1bf40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1bf50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1bf60 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1bf70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1bf80 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1bf90 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1bfa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1bfb0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1bfc0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1bfd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1bfe0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1bff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c000 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1c010 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1c020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c030 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1c040 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1c050 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1c060 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c080 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1c090 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1c0a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1c0b0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1c0c0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1c0d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c0e0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1c0f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1c100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1c110 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1c120 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1c130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c140 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1c150 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
1c160 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
1c170 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c180 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1c190 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1c1a0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
1c1b0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
1c1c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c1d0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
1c1e0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
1c1f0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
1c200 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
1c210 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
1c220 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
1c230 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
1c240 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1c250 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1c260 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1c270 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1c280 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1c290 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
1c2a0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
1c2b0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
1c2c0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
1c2d0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
1c2e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
1c2f0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
1c300 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
1c310 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
1c320 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1c330 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
1c340 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
1c350 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
1c360 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
1c370 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
1c380 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
1c390 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1c3a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1c3b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1c3c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1c3d0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1c3e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1c3f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1c400 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1c410 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1c420 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a  .** [H13601].*/.
1c430 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1c440 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1c450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1c460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c470 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1c480 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
1c490 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  20} <S70300>.**.
1c4a0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1c4b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c4c0 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
1c4d0 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51   the n-th.** [SQ
1c4e0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
1c4f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1c500 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1c510 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1c520 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1c530 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1c540 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1c550 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1c560 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1c570 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1c580 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1c590 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1c5a0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1c5b0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1c5c0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1c5d0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1c5e0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1c5f0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
1c600 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
1c610 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1c620 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1c630 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1c640 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1c650 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20  e also referred 
1c660 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73  to as "anonymous
1c670 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
1c680 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
1c690 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1c6a0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
1c6b0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
1c6c0 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
1c6d0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
1c6e0 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
1c6f0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
1c700 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
1c710 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1c720 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1c730 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
1c740 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1c750 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
1c760 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
1c770 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
1c780 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
1c790 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
1c7a0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
1c7b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c7c0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1c7d0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1c7e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1c7f0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1c800 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1c810 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1c820 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1c830 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1c840 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1c850 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1c860 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a  .** [H13621].*/.
1c870 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1c880 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1c890 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
1c8a0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
1c8b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1c8c0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
1c8d0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
1c8e0 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
1c8f0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
1c900 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1c910 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1c920 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1c930 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
1c940 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
1c950 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
1c960 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
1c970 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1c980 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1c990 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1c9a0 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
1c9b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1c9c0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1c9d0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1c9e0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1c9f0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1ca00 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1ca10 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1ca20 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1ca30 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1ca40 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1ca50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1ca60 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1ca70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1ca80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1ca90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1caa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1cab0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1cac0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1cad0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1cae0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1caf0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1cb00 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a  s:.** [H13641].*
1cb10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1cb20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1cb30 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
1cb40 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1cb50 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
1cb60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
1cb70 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
1cb80 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1cb90 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
1cba0 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
1cbb0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
1cbc0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
1cbd0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
1cbe0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
1cbf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1cc00 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
1cc10 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
1cc20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1cc30 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
1cc40 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
1cc50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1cc60 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52  to NULL..**.** R
1cc70 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1cc80 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13661].*/.int 
1cc90 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
1cca0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
1ccb0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1ccc0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1ccd0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
1cce0 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31  esult Set {H1371
1ccf0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1cd00 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
1cd10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1cd20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1cd30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1cd40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1cd50 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
1cd60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
1cd70 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1cd80 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1cd90 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
1cda0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
1cdb0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
1cdc0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  TE])..**.** Requ
1cdd0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1cde0 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3711].*/.int sql
1cdf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
1ce00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1ce10 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1ce20 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
1ce30 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
1ce40 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c  t Set {H13720} <
1ce50 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1ce60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1ce70 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
1ce80 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
1ce90 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
1cea0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1ceb0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1cec0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
1ced0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1cee0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
1cef0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1cf00 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1cf10 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1cf20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
1cf30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1cf40 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
1cf50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
1cf60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1cf70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
1cf80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1cf90 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
1cfa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
1cfb0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
1cfc0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
1cfd0 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73  statement. The s
1cfe0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1cff0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
1d000 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1d010 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
1d020 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
1d030 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1d040 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
1d050 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
1d060 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
1d070 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
1d080 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
1d090 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d0a0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1d0b0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
1d0c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d0d0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
1d0e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1d0f0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
1d100 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
1d110 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d120 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
1d130 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
1d140 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
1d150 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
1d160 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
1d170 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
1d180 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
1d190 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1d1a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1d1b0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
1d1c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
1d1d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1d1e0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
1d1f0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
1d200 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
1d210 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
1d220 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
1d230 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
1d240 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
1d250 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
1d260 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
1d270 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
1d280 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
1d290 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
1d2a0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1d2b0 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48  :.** [H13721] [H
1d2c0 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20  13723] [H13724] 
1d2d0 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36  [H13725] [H13726
1d2e0 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f  ] [H13727].*/.co
1d2f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1d300 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
1d310 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d320 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
1d330 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1d340 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1d350 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
1d360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1d370 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
1d380 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1d390 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30  {H13740} <S10700
1d3a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1d3b0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1d3c0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1d3d0 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
1d3e0 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
1d3f0 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
1d400 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
1d410 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1d420 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a  ent comes from..
1d430 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
1d440 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
1d450 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
1d460 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
1d470 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
1d480 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
1d490 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
1d4a0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
1d4b0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
1d4c0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
1d4d0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
1d4e0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
1d4f0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
1d500 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
1d510 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
1d520 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
1d530 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1d540 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
1d550 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
1d560 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1d570 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
1d580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1d590 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
1d5a0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
1d5b0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
1d5c0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
1d5d0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
1d5e0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
1d5f0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
1d600 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
1d610 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
1d620 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d630 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
1d640 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
1d650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d660 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
1d670 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
1d680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1d690 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1d6a0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
1d6b0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
1d6c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
1d6d0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1d6e0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1d6f0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1d700 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1d710 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
1d720 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1d730 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
1d740 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
1d750 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
1d760 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
1d770 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
1d780 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
1d790 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1d7a0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73  n.** NULL.  Thes
1d7b0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
1d7c0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
1d7d0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
1d7e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
1d7f0 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
1d800 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
1d810 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1d820 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1d830 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64  se, table.** and
1d840 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1d850 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
1d860 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
1d870 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
1d880 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
1d890 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
1d8a0 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
1d8b0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
1d8c0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
1d8d0 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
1d8e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1d8f0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
1d900 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
1d910 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1d920 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1d930 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1d940 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
1d950 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1d960 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
1d970 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1d980 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1d990 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  A13751}.** If tw
1d9a0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1d9b0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1d9c0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1d9d0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1d9e0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1d9f0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1da00 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1da10 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1da20 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1da30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1da40 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1da50 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37  * [H13741] [H137
1da60 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31  42] [H13743] [H1
1da70 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b  3744] [H13745] [
1da80 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d  H13746] [H13748]
1da90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
1daa0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1dab0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
1dac0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1dad0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
1dae0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
1daf0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
1db00 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
1db10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1db20 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
1db30 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
1db40 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1db50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1db60 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
1db70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1db80 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1db90 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1dba0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1dbb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1dbc0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1dbd0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1dbe0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
1dbf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1dc00 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
1dc10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1dc20 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1dc30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1dc40 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
1dc50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1dc60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1dc70 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
1dc80 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1dc90 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1dca0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1dcb0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
1dcc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1dcd0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1dce0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
1dcf0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
1dd00 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
1dd10 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
1dd20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1dd30 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
1dd40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1dd50 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
1dd60 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
1dd70 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
1dd80 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
1dd90 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
1dda0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
1ddb0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
1ddc0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
1ddd0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
1dde0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
1ddf0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
1de00 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
1de10 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
1de20 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
1de30 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
1de40 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
1de50 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
1de60 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1de70 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
1de80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1de90 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
1dea0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1deb0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
1dec0 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
1ded0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1dee0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
1def0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1df00 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1df10 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1df20 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
1df30 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1df40 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
1df50 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
1df60 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
1df70 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
1df80 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
1df90 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
1dfa0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
1dfb0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
1dfc0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
1dfd0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
1dfe0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
1dff0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
1e000 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
1e010 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1e020 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
1e030 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
1e040 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
1e050 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
1e060 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
1e070 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
1e080 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
1e090 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
1e0a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
1e0b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
1e0c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
1e0d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
1e0e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
1e0f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
1e100 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
1e110 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
1e120 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
1e130 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
1e140 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
1e150 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
1e160 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
1e170 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1e180 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48  :.** [H13761] [H
1e190 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a  13762] [H13763].
1e1a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1e1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1e1c0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
1e1d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1e1e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1e1f0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
1e200 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e210 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1e220 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
1e230 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1e240 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30  {H13200} <S10000
1e250 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  >.**.** After a 
1e260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e270 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
1e280 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
1e290 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
1e2a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e2b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e2c0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
1e2d0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
1e2e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
1e2f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e300 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1e310 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
1e320 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
1e330 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
1e340 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1e350 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
1e360 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
1e370 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
1e380 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
1e390 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1e3a0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
1e3b0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
1e3c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
1e3d0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1e3e0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
1e3f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
1e400 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e410 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e420 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
1e430 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
1e440 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
1e450 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e460 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1e470 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
1e480 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
1e490 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
1e4a0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
1e4b0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
1e4c0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
1e4d0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
1e4e0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
1e4f0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
1e500 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
1e510 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1e520 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
1e530 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
1e540 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
1e550 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
1e560 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
1e570 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
1e580 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
1e590 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
1e5a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1e5b0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
1e5c0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
1e5d0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
1e5e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
1e5f0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1e600 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
1e610 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1e620 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
1e630 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
1e640 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
1e650 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
1e660 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
1e670 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
1e680 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
1e690 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
1e6a0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
1e6b0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
1e6c0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1e6d0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
1e6e0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
1e6f0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
1e700 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
1e710 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
1e720 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1e730 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
1e740 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
1e750 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
1e760 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
1e770 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
1e780 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53  inuing..**.** [S
1e790 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
1e7a0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
1e7b0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
1e7c0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
1e7d0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
1e7e0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
1e7f0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
1e800 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
1e810 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
1e820 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
1e830 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1e840 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
1e850 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
1e860 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
1e870 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
1e880 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tate..**.** If t
1e890 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e8a0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
1e8b0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
1e8c0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
1e8d0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
1e8e0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
1e8f0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
1e900 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
1e910 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
1e920 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
1e930 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
1e940 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
1e950 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1e960 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
1e970 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
1e980 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
1e990 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
1e9a0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
1e9b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
1e9c0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
1e9d0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
1e9e0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
1e9f0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
1ea00 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
1ea10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1ea20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
1ea30 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
1ea40 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
1ea50 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
1ea60 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
1ea70 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
1ea80 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
1ea90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1eaa0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
1eab0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
1eac0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
1ead0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1eae0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
1eaf0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
1eb00 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
1eb10 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
1eb20 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
1eb30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1eb40 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
1eb50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1eb60 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
1eb70 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
1eb80 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
1eb90 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
1eba0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
1ebb0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
1ebc0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
1ebd0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
1ebe0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
1ebf0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
1ec00 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
1ec10 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
1ec20 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
1ec30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ec40 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
1ec50 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
1ec60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1ec70 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
1ec80 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
1ec90 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
1eca0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
1ecb0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
1ecc0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
1ecd0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
1ece0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
1ecf0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1ed00 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
1ed10 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
1ed20 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
1ed30 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
1ed40 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
1ed50 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
1ed60 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
1ed70 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
1ed80 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
1ed90 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
1eda0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
1edb0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
1edc0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
1edd0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
1ede0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
1edf0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1ee00 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
1ee10 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
1ee20 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
1ee30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1ee40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1ee50 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
1ee60 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
1ee70 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1ee80 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
1ee90 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
1eea0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
1eeb0 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
1eec0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
1eed0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
1eee0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
1eef0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
1ef00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
1ef10 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
1ef20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
1ef30 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
1ef40 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1ef50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ef60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1ef70 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
1ef80 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
1ef90 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
1efa0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
1efb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1efc0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
1efd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
1efe0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
1eff0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
1f000 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
1f010 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
1f020 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
1f030 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1f040 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f050 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
1f060 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32  ements:.** [H132
1f070 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31  02] [H15304] [H1
1f080 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b  5306] [H15308] [
1f090 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H15310].*/.int s
1f0a0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
1f0b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1f0c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1f0d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1f0e0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
1f0f0 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
1f100 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
1f110 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
1f120 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
1f130 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
1f140 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
1f150 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1f160 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37   [H13771] [H1377
1f170 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
1f180 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
1f190 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1f1a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f1b0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
1f1c0 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36  Datatypes {H1026
1f1d0 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31  5} <S10110><S101
1f1e0 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20>.** KEYWORDS:
1f1f0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
1f200 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72  ** {H10266} Ever
1f210 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
1f220 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
1f230 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
1f240 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
1f250 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
1f260 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f270 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
1f280 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
1f290 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
1f2a0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
1f2b0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
1f2c0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
1f2d0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
1f2e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
1f2f0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
1f300 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
1f310 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
1f320 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
1f330 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
1f340 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
1f350 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
1f360 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
1f370 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
1f380 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
1f390 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
1f3a0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
1f3b0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
1f3c0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
1f3d0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
1f3e0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
1f3f0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
1f400 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
1f410 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1f420 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
1f430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
1f440 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
1f450 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
1f460 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
1f470 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
1f480 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
1f490 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
1f4a0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
1f4b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
1f4c0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
1f4d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1f4e0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
1f4f0 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d  A Query {H13800}
1f500 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
1f510 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
1f520 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
1f530 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1f540 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
1f550 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
1f560 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
1f570 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f580 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
1f590 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
1f5a0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
1f5b0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
1f5c0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
1f5d0 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
1f5e0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
1f5f0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
1f600 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
1f610 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f620 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
1f630 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
1f640 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
1f650 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
1f660 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1f670 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f680 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1f690 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
1f6a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1f6b0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1f6c0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
1f6d0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
1f6e0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
1f6f0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1f700 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
1f710 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
1f720 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
1f730 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
1f740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
1f750 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
1f760 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
1f770 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
1f780 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
1f790 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1f7a0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
1f7b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
1f7c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
1f7d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1f7e0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
1f7f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
1f800 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f810 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
1f820 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
1f830 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
1f840 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
1f850 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f860 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
1f870 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
1f880 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
1f890 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1f8a0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
1f8b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1f8c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1f8d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1f8e0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
1f8f0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
1f900 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
1f910 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
1f920 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
1f930 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
1f940 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
1f950 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
1f960 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1f970 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
1f980 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
1f990 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
1f9a0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
1f9b0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
1f9c0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
1f9d0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
1f9e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
1f9f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1fa00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
1fa10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
1fa20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
1fa30 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
1fa40 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
1fa50 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
1fa60 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
1fa70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
1fa80 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
1fa90 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
1faa0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
1fab0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
1fac0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
1fad0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
1fae0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
1faf0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
1fb00 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1fb10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
1fb20 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
1fb30 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
1fb40 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
1fb50 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
1fb60 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
1fb70 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
1fb80 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
1fb90 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
1fba0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1fbb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
1fbc0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
1fbd0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
1fbe0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
1fbf0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
1fc00 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
1fc10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
1fc20 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
1fc30 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
1fc40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
1fc50 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
1fc60 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
1fc70 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
1fc80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
1fc90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1fca0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1fcb0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
1fcc0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
1fcd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
1fce0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
1fcf0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
1fd00 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
1fd10 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
1fd20 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
1fd30 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
1fd40 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1fd50 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
1fd60 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
1fd70 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
1fd80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
1fd90 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
1fda0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
1fdb0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
1fdc0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
1fdd0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
1fde0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
1fdf0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1fe00 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
1fe10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1fe20 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1fe30 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
1fe40 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
1fe50 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
1fe60 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
1fe70 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1fe80 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
1fe90 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
1fea0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
1feb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1fec0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1fed0 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
1fee0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
1fef0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
1ff00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1ff10 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
1ff20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
1ff30 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
1ff40 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
1ff50 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1ff60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
1ff70 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
1ff80 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1ff90 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
1ffa0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
1ffb0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
1ffc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1ffd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
1ffe0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
1fff0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
20000 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
20010 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
20020 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
20030 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
20040 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
20050 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
20060 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
20070 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
20080 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
20090 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
200a0 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
200b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
200c0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
200d0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
200e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
200f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
20100 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
20110 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20120 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
20130 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
20140 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
20150 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20160 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
20170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
20180 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20190 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
201a0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
201b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
201c0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
201d0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
201e0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
201f0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
20200 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
20210 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
20220 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
20230 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
20240 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
20250 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
20260 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
20270 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
20280 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
20290 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
202a0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
202b0 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
202c0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
202d0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
202e0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
202f0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
20300 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
20310 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
20320 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
20330 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
20340 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
20350 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
20360 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
20370 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
20380 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
20390 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
203a0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
203b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
203c0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
203d0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
203e0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
203f0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
20400 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
20410 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
20420 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
20430 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
20440 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
20450 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
20460 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
20470 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
20480 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
20490 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
204a0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
204b0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
204c0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
204d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
204e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
204f0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20500 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20510 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
20520 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
20530 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
20540 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
20550 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
20560 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
20570 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
20580 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
20590 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
205a0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
205b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
205c0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
205d0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
205e0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
205f0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
20600 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
20610 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
20620 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20630 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
20640 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
20650 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
20660 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
20670 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
20680 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
20690 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
206a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
206b0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
206c0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
206d0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
206e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
206f0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
20700 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
20710 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
20720 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20730 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
20740 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
20750 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
20760 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
20770 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
20780 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20790 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
207a0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
207b0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
207c0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
207d0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
207e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
207f0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
20800 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
20810 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
20820 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
20830 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
20840 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
20850 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
20860 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
20870 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
20880 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
20890 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
208a0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
208b0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
208c0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
208d0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
208e0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
208f0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
20900 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
20910 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
20920 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
20930 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
20940 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
20950 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
20960 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
20970 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
20980 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
20990 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
209a0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
209b0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
209c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
209d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
209e0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
209f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
20a00 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
20a10 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
20a20 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
20a30 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
20a40 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
20a50 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
20a60 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
20a70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
20a80 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
20a90 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
20aa0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
20ab0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
20ac0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
20ad0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
20ae0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
20af0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
20b00 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
20b10 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
20b20 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
20b30 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
20b40 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
20b50 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
20b60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20b70 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
20b80 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
20b90 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
20ba0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
20bb0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
20bc0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
20bd0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
20be0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
20bf0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
20c00 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
20c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
20c20 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
20c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20c40 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
20c50 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
20c60 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
20c70 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
20c80 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
20c90 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
20ca0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
20cb0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
20cc0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
20cd0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
20ce0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
20cf0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
20d00 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
20d10 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
20d20 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
20d30 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
20d40 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
20d50 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
20d60 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
20d70 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
20d80 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
20d90 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
20da0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
20db0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
20dc0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
20dd0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
20de0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
20df0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
20e00 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
20e10 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
20e20 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
20e30 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
20e40 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
20e50 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
20e60 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
20e70 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
20e80 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
20e90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
20ea0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
20eb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
20ec0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
20ed0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
20ee0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
20ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20f00 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
20f10 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
20f20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
20f30 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
20f40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
20f50 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
20f60 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
20f70 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
20f80 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
20f90 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
20fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20fb0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
20fc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
20fd0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
20fe0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
20ff0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
21000 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
21010 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
21020 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
21030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21040 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
21050 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
21060 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
21070 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
21080 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
21090 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
210a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
210b0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
210c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
210d0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
210e0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
210f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
21100 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
21110 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
21120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21130 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
21140 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
21150 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
21160 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
21170 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
21180 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
21190 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
211a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
211b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
211c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
211d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
211e0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
211f0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
21200 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
21210 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
21220 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
21230 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
21240 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
21250 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
21260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21270 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
21280 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
21290 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
212a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
212b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
212c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
212d0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
212e0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
212f0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
21300 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
21310 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
21320 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
21330 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
21340 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
21350 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
21360 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
21370 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
21380 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
21390 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
213a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
213b0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
213c0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
213d0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  MEM]..**.** Requ
213e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
213f0 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b  3803] [H13806] [
21400 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d  H13809] [H13812]
21410 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31   [H13815] [H1381
21420 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33  8] [H13821] [H13
21430 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d  824].** [H13827]
21440 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e   [H13830].*/.con
21450 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21460 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
21470 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21480 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
21490 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
214a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
214b0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
214c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
214d0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
214e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
214f0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
21500 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
21510 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21520 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
21530 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
21540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21550 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
21560 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
21570 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
21580 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21590 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
215a0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
215b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
215c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
215d0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
215e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
215f0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
21600 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
21620 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
21630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21640 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
21650 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
21660 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
21670 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21690 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
216a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
216b0 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d   Object {H13300}
216c0 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30   <S70300><S30100
216d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
216e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
216f0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
21700 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
21710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21720 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
21730 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
21740 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
21750 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
21760 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
21770 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
21780 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
21790 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
217a0 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
217b0 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
217c0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
217d0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
217e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
217f0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
21800 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
21810 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
21820 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
21830 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
21840 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
21850 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
21860 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
21870 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
21880 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
21890 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
218a0 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
218b0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
218c0 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
218d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
218e0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
218f0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
21900 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
21910 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
21920 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
21930 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
21940 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
21950 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
21960 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
21970 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
21980 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
21990 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
219a0 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20  ts:.** [H11302] 
219b0 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20  [H11304].*/.int 
219c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
219d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
219e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
219f0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
21a00 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
21a10 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33  nt Object {H1333
21a20 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
21a30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
21a40 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
21a50 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
21a60 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
21a70 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
21a80 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
21a90 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
21aa0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
21ab0 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
21ac0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
21ad0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
21ae0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
21af0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
21b00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21b10 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
21b20 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
21b30 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
21b40 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
21b50 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
21b60 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
21b70 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
21b80 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {H11332} The [sq
21b90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
21ba0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
21bb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21bc0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
21bd0 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
21be0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
21bf0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
21c00 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20  .** {H11334} If 
21c10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
21c20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
21c30 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
21c40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
21c50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21c60 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
21c70 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
21c80 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
21c90 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
21ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21cb0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
21cc0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
21cd0 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
21ce0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
21cf0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
21d00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
21d10 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74  ** {H11336} If t
21d20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
21d30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21d40 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
21d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
21d60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21d70 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
21d80 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
21d90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21da0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
21db0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
21dc0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
21dd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20  .**.** {H11338} 
21de0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
21df0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
21e00 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
21e10 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
21e20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
21e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21e40 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
21e50 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21e60 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
21e70 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
21e80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
21e90 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
21ea0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
21eb0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
21ec0 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d  nctions {H16100}
21ed0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
21ee0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
21ef0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
21f00 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
21f10 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
21f20 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
21f30 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
21f40 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
21f50 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
21f60 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
21f70 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
21f80 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
21f90 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
21fa0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
21fb0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
21fc0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
21fd0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
21fe0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
21ff0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
22000 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
22010 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
22020 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
22030 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
22040 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
22050 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
22060 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
22070 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22080 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
22090 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
220a0 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
220b0 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
220c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
220d0 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
220e0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
220f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
22100 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
22110 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
22120 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
22130 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
22140 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
22150 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
22160 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73  e added.  If a s
22170 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73  ingle program us
22180 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
22190 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
221a0 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c  nection internal
221b0 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e  ly, then SQL fun
221c0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
221d0 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
221e0 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74  y to.** each dat
221f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
22210 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
22220 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22230 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
22240 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
22250 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65   redefined.  The
22260 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
22270 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
22280 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
22290 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65  lusive of.** the
222a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
222b0 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
222c0 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d   name length lim
222d0 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20  it is in bytes, 
222e0 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  not.** character
222f0 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  s.  Any attempt 
22300 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
22310 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
22320 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
22330 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
22340 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
22350 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
22360 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22370 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
22380 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
22390 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
223a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
223b0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
223c0 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
223d0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
223e0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
223f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
22400 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
22410 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
22420 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
22430 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
22440 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
22450 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
22460 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
22470 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
22480 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
22490 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
224a0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
224b0 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
224c0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
224d0 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
224e0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
224f0 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
22500 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
22510 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
22520 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
22530 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
22540 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
22550 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
22560 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
22570 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
22580 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
22590 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
225a0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
225b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
225c0 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
225d0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
225e0 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
225f0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
22600 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
22610 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
22620 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
22630 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
22640 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
22650 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
22660 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
22670 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
22680 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
22690 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
226a0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
226b0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
226c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
226d0 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
226e0 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
226f0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
22700 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
22710 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
22720 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
22730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
22740 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
22750 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
22760 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
22770 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
22780 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
22790 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
227a0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
227b0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
227c0 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
227d0 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
227e0 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
227f0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
22800 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
22810 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
22820 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
22830 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
22840 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
22850 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
22860 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
22870 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
22880 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
22890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
228a0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
228b0 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
228c0 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
228d0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
228e0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
228f0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
22900 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
22910 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
22920 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
22930 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
22940 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
22950 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
22960 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
22970 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
22980 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
22990 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
229a0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
229b0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
229c0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
229d0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
229e0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
229f0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
22a00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
22a10 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
22a20 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
22a30 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
22a40 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
22a50 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
22a60 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
22a70 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
22a80 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
22a90 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
22aa0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
22ab0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
22ac0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
22ad0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
22ae0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
22af0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66  on is used.  A f
22b00 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
22b10 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
22b20 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
22b30 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
22b40 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
22b50 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
22b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
22b70 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
22b80 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69   nArg.  A functi
22b90 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
22ba0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
22bb0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
22bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
22bd0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
22be0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
22bf0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
22c00 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
22c10 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
22c20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   A function wher
22c30 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
22c40 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
22c50 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
22c60 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
22c70 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
22c80 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
22c90 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
22ca0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
22cb0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
22cc0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
22cd0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
22ce0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
22cf0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
22d00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
22d10 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  functions..** Th
22d20 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74  e first applicat
22d30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
22d40 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65  tion with a give
22d50 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73  n name overrides
22d60 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e   all.** built-in
22d70 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
22d80 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
22d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74   connection] wit
22da0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  h the same name.
22db0 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
22dc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
22dd0 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20  ed functions of 
22de0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e  the same name on
22df0 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20  ly override .** 
22e00 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f  prior applicatio
22e10 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
22e20 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20  ons that are an 
22e30 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20  exact match for 
22e40 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
22e50 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
22e60 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69  preferred encodi
22e70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70  ng..**.** An app
22e80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22e90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
22ea0 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
22eb0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
22ec0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
22ed0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
22ee0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
22ef0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
22f00 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
22f10 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
22f20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
22f30 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
22f40 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
22f50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
22f60 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
22f70 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36  ** [H16103] [H16
22f80 31 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48  106] [H16109] [H
22f90 31 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20  16112] [H16118] 
22fa0 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32 34  [H16121] [H16124
22fb0 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48  ] [H16127].** [H
22fc0 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20  16130] [H16133] 
22fd0 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39  [H16136] [H16139
22fe0 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e  ] [H16142].*/.in
22ff0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
23000 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
23010 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
23020 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
23030 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
23040 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
23050 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
23060 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
23070 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23080 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
23090 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
230a0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
230b0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
230c0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
230d0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
230e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
230f0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
23100 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23110 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
23120 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
23130 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
23140 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
23150 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
23160 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
23170 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
23180 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
23190 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
231a0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
231b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
231c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
231d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
231e0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
231f0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
23200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
23210 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48  ext Encodings {H
23220 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20  10267} <S50200> 
23230 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H16100>.**.** T
23240 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
23250 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
23260 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
23270 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
23280 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
23290 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
232a0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
232b0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
232c0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
232d0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
232e0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
232f0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
23300 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
23310 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
23320 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
23330 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
23340 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
23350 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
23360 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
23370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23380 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
23390 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
233a0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
233b0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
233c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
233d0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
233e0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
233f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
23400 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
23410 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
23420 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
23430 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
23440 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
23450 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
23460 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
23470 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
23480 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
23490 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
234a0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
234b0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
234c0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
234d0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
234e0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
234f0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
23500 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
23510 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
23520 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
23530 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
23540 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
23550 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
23560 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
23570 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23580 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
23590 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
235a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
235b0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
235c0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
235d0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
235e0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
235f0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
23600 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
23610 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
23620 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
23630 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
23640 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
23650 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
23660 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
23670 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
23680 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
23690 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
236a0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
236b0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
236c0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
236d0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
236e0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
236f0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
23700 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
23710 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
23720 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
23730 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
23740 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32  s {H15100} <S202
23750 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00>.**.** The C-
23760 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
23770 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
23780 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
23790 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
237a0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
237b0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
237c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
237d0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
237e0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
237f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
23800 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
23810 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
23820 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
23830 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
23840 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
23850 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
23860 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
23870 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
23880 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
23890 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
238a0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
238b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
238c0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
238d0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
238e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
238f0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
23900 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
23910 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
23920 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23930 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
23940 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
23950 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23960 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
23970 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
23980 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
23990 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
239a0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
239b0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
239c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
239d0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
239e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
239f0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
23a00 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
23a10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23a20 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
23a30 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
23a40 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
23a50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
23a60 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
23a70 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
23a80 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
23a90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
23aa0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
23ab0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
23ac0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
23ad0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
23ae0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
23af0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
23b00 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
23b10 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
23b20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23b30 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
23b40 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
23b50 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
23b60 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
23b70 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
23b80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23b90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
23ba0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
23bb0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
23bc0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
23bd0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
23be0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
23bf0 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
23c00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
23c10 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
23c20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
23c30 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
23c40 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
23c50 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
23c60 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
23c70 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
23c80 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  vely..**.** The 
23c90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
23ca0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
23cb0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
23cc0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
23cd0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
23ce0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
23cf0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
23d00 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
23d10 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
23d20 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
23d30 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
23d40 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
23d50 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
23d60 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
23d70 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
23d80 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
23d90 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
23da0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
23db0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
23dc0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
23dd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
23de0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
23df0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
23e00 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
23e10 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
23e20 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
23e30 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
23e40 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
23e50 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65  urned..**.** Ple
23e60 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
23e70 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
23e80 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
23e90 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
23ea0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
23eb0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
23ec0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
23ed0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
23ee0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
23ef0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
23f00 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
23f10 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
23f20 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
23f30 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
23f40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
23f50 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
23f60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
23f70 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
23f80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
23f90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
23fa0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
23fb0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
23fc0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
23fd0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
23fe0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
23ff0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
24000 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
24010 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
24020 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30  ments:.** [H1510
24030 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35  3] [H15106] [H15
24040 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48  109] [H15112] [H
24050 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20  15115] [H15118] 
24060 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34  [H15121] [H15124
24070 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48  ].** [H15127] [H
24080 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20  15130] [H15133] 
24090 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73  [H15136].*/.cons
240a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
240b0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
240c0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
240d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
240e0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
240f0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24100 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
24110 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24120 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
24130 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
24140 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
24150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
24160 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
24170 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
24180 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
24190 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
241a0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
241b0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
241c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
241d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
241e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
241f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24200 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24210 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24230 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
24240 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
24250 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
24260 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
24270 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
24280 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
24290 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
242a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
242b0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
242c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
242d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
242e0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
242f0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
24300 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
24310 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
24320 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24330 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
24340 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
24350 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
24360 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
24370 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
24380 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
24390 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
243a0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
243b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
243c0 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
243d0 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
243e0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
243f0 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
24400 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
24410 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
24420 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
24430 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
24440 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
24450 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
24460 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
24470 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
24480 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
24490 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
244a0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
244b0 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
244c0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
244d0 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
244e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
244f0 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
24500 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
24510 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
24520 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
24530 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
24540 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
24550 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
24560 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
24570 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
24580 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
24590 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
245a0 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
245b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
245c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
245d0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
245e0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
245f0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
24600 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
24610 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
24620 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
24630 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
24640 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
24650 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
24660 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
24670 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
24680 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
24690 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
246a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
246b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
246c0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
246d0 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 31  11] [H16213] [H1
246e0 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 2a  6215] [H16217].*
246f0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
24700 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
24710 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
24720 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
24730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24740 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
24750 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34  Functions {H1624
24760 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
24770 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
24780 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
24790 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
247a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
247b0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
247c0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
247d0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
247e0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
247f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
24800 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
24810 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
24820 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
24830 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
24840 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
24850 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
24860 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
24870 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
24880 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
24890 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
248a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
248b0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
248c0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
248d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
248e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
248f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
24900 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
24910 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  43].*/.void *sql
24920 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
24930 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
24940 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24950 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
24960 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
24970 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
24980 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
24990 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
249a0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
249b0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
249c0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
249d0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
249e0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
249f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
24a00 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
24a10 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
24a20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24a30 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
24a40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24a50 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
24a60 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
24a70 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
24a80 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
24a90 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
24aa0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ion..**.** Requi
24ab0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
24ac0 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  253].*/.sqlite3 
24ad0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
24ae0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
24af0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
24b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
24b10 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
24b20 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20  y Data {H16270} 
24b30 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
24b40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
24b50 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
24b60 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
24b70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
24b80 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
24b90 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
24ba0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
24bb0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
24bc0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
24bd0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
24be0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
24bf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
24c00 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
24c10 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
24c20 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
24c30 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
24c40 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
24c50 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
24c60 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
24c70 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
24c80 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
24c90 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
24ca0 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
24cb0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
24cc0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
24cd0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
24ce0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
24cf0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
24d00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
24d10 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
24d20 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
24d30 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
24d40 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
24d50 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
24d60 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
24d70 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
24d80 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
24d90 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
24da0 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
24db0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
24dc0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
24dd0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
24de0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
24df0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
24e00 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
24e10 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
24e20 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
24e30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
24e40 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
24e50 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
24e60 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
24e70 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
24e80 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
24e90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
24ea0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
24eb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
24ec0 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74  ction. If no met
24ed0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
24ee0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
24ef0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
24f00 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
24f10 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
24f20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
24f30 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
24f40 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
24f50 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
24f60 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
24f70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
24f80 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
24f90 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
24fa0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
24fb0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
24fc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
24fd0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
24fe0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
24ff0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
25000 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
25010 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
25020 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
25030 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
25040 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
25050 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
25060 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
25070 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
25080 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
25090 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
250a0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
250b0 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74  troyed..** If it
250c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
250d0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
250e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
250f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
25100 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
25110 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25120 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
25130 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
25140 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
25150 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
25160 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
25170 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
25180 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
25190 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
251a0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
251b0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
251c0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
251d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
251e0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
251f0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
25200 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
25210 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
25220 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61  e.  The only gua
25230 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
25240 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
25250 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
25260 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
25270 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
25280 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
25290 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
252a0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
252b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
252c0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
252d0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
252e0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
252f0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
25300 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
25310 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61  alues and SQL va
25320 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  riables..**.** T
25330 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
25340 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
25350 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
25360 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
25370 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
25380 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
25390 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
253a0 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36 32  * [H16272] [H162
253b0 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48 31  74] [H16276] [H1
253c0 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20 5b  6277] [H16278] [
253d0 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20  H16279].*/.void 
253e0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
253f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
25400 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
25410 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
25420 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
25430 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
25440 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
25450 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
25460 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
25470 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
25480 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
25490 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32  r Behavior {H102
254a0 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  80} <S30100>.**.
254b0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
254c0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
254d0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
254e0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
254f0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
25500 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
25510 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
25520 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
25530 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
25540 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
25550 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
25560 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
25570 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
25580 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
25590 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
255a0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
255b0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
255c0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
255d0 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   The.** SQLITE_T
255e0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
255f0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
25600 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
25610 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
25620 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
25630 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
25640 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
25650 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
25660 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
25670 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
25680 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
25690 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
256a0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
256b0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
256c0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
256d0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
256e0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
256f0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
25700 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
25710 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
25720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
25730 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
25740 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
25750 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
25760 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
25770 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
25780 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
25790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
257a0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
257b0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
257c0 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c  ction {H16400} <
257d0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
257e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
257f0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
25800 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
25810 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
25820 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
25830 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
25840 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
25850 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25860 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
25870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25880 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
25890 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
258a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
258b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
258c0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
258d0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
258e0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
258f0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
25900 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
25910 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
25920 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
25930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25940 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
25950 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
25960 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
25970 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
25980 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
25990 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
259a0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
259b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
259c0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
259d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
259e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
259f0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
25a00 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
25a10 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
25a20 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
25a30 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
25a40 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
25a50 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
25a60 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
25a70 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
25a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
25a90 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
25aa0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
25ab0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
25ac0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
25ad0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
25ae0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
25af0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
25b00 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
25b10 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
25b20 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
25b30 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
25b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25b50 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
25b60 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
25b70 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
25b80 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
25b90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25ba0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
25bb0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
25bc0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
25bd0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
25be0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
25bf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
25c00 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
25c10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
25c20 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
25c30 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
25c40 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
25c50 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
25c60 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
25c70 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
25c80 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
25c90 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
25ca0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
25cb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
25cc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
25cd0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
25ce0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
25cf0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
25d00 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
25d10 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
25d20 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25d30 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
25d40 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
25d50 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  TF-8. SQLite.** 
25d60 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
25d70 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
25d80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
25d90 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
25da0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
25db0 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74  order.  If the t
25dc0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
25dd0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
25de0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
25df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
25e00 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
25e10 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
25e20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
25e30 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
25e40 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
25e50 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
25e60 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
25e70 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
25e80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25e90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
25ea0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
25eb0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
25ec0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
25ed0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
25ee0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
25ef0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
25f00 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
25f10 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
25f20 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
25f30 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
25f40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
25f50 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
25f60 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
25f70 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
25f80 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
25f90 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25fa0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
25fb0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
25fc0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
25fd0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
25fe0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
25ff0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
26000 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
26010 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
26020 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26030 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
26040 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
26050 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
26060 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
26070 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
26080 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
26090 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
260a0 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
260b0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
260c0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
260d0 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
260e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
260f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
26100 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
26110 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
26120 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
26130 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
26140 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
26150 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
26160 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
26170 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
26180 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
26190 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
261a0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
261b0 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f  OB is to long to
261c0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
261d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
261e0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
261f0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
26200 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
26210 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
26220 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
26230 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
26240 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
26250 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
26260 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
26270 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
26280 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
26290 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
262a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
262b0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
262c0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
262d0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
262e0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
262f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26300 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
26310 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
26320 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
26330 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
26340 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26350 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
26360 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
26370 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
26380 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
26390 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
263a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
263b0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
263c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
263d0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
263e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
263f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26400 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
26410 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26420 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
26430 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
26440 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
26450 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
26460 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
26470 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
26480 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
26490 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
264a0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
264b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
264c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
264d0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
264e0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
264f0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
26500 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
26510 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
26520 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
26530 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
26540 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
26550 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
26560 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
26570 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
26580 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
26590 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
265a0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
265b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
265c0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
265d0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
265e0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
265f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26600 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
26610 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
26620 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
26630 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
26640 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
26650 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
26660 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
26670 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
26680 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
26690 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
266a0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
266b0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
266c0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
266d0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
266e0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
266f0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
26700 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
26710 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
26720 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
26730 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
26750 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
26760 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26770 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
26780 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
26790 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
267a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
267b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
267c0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
267d0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
267e0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
267f0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
26800 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
26810 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
26820 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
26830 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
26840 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
26850 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
26860 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26870 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
26880 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
26890 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
268a0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
268b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
268c0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
268d0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
268e0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
268f0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
26900 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
26910 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
26920 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64  e it or call a d
26930 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69  estructor when i
26940 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
26950 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
26960 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
26970 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26990 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
269a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
269b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
269c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
269d0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
269e0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
269f0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
26a00 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
26a10 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
26a20 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
26a30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
26a40 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
26a50 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
26a60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
26a70 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
26a80 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
26a90 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
26aa0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26ab0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
26ac0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
26ad0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26ae0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
26af0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
26b00 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
26b10 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
26b20 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
26b30 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
26b40 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
26b50 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
26b60 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
26b70 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
26b80 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
26b90 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
26ba0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
26bb0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
26bc0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26bd0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
26be0 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72  t harm..** A [pr
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 6d 61  value] object ma
26c10 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
26c20 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
26c30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26c40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26c50 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
26c60 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
26c70 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
26c80 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
26c90 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
26ca0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
26cb0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
26cc0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
26cd0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
26ce0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
26cf0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
26d00 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
26d10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26d20 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
26d30 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
26d40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
26d50 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
26d60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
26d70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
26d80 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
26d90 34 30 33 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48  403] [H16406] [H
26da0 31 36 34 30 39 5d 20 5b 48 31 36 34 31 32 5d 20  16409] [H16412] 
26db0 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 34 31 38  [H16415] [H16418
26dc0 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 31 36 34  ] [H16421] [H164
26dd0 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20  24].** [H16427] 
26de0 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 34 33 33  [H16430] [H16433
26df0 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 31 36 34  ] [H16436] [H164
26e00 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b 48 31  39] [H16442] [H1
26e10 36 34 34 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a  6445] [H16448].*
26e20 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 31 36 34  * [H16451] [H164
26e30 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b 48 31  54] [H16457] [H1
26e40 36 34 36 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a  6460] [H16463].*
26e50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
26e60 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
26e70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
26e80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
26e90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26ea0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
26eb0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
26ec0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
26ed0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
26ee0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26ef0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26f00 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
26f10 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
26f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
26f30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26f40 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
26f50 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
26f60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
26f70 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
26f80 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
26f90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26fa0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
26fb0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
26fc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
26fd0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
26fe0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
26ff0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
27000 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
27010 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
27020 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
27030 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
27040 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27050 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
27060 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27070 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
27080 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
27090 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
270a0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
270b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
270c0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
270d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
270e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
270f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
27100 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
27110 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
27120 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
27130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27140 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
27150 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27160 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
27170 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27190 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
271a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
271b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
271c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
271d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
271e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
271f0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
27200 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
27210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
27220 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
27230 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
27240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27250 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
27260 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
27270 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
27280 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
27290 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
272a0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
272b0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
272c0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
272d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
272e0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
272f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
27300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
27310 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
27320 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
27330 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
27340 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
27350 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
27360 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
27370 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
27380 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
27390 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
273a0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
273b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
273c0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
273d0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
273e0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
273f0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
27400 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
27410 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
27420 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
27430 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
27440 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
27450 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
27460 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
27470 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
27480 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
27490 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
274a0 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
274b0 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
274c0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
274d0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
274e0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
274f0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
27500 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
27510 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
27520 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
27530 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
27540 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
27550 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
27560 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
27570 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
27580 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
27590 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
275a0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
275b0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
275c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
275d0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
275e0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
275f0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
27600 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
27610 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
27620 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
27630 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
27640 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
27650 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
27660 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
27670 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
27680 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
27690 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
276a0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
276b0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
276c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
276d0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
276e0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
276f0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
27700 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
27710 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
27720 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
27730 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
27740 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
27750 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27760 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
27770 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27780 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
27790 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
277a0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
277b0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
277c0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
277d0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
277e0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
277f0 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
27800 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
27810 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
27820 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
27830 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
27840 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
27850 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
27860 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
27870 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
27880 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
27890 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
278a0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
278b0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
278c0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
278d0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
278e0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
278f0 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
27900 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
27910 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
27920 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
27930 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
27940 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
27950 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
27960 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
27970 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
27980 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
27990 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
279a0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
279b0 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
279c0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
279d0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
279e0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
279f0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
27a00 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
27a10 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
27a20 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
27a30 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
27a40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27a50 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
27a60 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
27a70 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
27a80 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
27a90 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
27aa0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
27ab0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
27ac0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
27ad0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
27ae0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
27af0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
27b00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27b10 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
27b20 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
27b30 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
27b40 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
27b50 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36  * [H16603] [H166
27b60 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31  04] [H16606] [H1
27b70 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b  6609] [H16612] [
27b80 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d  H16615] [H16618]
27b90 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31   [H16621].** [H1
27ba0 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b  6624] [H16627] [
27bb0 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H16630].*/.int s
27bc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27bd0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
27be0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
27bf0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
27c00 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
27c10 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
27c20 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
27c30 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
27c40 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
27c50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
27c60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
27c70 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
27c80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
27c90 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
27ca0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
27cb0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
27cc0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
27cd0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
27ce0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
27cf0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
27d00 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27d10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27d20 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
27d30 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
27d40 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
27d50 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
27d60 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
27d70 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
27d80 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
27d90 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
27da0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
27db0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
27dc0 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20  lbacks {H16700} 
27dd0 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
27de0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
27df0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
27e00 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
27e10 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
27e20 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
27e30 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
27e40 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
27e50 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
27e60 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
27e70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27e80 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  on] to be called
27e90 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
27ea0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
27eb0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
27ec0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
27ed0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
27ee0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
27ef0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
27f00 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
27f10 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
27f20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
27f30 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
27f40 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
27f50 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
27f60 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
27f70 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d   UTF-8. {H16703}
27f80 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
27f90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
27fa0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
27fb0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
27fc0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
27fd0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
27fe0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63  te order..** A c
27ff0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
28000 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
28010 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
28020 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
28030 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
28040 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
28050 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
28060 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
28070 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
28080 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
28090 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
280a0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
280b0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
280c0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
280d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
280e0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
280f0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
28100 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
28110 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
28120 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
28130 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
28140 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
28150 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
28160 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
28170 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
28180 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
28190 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
281a0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
281b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
281c0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
281d0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
281e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
281f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
28200 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
28210 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
28220 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
28230 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
28240 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28250 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
28260 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28270 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
28280 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28290 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
282a0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
282b0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32  ents:.** [H16702
282c0 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37  ] [H16704] [H167
282d0 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  06].*/.int sqlit
282e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
282f0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
28300 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
28310 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
28320 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
28330 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
28340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
28350 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
28360 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
28370 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
28380 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
28390 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
283a0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
283b0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
283c0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
283d0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
283e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
283f0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
28400 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
28410 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
28420 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
28430 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
28440 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
28450 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
28460 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
28470 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
28480 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
28490 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
284a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
284b0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
284c0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
284d0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
284e0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
284f0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
28500 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
28510 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
28520 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
28530 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
28540 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
28550 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
28560 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
28570 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
28580 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
28590 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
285a0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
285b0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
285c0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
285d0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
285e0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
285f0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
28600 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
28610 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
28620 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28630 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28640 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
28650 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
28660 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
28670 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
28680 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
28690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
286a0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
286b0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
286c0 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31   {H10530} <S4041
286d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
286e0 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
286f0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
28700 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
28710 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
28720 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
28730 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
28740 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
28750 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
28760 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
28770 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
28780 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
28790 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
287a0 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
287b0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
287c0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
287d0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
287e0 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
287f0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
28800 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
28810 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
28820 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
28830 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
28840 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
28850 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
28860 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
28870 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
28880 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
28890 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
288a0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
288b0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
288c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
288d0 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  bject..**.** Req
288e0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35  uirements: [H105
288f0 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a  33] [H10536].*/.
28900 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
28910 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
28920 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
28930 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
28940 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
28950 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32  les {H10310} <S2
28960 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  0000>.**.** If t
28970 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
28980 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
28990 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
289a0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
289b0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
289c0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
289d0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
289e0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
289f0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
28a00 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
28a10 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
28a20 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
28a30 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
28a40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
28a50 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
28a60 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
28a70 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
28a80 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
28a90 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
28aa0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
28ab0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20   to modify this 
28ac0 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20  variable once a 
28ad0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28ae0 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65  tion].** has bee
28af0 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73  n opened.  It is
28b00 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
28b10 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
28b20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
28b30 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
28b40 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
28b50 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
28b60 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
28b70 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
28b80 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d  een call and rem
28b90 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68  ain unchanged th
28ba0 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c  ereafter..*/.SQL
28bb0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
28bc0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
28bd0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
28be0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
28bf0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
28c00 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36  ode {H12930} <S6
28c10 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
28c20 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
28c30 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ode}.**.** The s
28c40 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
28c50 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
28c60 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
28c70 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
28c80 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
28c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
28ca0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
28cb0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
28cc0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
28cd0 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
28ce0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
28cf0 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  lt..** Autocommi
28d00 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
28d10 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
28d20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
28d30 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
28d40 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
28d50 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
28d60 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
28d70 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
28d80 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
28d90 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
28da0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
28db0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
28dc0 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
28dd0 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
28de0 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
28df0 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
28e00 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
28e10 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
28e20 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
28e30 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
28e40 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
28e50 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
28e60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
28e70 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
28e80 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
28e90 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
28ea0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
28eb0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
28ec0 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
28ed0 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
28ee0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
28ef0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
28f00 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
28f10 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
28f20 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
28f30 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
28f40 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
28f50 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
28f60 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
28f70 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
28f80 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
28f90 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
28fa0 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b  2931] [H12932] [
28fb0 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d  H12933] [H12934]
28fc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28fd0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
28fe0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
28ff0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
29000 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
29010 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
29020 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
29030 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  120} <S60600>.**
29040 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29050 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
29060 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29080 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
29090 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
290a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
290b0 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64  belongs.  The [d
290c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
290d0 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
290e0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
290f0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
29100 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29110 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20  ction] that was 
29120 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
29130 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
29140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29150 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
29160 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
29170 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
29180 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
29190 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
291a0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65   place..**.** Re
291b0 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33  quirements: [H13
291c0 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  123].*/.sqlite3 
291d0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
291e0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
291f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29200 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
29210 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
29220 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53  ment {H13140} <S
29230 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60600>.**.** Thi
29240 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
29250 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29260 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
29270 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
29280 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
29290 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
292a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
292b0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66  ection] pDb.  If
292c0 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
292d0 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
292e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
292f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
29300 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
29310 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
29320 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
29330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29340 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70  on pDb.  If no p
29350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29360 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
29370 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
29380 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
29390 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
293a0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
293b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
293c0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
293d0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
293e0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
293f0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
29400 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
29410 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
29420 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
29430 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
29440 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29450 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
29460 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31  : [H13143] [H131
29470 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31  46] [H13149] [H1
29480 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  3152].*/.sqlite3
29490 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
294a0 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
294b0 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
294c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
294d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
294e0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
294f0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
29500 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30  allbacks {H12950
29510 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
29520 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
29530 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
29540 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
29550 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
29560 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
29570 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
29580 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
29590 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
295a0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
295b0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
295c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
295d0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
295e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
295f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
29600 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
29610 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
29620 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
29630 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
29640 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
29650 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
29660 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
29670 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
29680 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
29690 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
296a0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
296b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
296c0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
296d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
296e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
296f0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
29700 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
29710 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
29720 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
29730 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ck..** If the ca
29740 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
29750 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
29760 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
29770 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
29780 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
29790 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
297a0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
297b0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
297c0 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
297d0 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
297e0 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
297f0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
29800 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
29810 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ned..**.** The c
29820 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
29830 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
29840 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
29850 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
29860 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
29870 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
29880 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
29890 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
298a0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
298b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
298c0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
298d0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
298e0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
298f0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
29900 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
29910 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
29920 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
29930 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
29940 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
29950 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
29960 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29970 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
29980 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
29990 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
299a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
299b0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
299c0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
299d0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
299e0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  aph..**.** Regis
299f0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
29a00 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
29a10 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
29a20 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
29a30 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
29a40 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
29a50 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
29a60 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
29a70 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
29a80 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
29a90 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
29aa0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
29ab0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
29ac0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
29ad0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
29ae0 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72   occur..** The r
29af0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
29b00 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
29b10 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
29b20 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
29b30 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
29b40 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
29b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29b60 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54   is closed..** T
29b70 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
29b80 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
29b90 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
29ba0 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65  tion is.** rolle
29bb0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61  d back because a
29bc0 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b   commit callback
29bd0 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65   returned non-ze
29be0 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68  ro..** <todo> Ch
29bf0 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f  eck on this </to
29c00 64 6f 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  do>.**.** Requir
29c10 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
29c20 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31  51] [H12952] [H1
29c30 32 39 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b  2953] [H12954] [
29c40 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39  H12955].** [H129
29c50 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31  61] [H12962] [H1
29c60 32 39 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a  2963] [H12964].*
29c70 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
29c80 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
29c90 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
29ca0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
29cb0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
29cc0 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
29cd0 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
29ce0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
29cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
29d00 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
29d10 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
29d20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30  {H12970} <S60400
29d30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
29d40 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
29d50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
29d60 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
29d70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
29d80 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
29d90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
29da0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
29db0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
29dc0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
29dd0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
29de0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
29df0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
29e00 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
29e10 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
29e20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
29e30 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
29e40 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
29e50 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
29e60 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rridden..**.** T
29e70 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
29e80 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
29e90 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
29ea0 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
29eb0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
29ec0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
29ed0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20  deleted..** The 
29ee0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
29ef0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
29f00 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
29f10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
29f20 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
29f30 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54  ate_hook()..** T
29f40 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
29f50 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
29f60 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
29f70 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
29f80 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
29f90 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
29fa0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
29fb0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
29fc0 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
29fd0 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
29fe0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ked..** The thir
29ff0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
2a000 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
2a010 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
2a020 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
2a030 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
2a040 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
2a050 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
2a060 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69  d row..** The fi
2a070 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
2a080 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72  ameter is the [r
2a090 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77  owid] of the row
2a0a0 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65  ..** In the case
2a0b0 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
2a0c0 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
2a0d0 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
2a0e0 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
2a0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2a100 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
2a110 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
2a120 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
2a130 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
2a140 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
2a150 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
2a160 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
2a170 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2a180 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2a190 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2a1a0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2a1b0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2a1c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a1d0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2a1e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2a1f0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2a200 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2a210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a220 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2a230 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2a240 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2a250 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2a260 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2a270 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2a280 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2a290 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2a2a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a2b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2a2c0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2a2d0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2a2e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2a2f0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2a300 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2a310 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2a320 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2a330 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
2a340 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
2a350 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
2a360 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
2a370 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
2a380 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2a390 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2a3a0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d  nts:.** [H12971]
2a3b0 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37   [H12973] [H1297
2a3c0 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32  5] [H12977] [H12
2a3d0 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48  979] [H12981] [H
2a3e0 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a  12983] [H12986].
2a3f0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2a400 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
2a410 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2a420 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
2a430 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
2a440 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
2a450 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
2a460 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
2a470 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
2a480 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
2a490 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30  Pager Cache {H10
2a4a0 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a  330} <S30900>.**
2a4b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
2a4c0 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65  ed cache} {share
2a4d0 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a  d cache mode}.**
2a4e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2a4f0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
2a500 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
2a510 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a520 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
2a530 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
2a540 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
2a550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a560 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
2a570 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2a580 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
2a590 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
2a5a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2a5b0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
2a5c0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2a5d0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a  ment is false..*
2a5e0 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69  *.** Cache shari
2a5f0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2a600 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2a610 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2a620 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2a630 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2a640 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2a650 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2a660 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2a670 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2a680 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2a690 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2a6a0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2a6b0 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68  .** The cache sh
2a6c0 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
2a6d0 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
2a6e0 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
2a6f0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2a700 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2a710 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2a720 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
2a730 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2a740 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
2a750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a760 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
2a770 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
2a780 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
2a790 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
2a7a0 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
2a7b0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ened..**.** Virt
2a7c0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
2a7d0 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
2a7e0 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
2a7f0 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63  When shared.** c
2a800 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
2a810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2a820 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41  eate_module()] A
2a830 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  PI used to regis
2a840 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  ter.** virtual t
2a850 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79  ables will alway
2a860 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
2a870 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  r..**.** This ro
2a880 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
2a890 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
2a8a0 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
2a8b0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2a8c0 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
2a8d0 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
2a8e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
2a8f0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
2a900 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
2a910 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
2a920 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d  ault. But this m
2a930 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a  ight change in.*
2a940 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  * future release
2a950 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70  s of SQLite.  Ap
2a960 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2a970 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65  care about share
2a980 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69  d.** cache setti
2a990 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74  ng should set it
2a9a0 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a   explicitly..**.
2a9b0 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53  ** See Also:  [S
2a9c0 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63  QLite Shared-Cac
2a9d0 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52  he Mode].**.** R
2a9e0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2a9f0 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b  0331] [H10336] [
2aa00 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d  H10337] [H10339]
2aa10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2aa20 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
2aa30 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
2aa40 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
2aa50 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
2aa60 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20  Memory {H17340} 
2aa70 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
2aa80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
2aa90 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
2aaa0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2aab0 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
2aac0 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
2aad0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
2aae0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2aaf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2ab00 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
2ab10 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
2ab20 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79  y. {END}  Memory
2ab30 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2ab40 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2ab50 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2ab60 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2ab70 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2ab80 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2ab90 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  * sqlite3_releas
2aba0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
2abb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2abc0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
2abd0 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
2abe0 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
2abf0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
2ac00 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
2ac10 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2ac20 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48  nts: [H17341] [H
2ac30 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17342].*/.int sq
2ac40 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2ac50 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
2ac60 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f  * CAPI3REF: Impo
2ac70 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
2ac80 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d  ap Size {H17350}
2ac90 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20   <S30220>.**.** 
2aca0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
2acb0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
2acc0 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61  terface places a
2acd0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a   "soft" limit.**
2ace0 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
2acf0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
2ad00 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
2ad10 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2ad20 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c  * If an internal
2ad30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72   allocation is r
2ad40 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f  equested that wo
2ad50 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2ad60 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  * soft heap limi
2ad70 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  t, [sqlite3_rele
2ad80 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
2ad90 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a   invoked one or.
2ada0 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  ** more times to
2adb0 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70   free up some sp
2adc0 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61  ace before the a
2add0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72  llocation is per
2ade0 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  formed..**.** Th
2adf0 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65  e limit is calle
2ae00 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73  d "soft", becaus
2ae10 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65  e if [sqlite3_re
2ae20 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a  lease_memory()].
2ae30 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73  ** cannot free s
2ae40 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2ae50 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
2ae60 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
2ae70 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68   exceeded,.** th
2ae80 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  e memory is allo
2ae90 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
2aea0 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
2aeb0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
2aec0 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  .**.** A negativ
2aed0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
2aee0 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
2aef0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
2af00 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
2af10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
2af20 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
2af30 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
2af40 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
2af50 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
2af60 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2af70 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
2af80 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
2af90 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
2afa0 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
2afb0 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
2afc0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2afd0 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20  ..** But if the 
2afe0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2aff0 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65  cannot be honore
2b000 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
2b010 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
2b020 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
2b030 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68  otification.  Th
2b040 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69  is is why the li
2b050 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  mit is.** called
2b060 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
2b070 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
2b080 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
2b090 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
2b0a0 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
2b0b0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
2b0c0 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
2b0d0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
2b0e0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
2b0f0 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
2b100 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
2b110 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
2b120 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
2b130 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
2b140 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
2b150 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2b160 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
2b170 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
2b180 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
2b190 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
2b1a0 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
2b1b0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
2b1c0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
2b1d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
2b1e0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
2b1f0 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
2b200 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
2b210 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
2b220 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
2b230 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
2b240 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
2b250 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2b260 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20  ts:.** [H16351] 
2b270 5b 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33  [H16352] [H16353
2b280 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33  ] [H16354] [H163
2b290 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a  55] [H16358].*/.
2b2a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
2b2b0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
2b2c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b2d0 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
2b2e0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2b2f0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b  umn Of A Table {
2b300 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e  H12850} <S60300>
2b310 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b320 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61  ine returns meta
2b330 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
2b340 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
2b350 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61  a specific.** da
2b360 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63  tabase table acc
2b370 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
2b380 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2b390 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
2b3a0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
2b3b0 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61  first function a
2b3c0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2b3d0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
2b3e0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
2b3f0 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
2b400 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2b410 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
2b420 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f  nction. The seco
2b430 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2b440 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
2b450 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2b460 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
2b470 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74   "temp" or an at
2b480 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
2b490 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2b4a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
2b4b0 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69  le or NULL. If i
2b4c0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2b4d0 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
2b4e0 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
2b4f0 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
2b500 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
2b510 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73  ame algorithm us
2b520 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
2b530 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20  se engine to.** 
2b540 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66  resolve unqualif
2b550 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65  ied table refere
2b560 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nces..**.** The 
2b570 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
2b580 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
2b590 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
2b5a0 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
2b5b0 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66  olumn.** name of
2b5c0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2b5d0 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
2b5e0 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
2b5f0 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ese parameters.*
2b600 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
2b610 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73  *.** Metadata is
2b620 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
2b630 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
2b640 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
2b650 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
2b660 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
2b670 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
2b680 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
2b690 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
2b6a0 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
2b6b0 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
2b6c0 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
2b6d0 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
2b6e0 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
2b6f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ted..**.** <bloc
2b700 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2b710 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2b720 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65   <tr><th> Parame
2b730 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c  ter <th> Output<
2b740 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65  br>Type <th>  De
2b750 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  scription.**.** 
2b760 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64  <tr><td> 5th <td
2b770 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
2b780 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20  d> Data type.** 
2b790 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64  <tr><td> 6th <td
2b7a0 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
2b7b0 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75  d> Name of defau
2b7c0 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
2b7d0 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  uence.** <tr><td
2b7e0 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 7th <td> int  
2b7f0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
2b800 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61   if column has a
2b810 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
2b820 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  aint.** <tr><td>
2b830 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   8th <td> int   
2b840 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2b850 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  if column is par
2b860 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
2b870 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   KEY.** <tr><td>
2b880 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   9th <td> int   
2b890 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2b8a0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55  if column is [AU
2b8b0 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20  TOINCREMENT].** 
2b8c0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2b8d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2b8e0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
2b8f0 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
2b900 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
2b910 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
2b920 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
2b930 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
2b940 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
2b950 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
2b960 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
2b970 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
2b980 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
2b990 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
2b9a0 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
2b9b0 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
2b9c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2b9d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b9e0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2b9f0 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
2ba00 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
2ba10 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
2ba20 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
2ba30 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
2ba40 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
2ba50 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
2ba60 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
2ba70 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
2ba80 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
2ba90 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
2baa0 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20  olumn. If there 
2bab0 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
2bac0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e  tly declared [IN
2bad0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
2bae0 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20  Y] column, then 
2baf0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2bb00 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2bb10 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
2bb20 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
2bb30 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
2bb40 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
2bb50 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
2bb60 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
2bb70 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
2bb80 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
2bb90 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
2bba0 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
2bbb0 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
2bbc0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
2bbd0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
2bbe0 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
2bbf0 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
2bc00 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
2bc10 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
2bc20 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
2bc30 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
2bc40 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
2bc50 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
2bc60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2bc70 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
2bc80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c   error message l
2bc90 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64  eft.** in the [d
2bca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bcb0 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69  on] (to be retri
2bcc0 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  eved using sqlit
2bcd0 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a  e3_errmsg())..**
2bce0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20  .** This API is 
2bcf0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2bd00 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2bd10 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2bd20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2bd30 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2bd40 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2bd50 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
2bd60 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2bd70 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
2bd80 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
2bd90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2bda0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
2bdb0 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
2bdc0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2bdd0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
2bde0 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
2bdf0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
2be00 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
2be10 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
2be20 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
2be30 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
2be40 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
2be50 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
2be60 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
2be70 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
2be80 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
2be90 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
2bea0 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
2beb0 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
2bec0 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
2bed0 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
2bee0 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
2bef0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2bf00 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
2bf10 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2bf20 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
2bf30 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
2bf40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2bf50 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2bf60 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
2bf70 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
2bf80 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
2bf90 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2bfa0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
2bfb0 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
2bfc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bfd0 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
2bfe0 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c  nsion {H12600} <
2bff0 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20500>.**.** Th
2c000 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61  is interface loa
2c010 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74  ds an SQLite ext
2c020 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66  ension library f
2c030 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69  rom the named fi
2c040 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  le..**.** {H1260
2c050 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  1} The sqlite3_l
2c060 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2c070 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2c080 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
2c090 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
2c0a0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
2c0b0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
2c0c0 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a  the file zFile..
2c0d0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54  **.** {H12602} T
2c0e0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
2c0f0 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b  s zProc..**.** {
2c100 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61  H12603} zProc ma
2c110 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
2c120 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
2c130 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
2c140 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  t.**          de
2c150 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
2c160 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
2c170 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  t"..**.** {H1260
2c180 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  4} The sqlite3_l
2c190 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2c1a0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2c1b0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
2c1c0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f     [SQLITE_OK] o
2c1d0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
2c1e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
2c1f0 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
2c200 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rong..**.** {H12
2c210 36 30 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  605} If an error
2c220 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72   occurs and pzEr
2c230 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74  rMsg is not 0, t
2c240 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hen the.**      
2c250 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61      [sqlite3_loa
2c260 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
2c270 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
2c280 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20  ttempt to.**    
2c290 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72        fill *pzEr
2c2a0 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
2c2b0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
2c2c0 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
2c2d0 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
2c2e0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2c2f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44  _malloc()]. {END
2c300 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  }  The calling f
2c310 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2c320 20 20 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20      should free 
2c330 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63  this memory by c
2c340 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c350 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  free()]..**.** {
2c360 48 31 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f  H12606} Extensio
2c370 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
2c380 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
2c390 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2c3a0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
2c3b0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72  _extension()] pr
2c3c0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
2c3d0 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20  his API,.**     
2c3e0 20 20 20 20 20 6f 74 68 65 72 77 69 73 65 20 61       otherwise a
2c3f0 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
2c400 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
2c410 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
2c420 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
2c430 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c440 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
2c450 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
2c460 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c470 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
2c480 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
2c490 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
2c4a0 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
2c4b0 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
2c4c0 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2c4d0 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
2c4e0 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
2c4f0 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
2c500 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
2c510 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
2c520 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
2c530 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
2c540 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
2c550 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
2c560 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
2c570 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2c580 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30  {H12620} <S20500
2c590 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f  >.**.** So as no
2c5a0 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
2c5b0 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
2c5c0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
2c5d0 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
2c5e0 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
2c5f0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
2c600 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
2c610 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
2c620 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
2c630 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
2c640 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
2c650 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
2c660 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
2c670 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
2c680 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
2c690 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2c6a0 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
2c6b0 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78  nd off..**.** Ex
2c6c0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2c6d0 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
2c6e0 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  t. See ticket #1
2c6f0 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  863..**.** {H126
2c700 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c  21} Call the sql
2c710 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
2c720 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
2c730 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d  tine with onoff=
2c740 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  =1.**          t
2c750 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
2c760 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20   loading on and 
2c770 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f  call it with ono
2c780 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a  ff==0 to turn.**
2c790 20 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63            it bac
2c7a0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a  k off again..**.
2c7b0 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65  ** {H12622} Exte
2c7c0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2c7d0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2c7e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c7f0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
2c800 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
2c810 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
2c820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c830 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
2c840 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73  ad An Extensions
2c850 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30   {H12640} <S2050
2c860 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  0>.**.** This AP
2c870 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64  I can be invoked
2c880 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72   at program star
2c890 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  tup in order to 
2c8a0 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20  register.** one 
2c8b0 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c  or more statical
2c8c0 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73  ly linked extens
2c8d0 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ions that will b
2c8e0 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74  e available.** t
2c8f0 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62  o all new [datab
2c900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
2c910 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
2c920 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
2c930 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c940 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
2c950 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
2c960 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
2c970 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2c980 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75  c()].  If you ru
2c990 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20  n a memory leak 
2c9a0 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f  checker.** on yo
2c9b0 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69  ur program and i
2c9c0 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b  t reports a leak
2c9d0 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   because of this
2c9e0 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a   array, invoke.*
2c9f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2ca00 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2ca10 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74  )] prior to shut
2ca20 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65  down to free the
2ca30 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
2ca40 48 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e  H12641} This fun
2ca50 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20  ction registers 
2ca60 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  an extension ent
2ca70 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73  ry point that is
2ca80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
2ca90 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
2caa0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ed whenever a ne
2cab0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
2cac0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20  ection].**      
2cad0 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73      is opened us
2cae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
2caf0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2cb00 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
2cb10 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2cb20 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
2cb30 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70  .** {H12642} Dup
2cb40 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
2cb50 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
2cb60 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
2cb70 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20  outine.**       
2cb80 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65     multiple time
2cb90 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2cba0 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72  extension is har
2cbb0 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mless..**.** {H1
2cbc0 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69  2643} This routi
2cbd0 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e  ne stores a poin
2cbe0 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e  ter to the exten
2cbf0 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79  sion in an array
2cc00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
2cc10 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  t is obtained fr
2cc20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2cc30 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  oc()]..**.** {H1
2cc40 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20  2644} Automatic 
2cc50 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79  extensions apply
2cc60 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65   across all thre
2cc70 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ads..*/.int sqli
2cc80 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
2cc90 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79  on(void (*xEntry
2cca0 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a  Point)(void));..
2ccb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ccc0 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
2ccd0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2cce0 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35  g {H12660} <S205
2ccf0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
2cd00 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2cd10 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
2cd20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d  registered autom
2cd30 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  atic.** extensio
2cd40 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e  ns. {END}  It un
2cd50 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
2cd60 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20  of all prior.** 
2cd70 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78  [sqlite3_auto_ex
2cd80 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73  tension()] calls
2cd90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d  ..**.** {H12661}
2cda0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2cdb0 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76  isables all prev
2cdc0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2cdd0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  d.**          au
2cde0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2cdf0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36  ns..**.** {H1266
2ce00 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  2} This function
2ce10 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61   disables automa
2ce20 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
2ce30 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
2ce40 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2ce50 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2ce60 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
2ce70 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
2ce80 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
2ce90 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
2cea0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
2ceb0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
2cec0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
2ced0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2cee0 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
2cef0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
2cf00 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
2cf10 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
2cf20 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
2cf30 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
2cf40 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
2cf50 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
2cf60 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
2cf70 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
2cf80 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
2cf90 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
2cfa0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2cfb0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
2cfc0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
2cfd0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
2cfe0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
2cff0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
2d000 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
2d010 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
2d020 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
2d030 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
2d040 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
2d050 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
2d060 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2d070 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
2d080 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
2d090 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2d0a0 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
2d0b0 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
2d0c0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2d0d0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
2d0e0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2d0f0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2d100 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
2d110 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
2d120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d130 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
2d140 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c  bject {H18000} <
2d150 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
2d160 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
2d170 75 6c 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ule.** EXPERIMEN
2d180 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75  TAL.**.** A modu
2d190 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66  le is a class of
2d1a0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
2d1b0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73    Each module is
2d1c0 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61   defined.** by a
2d1d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
2d1e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
2d1f0 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72  cture.  This str
2d200 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a  ucture consists.
2d210 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ** mostly of met
2d220 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
2d230 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule..**.** This 
2d240 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
2d250 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
2d260 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
2d270 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
2d280 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2d290 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2d2a0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2d2b0 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
2d2c0 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
2d2d0 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
2d2e0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2d2f0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d300 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2d310 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2d320 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d330 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2d340 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2d350 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
2d360 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
2d370 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2d380 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2d390 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2d3a0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2d3b0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2d3c0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2d3d0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2d3e0 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
2d3f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d400 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
2d410 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
2d420 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
2d430 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d440 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
2d450 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
2d460 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2d470 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
2d480 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
2d490 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2d4a0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
2d4b0 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
2d4c0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2d4d0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2d4e0 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
2d4f0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
2d500 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
2d510 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
2d520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2d530 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
2d540 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
2d550 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
2d560 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2d570 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
2d580 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
2d590 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2d5a0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
2d5b0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2d5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d5d0 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
2d5e0 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
2d5f0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2d600 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
2d610 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
2d620 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
2d630 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
2d640 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
2d650 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
2d660 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
2d670 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2d680 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2d690 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
2d6a0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2d6b0 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
2d6c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d6d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
2d6e0 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
2d6f0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2d700 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
2d710 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2d720 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
2d730 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2d740 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
2d750 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2d760 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
2d770 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2d780 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2d790 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
2d7a0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
2d7b0 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
2d7c0 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
2d7d0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
2d7e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
2d7f0 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
2d800 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
2d810 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
2d820 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30  ormation {H18100
2d830 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
2d840 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2d850 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58  index_info.** EX
2d860 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2d870 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
2d880 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
2d890 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
2d8a0 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
2d8b0 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
2d8c0 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
2d8d0 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
2d8e0 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74  y from the xBest
2d8f0 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20  Index.** method 
2d900 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f  of an sqlite3_mo
2d910 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64  dule.  The field
2d920 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
2d930 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
2d940 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
2d950 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
2d960 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
2d970 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
2d980 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
2d990 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
2d9a0 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  elds..**.** The 
2d9b0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
2d9c0 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52  ray records WHER
2d9d0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
2d9e0 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ints of the form
2d9f0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c  :.**.** <pre>col
2da00 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65  umn OP expr</pre
2da10 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50  >.**.** where OP
2da20 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74   is =, &lt;, &lt
2da30 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74  ;=, &gt;, or &gt
2da40 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75  ;=.  The particu
2da50 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a  lar operator is.
2da60 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f  ** stored in aCo
2da70 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
2da80 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
2da90 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
2daa0 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61  d in.** aConstra
2dab0 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20  int[].iColumn.  
2dac0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
2dad0 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
2dae0 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
2daf0 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
2db00 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
2db10 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
2db20 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
2db30 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
2db40 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
2db50 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74  t..**.** The opt
2db60 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
2db70 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
2db80 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
2db90 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
2dba0 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
2dbb0 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
2dbc0 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
2dbd0 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
2dbe0 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
2dbf0 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
2dc00 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
2dc10 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
2dc20 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
2dc30 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
2dc40 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
2dc50 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
2dc60 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74  lause terms in t
2dc70 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f  he correct.** fo
2dc80 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f  rm that refer to
2dc90 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
2dca0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
2dcb0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
2dcc0 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** Information a
2dcd0 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
2dce0 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
2dcf0 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
2dd00 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f  ..** Each term o
2dd10 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72  f aOrderBy recor
2dd20 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ds a column of t
2dd30 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
2dd40 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42  se..**.** The xB
2dd50 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
2dd60 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
2dd70 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
2dd80 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2dd90 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
2dda0 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
2ddb0 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61  o xFilter.  If a
2ddc0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
2ddd0 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
2dde0 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
2ddf0 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
2de00 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
2de10 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
2de20 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
2de30 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
2de40 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74  argv.  If aConst
2de50 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
2de60 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
2de70 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
2de80 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
2de90 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
2dea0 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
2deb0 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
2dec0 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
2ded0 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  n by SQLite..**.
2dee0 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  ** The idxNum an
2def0 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
2df00 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
2df10 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69   passed into xFi
2df20 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  lter..** sqlite3
2df30 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20  _free() is used 
2df40 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
2df50 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  f needToFreeIdxP
2df60 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
2df70 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e  * The orderByCon
2df80 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
2df90 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69   output from xFi
2dfa0 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20  lter will occur 
2dfb0 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
2dfc0 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
2dfd0 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
2dfe0 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
2dff0 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
2e000 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
2e010 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
2e020 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
2e030 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
2e040 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
2e050 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
2e060 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
2e070 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
2e080 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
2e090 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
2e0a0 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
2e0b0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
2e0c0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
2e0d0 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
2e0e0 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
2e0f0 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
2e100 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
2e110 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2e120 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
2e130 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
2e140 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a  ct to change or.
2e150 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  ** removal in fu
2e160 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2e170 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75   SQLite..*/.stru
2e180 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2e190 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
2e1a0 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
2e1b0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
2e1c0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
2e1d0 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
2e1e0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
2e1f0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2e200 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
2e210 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
2e220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e230 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
2e240 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
2e250 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
2e260 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
2e270 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
2e280 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
2e290 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
2e2a0 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
2e2b0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
2e2c0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
2e2d0 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
2e2e0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
2e2f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
2e300 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
2e310 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
2e320 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
2e330 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
2e340 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
2e350 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
2e360 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
2e370 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
2e380 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e390 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
2e3a0 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
2e3b0 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
2e3c0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2e3d0 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
2e3e0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
2e3f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
2e400 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
2e410 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
2e420 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
2e430 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
2e440 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
2e450 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
2e460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e470 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
2e480 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
2e490 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
2e4a0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e4b0 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
2e4c0 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
2e4d0 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
2e4e0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
2e4f0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
2e500 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
2e510 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
2e520 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
2e530 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
2e540 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
2e550 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
2e560 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
2e570 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
2e580 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
2e590 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
2e5a0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
2e5b0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
2e5c0 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
2e5d0 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
2e5e0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
2e5f0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
2e600 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
2e610 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
2e620 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
2e630 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
2e640 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
2e650 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
2e660 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
2e670 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
2e680 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
2e690 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
2e6a0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
2e6b0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
2e6c0 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
2e6d0 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
2e6e0 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
2e6f0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2e700 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
2e710 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2e720 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
2e730 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2e740 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2e750 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
2e760 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2e770 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
2e780 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
2e790 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
2e7a0 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
2e7b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
2e7c0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
2e7d0 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
2e7e0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
2e7f0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
2e800 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   Implementation 
2e810 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30  {H18200} <S20400
2e820 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
2e830 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  L.**.** This rou
2e840 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20  tine is used to 
2e850 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d  register a new m
2e860 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20  odule name with 
2e870 61 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  a.** [database c
2e880 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64  onnection].  Mod
2e890 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ule names must b
2e8a0 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66  e registered bef
2e8b0 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20  ore.** creating 
2e8c0 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
2e8d0 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65  es on the module
2e8e0 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e  , or before usin
2e8f0 67 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  g.** preexisting
2e900 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
2e910 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  of the module..*
2e920 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2e930 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
2e940 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
2e950 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a  ct to change or.
2e960 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  ** removal in fu
2e970 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2e980 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
2e990 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
2e9a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2e9b0 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
2e9c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2e9d0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
2e9e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
2e9f0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
2ea00 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
2ea10 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
2ea20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
2ea30 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
2ea40 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
2ea50 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
2ea60 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
2ea70 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
2ea80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ea90 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
2eaa0 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
2eab0 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a  xConnect */.);..
2eac0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ead0 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
2eae0 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
2eaf0 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d  ntation {H18210}
2eb00 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
2eb10 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2eb20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
2eb30 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65  identical to the
2eb40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eb50 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f  _module()] metho
2eb60 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65  d above,.** exce
2eb70 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77  pt that it allow
2eb80 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
2eb90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70  unction to be sp
2eba0 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a  ecified. It is.*
2ebb0 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65  * even more expe
2ebc0 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68  rimental than th
2ebd0 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76 69  e rest of the vi
2ebe0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49  rtual tables API
2ebf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
2ec00 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
2ec10 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
2ec20 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
2ec30 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ec40 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
2ec50 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
2ec60 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
2ec70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ec80 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
2ec90 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
2eca0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
2ecb0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2ecc0 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
2ecd0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
2ece0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
2ecf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ed00 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
2ed10 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
2ed20 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
2ed30 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2ed40 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
2ed50 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
2ed60 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
2ed70 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
2ed80 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65  l Table Instance
2ed90 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d   Object {H18010}
2eda0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2edb0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
2edc0 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  tab.** EXPERIMEN
2edd0 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  TAL.**.** Every 
2ede0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
2edf0 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
2ee00 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c  class of the fol
2ee10 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
2ee20 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20  .** to describe 
2ee30 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
2ee40 74 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64  tance of the mod
2ee50 75 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c  ule.  Each subcl
2ee60 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
2ee70 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
2ee80 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
2ee90 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
2eea0 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54  ementation..** T
2eeb0 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  he purpose of th
2eec0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
2eed0 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
2eee0 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
2eef0 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20  re.** common to 
2ef00 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
2ef10 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
2ef20 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
2ef30 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74   methods can set
2ef40 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2ef50 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61  e by assigning a
2ef60 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69  .** string obtai
2ef70 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2ef80 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  3_mprintf()] to 
2ef90 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65  zErrMsg.  The me
2efa0 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74  thod should.** t
2efb0 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e  ake care that an
2efc0 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69  y prior string i
2efd0 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c  s freed by a cal
2efe0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  l to [sqlite3_fr
2eff0 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74  ee()].** prior t
2f000 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65  o assigning a ne
2f010 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72  w string to zErr
2f020 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65 20  Msg.  After the 
2f030 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
2f040 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70   is delivered up
2f050 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61   to the client a
2f060 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
2f070 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61  string will be a
2f080 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2f090 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33  freed by sqlite3
2f0a0 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20  _free() and the 
2f0b0 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69  zErrMsg field wi
2f0c0 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e  ll be zeroed.  N
2f0d0 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69  ote.** that sqli
2f0e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
2f0f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  d sqlite3_free()
2f100 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65   are used on the
2f110 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a   zErrMsg field.*
2f120 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20  * since virtual 
2f130 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f  tables are commo
2f140 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  nly implemented 
2f150 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65  in loadable exte
2f160 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20  nsions which.** 
2f170 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  do not have acce
2f180 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72  ss to sqlite3MPr
2f190 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65  intf() or sqlite
2f1a0 33 46 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  3Free()..**.** T
2f1b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
2f1c0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
2f1d0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
2f1e0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
2f1f0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
2f200 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2f210 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  e..*/.struct sql
2f220 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
2f230 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
2f240 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
2f250 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
2f260 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
2f270 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
2f280 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
2f290 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
2f2a0 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20  internally */.  
2f2b0 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
2f2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f2d0 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
2f2e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
2f2f0 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
2f300 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
2f310 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
2f320 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
2f330 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
2f340 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
2f350 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
2f360 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f  l Table Cursor O
2f370 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20  bject  {H18020} 
2f380 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
2f390 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
2f3a0 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50  ab_cursor.** EXP
2f3b0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2f3c0 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
2f3d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
2f3e0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
2f3f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
2f400 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
2f410 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
2f420 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
2f430 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
2f440 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
2f450 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
2f460 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2f470 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
2f480 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2f490 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f  e.** xOpen metho
2f4a0 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  d of the module.
2f4b0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
2f4c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2f4d0 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
2f4e0 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
2f4f0 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
2f500 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
2f510 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
2f520 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
2f530 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
2f540 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
2f550 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
2f560 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
2f570 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
2f580 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ons..**.** This 
2f590 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
2f5a0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
2f5b0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
2f5c0 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
2f5d0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2f5e0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2f5f0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2f600 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20  _vtab_cursor {. 
2f610 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70   sqlite3_vtab *p
2f620 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69  Vtab;      /* Vi
2f630 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74  rtual table of t
2f640 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20  his cursor */.  
2f650 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
2f660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2f670 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
2f680 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
2f690 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
2f6a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
2f6b0 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20  lare The Schema 
2f6c0 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  Of A Virtual Tab
2f6d0 6c 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30  le {H18280} <S20
2f6e0 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  400>.** EXPERIME
2f6f0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  NTAL.**.** The x
2f700 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e  Create and xConn
2f710 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ect methods of a
2f720 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20   module use the 
2f730 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
2f740 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20   to declare the 
2f750 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65  format (the name
2f760 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20  s and datatypes 
2f770 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20  of the columns) 
2f780 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61  of.** the virtua
2f790 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d  l tables they im
2f7a0 70 6c 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  plement..**.** T
2f7b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
2f7c0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
2f7d0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
2f7e0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
2f7f0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
2f800 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2f810 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  e..*/.SQLITE_EXP
2f820 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
2f830 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
2f840 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
2f850 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65  st char *zCreate
2f860 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Table);../*.** C
2f870 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
2f880 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
2f890 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
2f8a0 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30   {H18300} <S2040
2f8b0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
2f8c0 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  AL.**.** Virtual
2f8d0 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
2f8e0 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
2f8f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2f900 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
2f910 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46  using the xFindF
2f920 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20  unction method. 
2f930 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
2f940 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
2f950 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
2f960 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
2f970 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
2f980 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2f990 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f  makes sure a glo
2f9a0 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61  bal version of a
2f9b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2f9c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e   particular.** n
2f9d0 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f  ame and number o
2f9e0 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69  f parameters exi
2f9f0 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68  sts.  If no such
2fa00 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73   function exists
2fa10 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20  .** before this 
2fa20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61  API is called, a
2fa30 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
2fa40 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69   created.  The i
2fa50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
2fa60 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63   of the new func
2fa70 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73  tion always caus
2fa80 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  es an exception 
2fa90 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53  to be thrown.  S
2faa0 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e  o.** the new fun
2fab0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f  ction is not goo
2fac0 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62  d for anything b
2fad0 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f  y itself.  Its o
2fae0 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69  nly.** purpose i
2faf0 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68  s to be a placeh
2fb00 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
2fb10 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
2fb20 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74  oaded.** by virt
2fb30 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a  ual tables..**.*
2fb40 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c  * This API shoul
2fb50 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20  d be considered 
2fb60 70 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74  part of the virt
2fb70 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
2fb80 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73  ace,.** which is
2fb90 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
2fba0 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  d subject to cha
2fbb0 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  nge..*/.SQLITE_E
2fbc0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
2fbd0 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
2fbe0 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
2fbf0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
2fc00 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
2fc10 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
2fc20 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
2fc30 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2fc40 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
2fc50 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
2fc60 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
2fc70 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
2fc80 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
2fc90 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
2fca0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
2fcb0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
2fcc0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
2fcd0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
2fce0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
2fcf0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
2fd00 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
2fd10 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
2fd20 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
2fd30 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
2fd40 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
2fd50 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
2fd60 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
2fd70 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
2fd80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
2fd90 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
2fda0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
2fdb0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
2fdc0 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
2fdd0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
2fde0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
2fdf0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
2fe00 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
2fe10 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2fe20 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
2fe30 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31  An Open BLOB {H1
2fe40 37 38 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7800} <S30230>.*
2fe50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f  * KEYWORDS: {BLO
2fe60 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20  B handle} {BLOB 
2fe70 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41  handles}.**.** A
2fe80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
2fe90 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
2fea0 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
2feb0 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73  B on which.** [s
2fec0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2fed0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2fee0 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20  LOB I/O] can be 
2fef0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62  performed..** Ob
2ff00 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
2ff10 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
2ff20 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
2ff30 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64  open()].** and d
2ff40 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2ff50 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
2ff60 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2ff70 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
2ff80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
2ff90 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
2ffa0 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
2ffb0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
2ffc0 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
2ffd0 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
2ffe0 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  BLOB..** The [sq
2fff0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
30000 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
30010 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
30020 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79  f the BLOB in by
30030 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
30040 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
30050 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
30060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30070 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
30080 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
30090 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30  /O {H17810} <S30
300a0 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  230>.**.** This 
300b0 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
300c0 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20   a [BLOB handle 
300d0 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65  | handle] to the
300e0 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a   BLOB located.**
300f0 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
30100 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
30110 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
30120 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
30130 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
30140 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61  he same BLOB tha
30150 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63  t would be selec
30160 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
30170 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
30180 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
30190 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
301a0 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a  [rowid] = iRow;.
301b0 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a  ** </pre> {END}.
301c0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61  **.** If the fla
301d0 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  gs parameter is 
301e0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68  non-zero, the th
301f0 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
30200 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64   for read.** and
30210 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49   write access. I
30220 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
30230 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
30240 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
30250 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
30260 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
30270 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
30280 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
30290 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
302a0 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
302b0 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
302c0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
302d0 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73  se that.** is as
302e0 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20  signed when the 
302f0 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
30300 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
30310 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  ACH]..** For the
30320 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
30330 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
30340 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
30350 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61  ..** For TEMP ta
30360 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61  bles, the databa
30370 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70  se name is "temp
30380 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  "..**.** On succ
30390 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
303a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
303b0 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
303c0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
303d0 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
303e0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
303f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
30400 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 76  turned and any v
30410 61 6c 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20  alue written.** 
30420 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c  to *ppBlob shoul
30430 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
30440 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20   the caller..** 
30450 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65  This function se
30460 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ts the [database
30470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72   connection] err
30480 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
30490 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c  age.** accessibl
304a0 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65  e via [sqlite3_e
304b0 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73  rrcode()] and [s
304c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
304d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
304e0 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
304f0 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
30500 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
30510 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
30520 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
30530 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
30540 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
30550 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
30560 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
30570 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
30580 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
30590 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
305a0 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
305b0 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
305c0 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
305d0 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
305e0 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a  le is open on..*
305f0 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * Calls to [sqli
30600 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
30610 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
30620 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a  ob_write()] for.
30630 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f  ** a expired BLO
30640 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
30650 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64  th an return cod
30660 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
30670 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20  RT]..** Changes 
30680 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
30690 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
306a0 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
306b0 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61  re not.** rollba
306c0 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61  ck by the expira
306d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42  tion of the BLOB
306e0 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20  .  Such changes 
306f0 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a  will eventually.
30700 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65  ** commit if the
30710 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
30720 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
30730 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  tion..**.** Requ
30740 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
30750 37 38 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b  7813] [H17814] [
30760 48 31 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d  H17816] [H17819]
30770 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32   [H17821] [H1782
30780 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  4].*/.int sqlite
30790 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
307a0 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
307b0 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
307c0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
307d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
307e0 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
307f0 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
30800 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
30810 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
30820 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
30830 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20  PI3REF: Close A 
30840 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37  BLOB Handle {H17
30850 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  830} <S30230>.**
30860 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70  .** Closes an op
30870 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
30880 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20  ..**.** Closing 
30890 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75  a BLOB shall cau
308a0 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  se the current t
308b0 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f  ransaction to co
308c0 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65  mmit.** if there
308d0 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c   are no other BL
308e0 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20  OBs, no pending 
308f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30900 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  nts, and the.** 
30910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30920 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63  ion is in [autoc
30930 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20  ommit mode]..** 
30940 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
30950 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
30960 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
30970 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
30980 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
30990 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
309a0 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20   they will fit. 
309b0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73  {END}.**.** Clos
309c0 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74  ing the BLOB oft
309d0 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68  en forces the ch
309e0 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20  anges.** out to 
309f0 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61  disk and so if a
30a00 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63  ny I/O errors oc
30a10 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c  cur, they will l
30a20 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61  ikely occur.** a
30a30 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
30a40 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  the BLOB is clos
30a50 65 64 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e  ed.  {H17833} An
30a60 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  y errors that oc
30a70 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c  cur during.** cl
30a80 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74  osing are report
30a90 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  ed as a non-zero
30aa0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a   return value..*
30ab0 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73  *.** The BLOB is
30ac0 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74   closed uncondit
30ad0 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69  ionally.  Even i
30ae0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
30af0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72  eturns.** an err
30b00 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f  or code, the BLO
30b10 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65  B is still close
30b20 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
30b30 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33  ments:.** [H1783
30b40 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37  3] [H17836] [H17
30b50 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  839].*/.int sqli
30b60 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
30b70 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
30b80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30b90 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
30ba0 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
30bb0 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33   {H17840} <S3023
30bc0 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73  0>.**.** Returns
30bd0 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
30be0 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61  es of the BLOB a
30bf0 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
30c00 65 20 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42  e open.** []BLOB
30c10 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20   handle] in its 
30c20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  only argument..*
30c30 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
30c40 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a  s:.** [H17843].*
30c50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
30c60 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
30c70 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
30c80 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20   CAPI3REF: Read 
30c90 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42  Data From A BLOB
30ca0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b   Incrementally {
30cb0 48 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e  H17850} <S30230>
30cc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
30cd0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
30ce0 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61  read data from a
30cf0 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
30d00 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63  dle] into a.** c
30d10 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62  aller-supplied b
30d20 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f  uffer. N bytes o
30d30 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
30d40 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a  d into buffer Z.
30d50 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e  ** from the open
30d60 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20   BLOB, starting 
30d70 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  at offset iOffse
30d80 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73  t..**.** If offs
30d90 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65  et iOffset is le
30da0 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20  ss than N bytes 
30db0 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20  from the end of 
30dc0 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51  the BLOB,.** [SQ
30dd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
30de0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
30df0 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66  ata is read.  If
30e00 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73   N or iOffset is
30e10 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
30e20 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ro, [SQLITE_ERRO
30e30 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
30e40 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
30e50 61 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74  ad..**.** An att
30e60 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
30e70 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
30e80 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
30e90 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
30ea0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
30eb0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
30ec0 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49  On success, SQLI
30ed0 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
30ee0 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  d..** Otherwise,
30ef0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
30f00 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
30f10 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
30f20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
30f30 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
30f40 20 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35   [H17853] [H1785
30f50 36 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37  6] [H17859] [H17
30f60 38 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48  862] [H17863] [H
30f70 31 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a  17865] [H17868].
30f80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
30f90 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
30fa0 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a  _blob *, void *Z
30fb0 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66  , int N, int iOf
30fc0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
30fd0 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61  PI3REF: Write Da
30fe0 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
30ff0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31  ncrementally {H1
31000 37 38 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7870} <S30230>.*
31010 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
31020 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72  on is used to wr
31030 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e  ite data into an
31040 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
31050 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61  le] from a.** ca
31060 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
31070 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66  ffer. N bytes of
31080 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
31090 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
310a0 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f   Z.** into the o
310b0 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
310c0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
310d0 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  fset..**.** If t
310e0 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
310f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
31100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61  irst argument wa
31110 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72  s not opened for
31120 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65  .** writing (the
31130 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
31140 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
31150 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65  b_open()] was ze
31160 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e  ro),.** this fun
31170 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
31180 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e  QLITE_READONLY].
31190 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
311a0 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f  tion may only mo
311b0 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  dify the content
311c0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69  s of the BLOB; i
311d0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
311e0 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65  ible to increase
311f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42   the size of a B
31200 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41  LOB using this A
31210 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74  PI..** If offset
31220 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
31230 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
31240 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
31250 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
31260 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
31270 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
31280 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49  a is written.  I
31290 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
312a0 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45  han zero [SQLITE
312b0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
312c0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
312d0 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a  is written..**.*
312e0 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20  * An attempt to 
312f0 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69  write to an expi
31300 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  red [BLOB handle
31310 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  ] fails with an.
31320 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66  ** error code of
31330 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
31340 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20    Writes to the 
31350 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72  BLOB that occurr
31360 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  ed.** before the
31370 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65   [BLOB handle] e
31380 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72  xpired are not r
31390 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
313a0 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20  e.** expiration 
313b0 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74  of the handle, t
313c0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
313d0 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69  those changes mi
313e0 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e  ght.** have been
313f0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
31400 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
31410 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42  at expired the B
31420 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72  LOB handle.** or
31430 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65   by other indepe
31440 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  ndent statements
31450 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
31460 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  ss, SQLITE_OK is
31470 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
31480 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72  herwise, an  [er
31490 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
314a0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
314b0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
314c0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
314d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37  ments:.** [H1787
314e0 33 5d 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37  3] [H17874] [H17
314f0 38 37 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48  875] [H17876] [H
31500 31 37 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20  17877] [H17879] 
31510 5b 48 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35  [H17882] [H17885
31520 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f  ].** [H17888].*/
31530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
31540 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
31550 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
31560 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
31570 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
31580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
31590 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d  tual File System
315a0 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30   Objects {H11200
315b0 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20100>.**.**
315c0 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73   A virtual files
315d0 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61  ystem (VFS) is a
315e0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
315f0 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53  object.** that S
31600 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e  QLite uses to in
31610 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74  teract.** with t
31620 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
31630 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
31640 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69   Most SQLite bui
31650 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a  lds come with a.
31660 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c  ** single defaul
31670 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70  t VFS that is ap
31680 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
31690 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
316a0 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61  .** New VFSes ca
316b0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
316c0 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53  and existing VFS
316d0 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69  es can be unregi
316e0 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66  stered..** The f
316f0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
31700 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
31710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
31720 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
31730 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31740 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
31750 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61  VFS given its na
31760 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65  me..** Names are
31770 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
31780 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65  .** Names are ze
31790 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
317a0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
317b0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
317c0 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69  atch, a NULL poi
317d0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
317e0 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65  ..** If zVfsName
317f0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
31800 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
31810 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
31820 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
31830 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
31840 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
31850 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e  ter()..** Each n
31860 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74  ew VFS becomes t
31870 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
31880 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  f the makeDflt f
31890 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54  lag is set..** T
318a0 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20  he same VFS can 
318b0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
318c0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
318d0 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20  hout injury..** 
318e0 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
318f0 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
31900 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
31910 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
31920 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
31930 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
31940 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
31950 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
31960 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
31970 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
31980 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
31990 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
319a0 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
319b0 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
319c0 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
319d0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
319e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
319f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
31a00 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73  d..**.** Unregis
31a10 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74  ter a VFS with t
31a20 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  he sqlite3_vfs_u
31a30 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65  nregister() inte
31a40 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65  rface..** If the
31a50 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
31a60 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e  unregistered, an
31a70 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f  other VFS is cho
31a80 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65  sen as.** the de
31a90 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69  fault.  The choi
31aa0 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56  ce for the new V
31ab0 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  FS is arbitrary.
31ac0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
31ad0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d  nts:.** [H11203]
31ae0 20 5b 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30   [H11206] [H1120
31af0 39 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31  9] [H11212] [H11
31b00 32 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f  215] [H11218].*/
31b10 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71  .sqlite3_vfs *sq
31b20 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63  lite3_vfs_find(c
31b30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e  onst char *zVfsN
31b40 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ame);.int sqlite
31b50 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73  3_vfs_register(s
31b60 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
31b70 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20   makeDflt);.int 
31b80 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
31b90 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
31ba0 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  fs*);../*.** CAP
31bb0 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b  I3REF: Mutexes {
31bc0 48 31 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e  H17000} <S20000>
31bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
31be0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
31bf0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74  e routines for t
31c00 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f  hread.** synchro
31c10 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68  nization. Though
31c20 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64   they are intend
31c30 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  ed for internal.
31c40 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
31c50 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b  , code that link
31c60 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65  s against SQLite
31c70 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64   is.** permitted
31c80 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74   to use any of t
31c90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
31ca0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
31cb0 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74  source code cont
31cc0 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ains multiple im
31cd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
31ce0 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20   of these mutex 
31cf0 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70  routines.  An ap
31d00 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d  propriate implem
31d10 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73  entation.** is s
31d20 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69  elected automati
31d30 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65  cally at compile
31d40 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c  -time.  The foll
31d50 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65  owing.** impleme
31d60 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61  ntations are ava
31d70 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51  ilable in the SQ
31d80 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a  Lite core:.**.**
31d90 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20   <ul>.** <li>   
31da0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
31db0 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
31dc0 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a  E_MUTEX_PTHREAD.
31dd0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
31de0 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c  _MUTEX_W32.** <l
31df0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
31e00 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a  X_NOOP.** </ul>.
31e10 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
31e20 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c  _MUTEX_NOOP impl
31e30 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20  ementation is a 
31e40 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a  set of routines.
31e50 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20  ** that does no 
31e60 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64  real locking and
31e70 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   is appropriate 
31e80 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20  for use in.** a 
31e90 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20  single-threaded 
31ea0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
31eb0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f  e SQLITE_MUTEX_O
31ec0 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  S2,.** SQLITE_MU
31ed0 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64  TEX_PTHREAD, and
31ee0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
31ef0 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  2 implementation
31f00 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72  s.** are appropr
31f10 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20  iate for use on 
31f20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20  OS/2, Unix, and 
31f30 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49  Windows..**.** I
31f40 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
31f50 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
31f60 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
31f70 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
31f80 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
31f90 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
31fa0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
31fb0 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
31fc0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
31fd0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
31fe0 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
31ff0 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65  In this case the
32000 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
32010 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75  must supply a cu
32020 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65  stom mutex imple
32030 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20  mentation using 
32040 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
32050 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
32060 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ion of the sqlit
32070 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63  e3_config() func
32080 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63  tion.** before c
32090 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69  alling sqlite3_i
320a0 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61  nitialize() or a
320b0 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20  ny other public 
320c0 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63  sqlite3_.** func
320d0 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20  tion that calls 
320e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
320f0 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ze()..**.** {H17
32100 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  011} The sqlite3
32110 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72  _mutex_alloc() r
32120 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73  outine allocates
32130 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20   a new.** mutex 
32140 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
32150 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31  inter to it. {H1
32160 37 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75  7012} If it retu
32170 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
32180 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
32190 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
321a0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37   allocated. {H17
321b0 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77  013} SQLite.** w
321c0 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73  ill unwind its s
321d0 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20  tack and return 
321e0 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31  an error. {H1701
321f0 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  4} The argument.
32200 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ** to sqlite3_mu
32210 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f  tex_alloc() is o
32220 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
32230 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  ger constants:.*
32240 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
32250 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
32260 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  FAST.** <li>  SQ
32270 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
32280 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
32290 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
322a0 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e  C_MASTER.** <li>
322b0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
322c0 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69  TATIC_MEM.** <li
322d0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
322e0 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c  STATIC_MEM2.** <
322f0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
32300 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a  X_STATIC_PRNG.**
32310 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
32320 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a  TEX_STATIC_LRU.*
32330 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
32340 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32  UTEX_STATIC_LRU2
32350 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
32360 7b 48 31 37 30 31 35 7d 20 54 68 65 20 66 69 72  {H17015} The fir
32370 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  st two constants
32380 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
32390 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
323a0 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
323b0 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20  mutex.  The new 
323c0 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
323d0 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
323e0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
323f0 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
32400 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
32410 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
32420 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
32430 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75   {END}.** The mu
32440 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
32450 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
32460 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69   to make a disti
32470 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
32480 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
32490 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c  ECURSIVE and SQL
324a0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
324b0 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  f it does.** not
324c0 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30   want to.  {H170
324d0 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77  16} But SQLite w
324e0 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74  ill only request
324f0 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74   a recursive mut
32500 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77  ex in.** cases w
32510 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e  here it really n
32520 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d  eeds one.  {END}
32530 20 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e   If a faster non
32540 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78  -recursive mutex
32550 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
32560 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
32570 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74  on the host plat
32580 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20  form, the mutex 
32590 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67  subsystem.** mig
325a0 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61  ht return such a
325b0 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e   mutex in respon
325c0 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54  se to SQLITE_MUT
325d0 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b  EX_FAST..**.** {
325e0 48 31 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65  H17017} The othe
325f0 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65  r allowed parame
32600 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  ters to sqlite3_
32610 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61  mutex_alloc() ea
32620 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70  ch return.** a p
32630 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74  ointer to a stat
32640 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d  ic preexisting m
32650 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75  utex. {END}  Fou
32660 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  r static mutexes
32670 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20   are.** used by 
32680 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73  the current vers
32690 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ion of SQLite.  
326a0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
326b0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79  of SQLite.** may
326c0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
326d0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20  static mutexes. 
326e0 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   Static mutexes 
326f0 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  are for internal
32700 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
32710 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  e only.  Applica
32720 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53  tions that use S
32730 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68  QLite mutexes sh
32740 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79  ould.** use only
32750 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
32760 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  exes returned by
32770 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
32780 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f  ST or.** SQLITE_
32790 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e  MUTEX_RECURSIVE.
327a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20  .**.** {H17018} 
327b0 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65  Note that if one
327c0 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20   of the dynamic 
327d0 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73  mutex parameters
327e0 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46   (SQLITE_MUTEX_F
327f0 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45  AST.** or SQLITE
32800 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
32810 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73  ) is used then s
32820 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
32830 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  oc().** returns 
32840 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65  a different mute
32850 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e  x on every call.
32860 20 20 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66    {H17034} But f
32870 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a  or the static.**
32880 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68   mutex types, th
32890 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20  e same mutex is 
328a0 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72  returned on ever
328b0 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a  y call that has.
328c0 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65  ** the same type
328d0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b   number..**.** {
328e0 48 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69  H17019} The sqli
328f0 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29  te3_mutex_free()
32900 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63   routine dealloc
32910 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c  ates a previousl
32920 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64  y.** allocated d
32930 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48  ynamic mutex. {H
32940 31 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73  17020} SQLite is
32950 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c   careful to deal
32960 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20  locate every.** 
32970 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68  dynamic mutex th
32980 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e  at it allocates.
32990 20 7b 41 31 37 30 32 31 7d 20 54 68 65 20 64 79   {A17021} The dy
329a0 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75  namic mutexes mu
329b0 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20  st not be in.** 
329c0 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72  use when they ar
329d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b  e deallocated. {
329e0 41 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69  A17022} Attempti
329f0 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ng to deallocate
32a00 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74   a static.** mut
32a10 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ex results in un
32a20 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
32a30 2e 20 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74  . {H17023} SQLit
32a40 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61  e never dealloca
32a50 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20  tes.** a static 
32a60 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  mutex. {END}.**.
32a70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
32a80 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64  utex_enter() and
32a90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
32aa0 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74  ry() routines at
32ab0 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65  tempt.** to ente
32ac0 72 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30  r a mutex. {H170
32ad0 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74  24} If another t
32ae0 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
32af0 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65   within the mute
32b00 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  x,.** sqlite3_mu
32b10 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c  tex_enter() will
32b20 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74   block and sqlit
32b30 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77  e3_mutex_try() w
32b40 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  ill return.** SQ
32b50 4c 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30  LITE_BUSY. {H170
32b60 32 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33  25}  The sqlite3
32b70 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74  _mutex_try() int
32b80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b  erface returns [
32b90 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70  SQLITE_OK].** up
32ba0 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e  on successful en
32bb0 74 72 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d  try.  {H17026} M
32bc0 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
32bd0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
32be0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
32bf0 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
32c00 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
32c10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
32c20 0a 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20  .** {H17027} In 
32c30 73 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a  such cases the,.
32c40 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65  ** mutex must be
32c50 20 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c   exited an equal
32c60 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
32c70 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20   before another 
32c80 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e  thread.** can en
32c90 74 65 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49  ter.  {A17028} I
32ca0 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  f the same threa
32cb0 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72  d tries to enter
32cc0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69   any other.** ki
32cd0 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65  nd of mutex more
32ce0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20   than once, the 
32cf0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
32d00 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32  fined..** {H1702
32d10 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  9} SQLite will n
32d20 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20  ever exhibit.** 
32d30 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e  such behavior in
32d40 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20   its own use of 
32d50 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53  mutexes..**.** S
32d60 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72  ome systems (for
32d70 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77   example, Window
32d80 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70  s 95) do not sup
32d90 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69  port the operati
32da0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65  on.** implemente
32db0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74  d by sqlite3_mut
32dc0 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68  ex_try().  On th
32dd0 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c  ose systems, sql
32de0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
32df0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  .** will always 
32e00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
32e10 53 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68  SY.  {H17030} Th
32e20 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
32e30 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20  ly ever uses.** 
32e40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
32e50 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69  y() as an optimi
32e60 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69  zation so this i
32e70 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68  s acceptable beh
32e80 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  avior..**.** {H1
32e90 37 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65  7031} The sqlite
32ea0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
32eb0 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20  routine exits a 
32ec0 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a  mutex that was.*
32ed0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74  * previously ent
32ee0 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65  ered by the same
32ef0 20 74 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33   thread.  {A1703
32f00 32 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a  2} The behavior.
32f10 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ** is undefined 
32f20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20  if the mutex is 
32f30 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  not currently en
32f40 74 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  tered by the.** 
32f50 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f  calling thread o
32f60 72 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  r is not current
32f70 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b  ly allocated.  {
32f80 48 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77  H17033} SQLite w
32f90 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20  ill.** never do 
32fa0 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a  either. {END}.**
32fb0 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d  .** If the argum
32fc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ent to sqlite3_m
32fd0 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71  utex_enter(), sq
32fe0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
32ff0 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  ), or.** sqlite3
33000 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69  _mutex_leave() i
33010 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
33020 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65  , then all three
33030 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68   routines.** beh
33040 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  ave as no-ops..*
33050 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33060 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
33070 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ld()] and [sqlit
33080 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
33090 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ()]..*/.sqlite3_
330a0 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d  mutex *sqlite3_m
330b0 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b  utex_alloc(int);
330c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
330d0 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33  tex_free(sqlite3
330e0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
330f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
33100 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  er(sqlite3_mutex
33110 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33120 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65  mutex_try(sqlite
33130 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20  3_mutex*);.void 
33140 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
33150 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ave(sqlite3_mute
33160 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
33170 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68  3REF: Mutex Meth
33180 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31  ods Object {H171
33190 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20  20} <S20130>.** 
331a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
331b0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
331c0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
331d0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77   defines the low
331e0 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a  -level routines.
331f0 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63  ** used to alloc
33200 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65  ate and use mute
33210 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c  xes..**.** Usual
33220 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20  ly, the default 
33230 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
33240 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62  tions provided b
33250 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20  y SQLite are.** 
33260 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65  sufficient, howe
33270 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 73  ver the user has
33280 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73   the option of s
33290 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 75  ubstituting a cu
332a0 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  stom.** implemen
332b0 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69  tation for speci
332c0 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e  alized deploymen
332d0 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f  ts or systems fo
332e0 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a  r which SQLite.*
332f0 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  * does not provi
33300 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  de a suitable im
33310 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e  plementation. In
33320 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
33330 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20  user.** creates 
33340 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  and populates an
33350 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
33360 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 70  s structure to p
33370 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ass.** to sqlite
33380 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67  3_config() along
33390 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
333a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
333b0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74  option..** Addit
333c0 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74  ionally, an inst
333d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
333e0 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  ucture can be us
333f0 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70  ed as an.** outp
33400 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e  ut variable when
33410 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 79   querying the sy
33420 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72  stem for the cur
33430 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  rent mutex.** im
33440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73  plementation, us
33450 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
33460 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
33470 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54   option..**.** T
33480 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65  he xMutexInit me
33490 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20  thod defined by 
334a0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69  this structure i
334b0 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20  s invoked as.** 
334c0 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69  part of system i
334d0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79  nitialization by
334e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   the sqlite3_ini
334f0 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  tialize() functi
33500 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20  on..** {H17001} 
33510 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72  The xMutexInit r
33520 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20  outine shall be 
33530 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65  called by SQLite
33540 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a   once for each.*
33550 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  * effective call
33560 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69   to [sqlite3_ini
33570 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  tialize()]..**.*
33580 2a 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20  * The xMutexEnd 
33590 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62  method defined b
335a0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
335b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a   is invoked as.*
335c0 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d  * part of system
335d0 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65   shutdown by the
335e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
335f0 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  n() function. Th
33600 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
33610 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68  ion of this meth
33620 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20 74  od is expected t
33630 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75  o release all ou
33640 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73  tstanding.** res
33650 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20  ources obtained 
33660 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74  by the mutex met
33670 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hods implementat
33680 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a  ion, especially.
33690 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65  ** those obtaine
336a0 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 49  d by the xMutexI
336b0 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37  nit method. {H17
336c0 30 30 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45  003} The xMutexE
336d0 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  nd().** interfac
336e0 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b  e shall be invok
336f0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
33700 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33710 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
33720 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  *.** The remaini
33730 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73  ng seven methods
33740 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
33750 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74   structure (xMut
33760 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74  exAlloc,.** xMut
33770 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e  exFree, xMutexEn
33780 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20  ter, xMutexTry, 
33790 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75  xMutexLeave, xMu
337a0 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78  texHeld and.** x
337b0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d  MutexNotheld) im
337c0 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c  plement the foll
337d0 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
337e0 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a   (respectively):
337f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
33800 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
33810 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c  mutex_alloc()] <
33820 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
33830 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66  [sqlite3_mutex_f
33840 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ree()] </li>.** 
33850 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
33860 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20  _mutex_enter()] 
33870 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
33880 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
33890 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  try()] </li>.** 
338a0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
338b0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20  _mutex_leave()] 
338c0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
338d0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
338e0 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
338f0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
33900 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
33910 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  )] </li>.** </ul
33920 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  >.**.** The only
33930 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74   difference is t
33940 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73  hat the public s
33950 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74  qlite3_XXX funct
33960 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a  ions enumerated.
33970 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c  ** above silentl
33980 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76  y ignore any inv
33990 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61  ocations that pa
339a0 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ss a NULL pointe
339b0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
339c0 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
339d0 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d  ndle. The implem
339e0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
339f0 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
33a00 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75  .** by this stru
33a10 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65  cture are not re
33a20 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65  quired to handle
33a30 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
33a40 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61  results.** of pa
33a50 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
33a60 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
33a70 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
33a80 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e  ndle are undefin
33a90 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69  ed.** (i.e. it i
33aa0 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20  s acceptable to 
33ab0 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65  provide an imple
33ac0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73  mentation that s
33ad0 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69  egfaults if.** i
33ae0 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55  t is passed a NU
33af0 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a  LL pointer)..*/.
33b00 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
33b10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
33b20 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74  hods sqlite3_mut
33b30 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  ex_methods;.stru
33b40 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
33b50 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
33b60 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76   (*xMutexInit)(v
33b70 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  oid);.  int (*xM
33b80 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a  utexEnd)(void);.
33b90 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20    sqlite3_mutex 
33ba0 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28  *(*xMutexAlloc)(
33bb0 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  int);.  void (*x
33bc0 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74  MutexFree)(sqlit
33bd0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76  e3_mutex *);.  v
33be0 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65  oid (*xMutexEnte
33bf0 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  r)(sqlite3_mutex
33c00 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
33c10 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f  texTry)(sqlite3_
33c20 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
33c30 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28   (*xMutexLeave)(
33c40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
33c50 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
33c60 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75  Held)(sqlite3_mu
33c70 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  tex *);.  int (*
33c80 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73  xMutexNotheld)(s
33c90 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
33ca0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
33cb0 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
33cc0 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ication Routines
33cd0 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33   {H17080} <S2013
33ce0 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a  0> <S30800>.**.*
33cf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
33d00 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73  tex_held() and s
33d10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
33d20 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a  held() routines.
33d30 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
33d40 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
33d50 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
33d60 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65  ts. {H17081} The
33d70 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20   SQLite core.** 
33d80 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65  never uses these
33d90 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74   routines except
33da0 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72   inside an asser
33db0 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74  t() and applicat
33dc0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69  ions.** are advi
33dd0 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68  sed to follow th
33de0 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f  e lead of the co
33df0 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68  re.  {H17082} Th
33e00 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70  e core only.** p
33e10 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e  rovides implemen
33e20 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73  tations for thes
33e30 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20  e routines when 
33e40 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  it is compiled.*
33e50 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  * with the SQLIT
33e60 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b  E_DEBUG flag.  {
33e70 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c  A17087} External
33e80 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
33e90 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e  ations.** are on
33ea0 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ly required to p
33eb0 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75  rovide these rou
33ec0 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f  tines if SQLITE_
33ed0 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69  DEBUG is.** defi
33ee0 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55  ned and if NDEBU
33ef0 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64  G is not defined
33f00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d  ..**.** {H17083}
33f10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33f20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72  should return tr
33f30 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ue if the mutex 
33f40 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e  in their argumen
33f50 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20  t.** is held or 
33f60 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63  not held, respec
33f70 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63  tively, by the c
33f80 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a  alling thread..*
33f90 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68  *.** {X17084} Th
33fa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33fb0 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64   is not required
33fc0 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72   to provided ver
33fd0 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a  sions of these.*
33fe0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
33ff0 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49  actually work. I
34000 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  f the implementa
34010 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72  tion does not pr
34020 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a  ovide working.**
34030 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
34040 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20  se routines, it 
34050 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20  should at least 
34060 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68  provide stubs th
34070 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74  at always.** ret
34080 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74  urn true so that
34090 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65   one does not ge
340a0 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72  t spurious asser
340b0 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a  tion failures..*
340c0 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66  *.** {H17085} If
340d0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
340e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
340f0 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  eld() is a NULL 
34100 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
34110 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  the routine shou
34120 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45  ld return 1.  {E
34130 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63  ND} This seems c
34140 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65  ounter-intuitive
34150 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c   since.** clearl
34160 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e  y the mutex cann
34170 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74  ot be held if it
34180 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e   does not exist.
34190 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65    But the.** the
341a0 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65   reason the mute
341b0 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  x does not exist
341c0 20 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20   is because the 
341d0 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20  build is not.** 
341e0 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20  using mutexes.  
341f0 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61  And we do not wa
34200 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20  nt the assert() 
34210 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
34220 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
34230 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74  3_mutex_held() t
34240 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e  o fail, so a non
34250 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a  -zero return is.
34260 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ** the appropria
34270 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20  te thing to do. 
34280 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20 73 71   {H17086} The sq
34290 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
342a0 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  eld().** interfa
342b0 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72  ce should also r
342c0 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76  eturn 1 when giv
342d0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
342e0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
342f0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c  3_mutex_held(sql
34300 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
34310 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
34320 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  notheld(sqlite3_
34330 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
34340 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
34350 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c  Types {H17001} <
34360 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H17000>.**.** Th
34370 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
34380 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
34390 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
343a0 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
343b0 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
343c0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
343d0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  stants..**.** Th
343e0 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 20  e set of static 
343f0 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e  mutexes may chan
34400 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69  ge from one SQLi
34410 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  te release to th
34420 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
34430 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ications that ov
34440 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c 74  erride the built
34450 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20  -in mutex logic 
34460 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61  must be.** prepa
34470 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61  red to accommoda
34480 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  te additional st
34490 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f  atic mutexes..*/
344a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
344b0 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20  MUTEX_FAST      
344c0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
344d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
344e0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31  CURSIVE        1
344f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34500 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
34510 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65  TER    2.#define
34520 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
34530 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33  ATIC_MEM       3
34540 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c    /* sqlite3_mal
34550 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  loc() */.#define
34560 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
34570 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34  ATIC_MEM2      4
34580 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c    /* sqlite3_rel
34590 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f  ease_memory() */
345a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
345b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
345c0 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
345d0 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
345e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
345f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
34600 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
34610 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64   page list */.#d
34620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
34630 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20  EX_STATIC_LRU2  
34640 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61      7  /* lru pa
34650 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
34660 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
34670 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66  ieve the mutex f
34680 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
34690 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32  nnection {H17002
346a0 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <H17000>.**.**
346b0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
346c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
346d0 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  r the [sqlite3_m
346e0 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61  utex] object tha
346f0 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73  t .** serializes
34700 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b   access to the [
34710 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34720 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68  ion] given in th
34730 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68  e argument.** wh
34740 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  en the [threadin
34750 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61  g mode] is Seria
34760 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  lized..** If the
34770 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
34780 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] is Single-thre
34790 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65  ad or Multi-thre
347a0 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20  ad then this.** 
347b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
347c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
347d0 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
347e0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74   *sqlite3_db_mut
347f0 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  ex(sqlite3*);../
34800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
34810 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c  ow-Level Control
34820 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c   Of Database Fil
34830 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30  es {H11300} <S30
34840 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  800>.**.** {H113
34850 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
34860 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
34870 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
34880 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74   a direct call t
34890 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f  o the.** xFileCo
348a0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72  ntrol method for
348b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
348c0 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
348d0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
348e0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
348f0 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69   database identi
34900 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
34910 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31  nd argument. {H1
34920 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d  1302} The.** nam
34930 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
34940 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73  e is the name as
34950 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61  signed to the da
34960 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a  tabase by the.**
34970 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61   <a href="lang_a
34980 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41  ttach.html">ATTA
34990 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61  CH</a> SQL comma
349a0 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74  nd that opened t
349b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
349c0 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74  {H11303} To cont
349d0 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74  rol the main dat
349e0 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20  abase file, use 
349f0 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a  the name "main".
34a00 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ** or a NULL poi
34a10 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54  nter. {H11304} T
34a20 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
34a30 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
34a40 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  o this routine.*
34a50 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72  * are passed dir
34a60 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f  ectly through to
34a70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
34a80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73  third parameters
34a90 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65   of.** the xFile
34aa0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
34ab0 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65   {H11305} The re
34ac0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
34ad0 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a  e xFileControl.*
34ae0 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73  * method becomes
34af0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34b00 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
34b10 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36  e..**.** {H11306
34b20 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  } If the second 
34b30 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61  parameter (zDbNa
34b40 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74  me) does not mat
34b50 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ch the name of a
34b60 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ny.** open datab
34b70 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53  ase file, then S
34b80 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72  QLITE_ERROR is r
34b90 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37  eturned. {H11307
34ba0 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20  } This error.** 
34bb0 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65  code is not reme
34bc0 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20  mbered and will 
34bd0 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20  not be recalled 
34be0 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
34bf0 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  ode()].** or [sq
34c00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
34c10 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e   {A11308} The un
34c20 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f  derlying xFileCo
34c30 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67  ntrol method mig
34c40 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72  ht.** also retur
34c50 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  n SQLITE_ERROR. 
34c60 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20   {A11309} There 
34c70 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73  is no way to dis
34c80 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e  tinguish between
34c90 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74  .** an incorrect
34ca0 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20   zDbName and an 
34cb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74  SQLITE_ERROR ret
34cc0 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  urn from the und
34cd0 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65  erlying.** xFile
34ce0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
34cf0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20  {END}.**.** See 
34d00 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
34d10 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
34d20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
34d30 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
34d40 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
34d50 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
34d60 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
34d70 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69   CAPI3REF: Testi
34d80 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31  ng Interface {H1
34d90 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a  1400} <S30800>.*
34da0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34db0 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20  _test_control() 
34dc0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
34dd0 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e  d to read out in
34de0 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20  ternal.** state 
34df0 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f  of SQLite and to
34e00 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69   inject faults i
34e10 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74  nto SQLite for t
34e20 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73  esting.** purpos
34e30 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  es.  The first p
34e40 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f  arameter is an o
34e50 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68  peration code th
34e60 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
34e70 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61   the number, mea
34e80 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74  ning, and operat
34e90 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65  ion of all subse
34ea0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
34eb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
34ec0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f  erface is not fo
34ed0 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61  r use by applica
34ee0 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74  tions.  It exist
34ef0 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20  s solely.** for 
34f00 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f  verifying the co
34f10 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrect operation 
34f20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
34f30 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e  brary.  Dependin
34f40 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20  g.** on how the 
34f50 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
34f60 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73  s compiled, this
34f70 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
34f80 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a   not exist..**.*
34f90 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
34fa0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63   the operation c
34fb0 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e  odes, their mean
34fc0 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65  ings, the parame
34fd0 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b  ters.** they tak
34fe0 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79  e, and what they
34ff0 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a   do are all subj
35000 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
35010 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a  thout notice..**
35020 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20   Unlike most of 
35030 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20  the SQLite API, 
35040 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
35050 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
35060 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f  to.** operate co
35070 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20  nsistently from 
35080 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
35090 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20  he next..*/.int 
350a0 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
350b0 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e  trol(int op, ...
350c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
350d0 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65  EF: Testing Inte
350e0 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20  rface Operation 
350f0 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c  Codes {H11410} <
35100 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H11400>.**.** Th
35110 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
35120 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72  e the valid oper
35130 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d  ation code param
35140 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73  eters used.** as
35150 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35160 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
35170 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e  test_control()].
35180 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72  .**.** These par
35190 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69  ameters and thei
351a0 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73  r meanings are s
351b0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
351c0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  .** without noti
351d0 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65  ce.  These value
351e0 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e  s are for testin
351f0 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e  g purposes only.
35200 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
35210 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
35220 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72  any of these par
35230 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a  ameters or the.*
35240 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  * [sqlite3_test_
35250 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
35260 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
35270 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
35280 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20  _PRNG_SAVE      
35290 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
352a0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
352b0 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45  TRL_PRNG_RESTORE
352c0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
352d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
352e0 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45  STCTRL_PRNG_RESE
352f0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
35300 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
35310 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43  _TESTCTRL_BITVEC
35320 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20  _TEST           
35330 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
35340 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55  ITE_TESTCTRL_FAU
35350 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20  LT_INSTALL      
35360 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
35370 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
35380 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f  BENIGN_MALLOC_HO
35390 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69  OKS     10.#defi
353a0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
353b0 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20  RL_PENDING_BYTE 
353c0 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
353d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
353e0 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53 74  QLite Runtime St
353f0 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c 53  atus {H17200} <S
35400 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60200>.** EXPERI
35410 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69  MENTAL.**.** Thi
35420 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  s interface is u
35430 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
35440 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69  runtime status i
35450 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
35460 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d 61  out the preforma
35470 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20 61  nce of SQLite, a
35480 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f  nd optionally to
35490 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a 2a   reset various.*
354a0 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  * highwater mark
354b0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  s.  The first ar
354c0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
354d0 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a  eger code for.**
354e0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70 61   the specific pa
354f0 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73 75  rameter to measu
35500 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64 20  re.  Recognized 
35510 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a  integer codes.**
35520 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d   are of the form
35530 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f   [SQLITE_STATUS_
35540 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51  MEMORY_USED | SQ
35550 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d  LITE_STATUS_...]
35560 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74  ..** The current
35570 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 61   value of the pa
35580 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75 72  rameter is retur
35590 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 65  ned into *pCurre
355a0 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68 65  nt..** The highe
355b0 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75  st recorded valu
355c0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e  e is returned in
355d0 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20 49   *pHighwater.  I
355e0 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c  f the.** resetFl
355f0 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ag is true, then
35600 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65 63   the highest rec
35610 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 73  ord value is res
35620 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69  et after.** *pHi
35630 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74 74  ghwater is writt
35640 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65 74  en. Some paramet
35650 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72  ers do not recor
35660 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a  d the highest.**
35670 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f   value.  For tho
35680 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
35690 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74   nothing is writ
356a0 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 77  ten into *pHighw
356b0 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65 73  ater and the res
356c0 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 65  etFlag is ignore
356d0 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72 61  d..** Other para
356e0 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f 6e  meters record on
356f0 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65 72  ly the highwater
35700 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68   mark and not th
35710 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c  e current.** val
35720 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20 6c  ue.  For these l
35730 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72 73  atter parameters
35740 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74   nothing is writ
35750 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72 65  ten into *pCurre
35760 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  nt..**.** This r
35770 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
35780 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
35790 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65  ess and a non-ze
357a0 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ro.** [error cod
357b0 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
357c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
357d0 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 20  e is threadsafe 
357e0 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69  but is not atomi
357f0 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  c.  This routine
35800 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77   can.** called w
35810 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61  hile other threa
35820 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74  ds are running t
35830 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65  he same or diffe
35840 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69  rent SQLite.** i
35850 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
35860 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72  ver the values r
35870 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72  eturned in *pCur
35880 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69  rent and.** *pHi
35890 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20  ghwater reflect 
358a0 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51  the status of SQ
358b0 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e  Lite at differen
358c0 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65  t points in time
358d0 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f  .** and it is po
358e0 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74  ssible that anot
358f0 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74  her thread might
35900 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61   change the para
35910 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77  meter.** in betw
35920 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68  een the times wh
35930 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64  en *pCurrent and
35940 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65   *pHighwater are
35950 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20   written..**.** 
35960 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
35970 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a  e3_db_status()].
35980 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
35990 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
359a0 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70  e3_status(int op
359b0 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c  , int *pCurrent,
359c0 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72   int *pHighwater
359d0 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  , int resetFlag)
359e0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
359f0 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d  EF: Status Param
35a00 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c  eters {H17250} <
35a10 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  H17200>.** EXPER
35a20 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
35a30 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
35a40 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20  tants designate 
35a50 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65  various run-time
35a60 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65   status paramete
35a70 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  rs.** that can b
35a80 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
35a90 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
35aa0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
35ab0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
35ac0 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64  S_MEMORY_USED</d
35ad0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
35ae0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
35af0 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f  current amount o
35b00 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64  f memory checked
35b10 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73   out.** using [s
35b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35b30 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74 6c  , either directl
35b40 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e  y or indirectly.
35b50 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20    The.** figure 
35b60 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d  includes calls m
35b70 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ade to [sqlite3_
35b80 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65  malloc()] by the
35b90 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
35ba0 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  and internal mem
35bb0 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68 65  ory usage by the
35bc0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
35bd0 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79    Scratch memory
35be0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  .** controlled b
35bf0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
35c00 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75  _SCRATCH] and au
35c10 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63  xiliary page-cac
35c20 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e  he.** memory con
35c30 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49  trolled by [SQLI
35c40 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
35c50 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c  CHE] is not incl
35c60 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20  uded in.** this 
35c70 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
35c80 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20  amount returned 
35c90 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68  is the sum of th
35ca0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  e allocation.** 
35cb0 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65  sizes as reporte
35cc0 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d  d by the xSize m
35cd0 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65  ethod in [sqlite
35ce0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c  3_mem_methods].<
35cf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
35d00 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c  QLITE_STATUS_MAL
35d10 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a  LOC_SIZE</dt>.**
35d20 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
35d30 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20  ter records the 
35d40 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61  largest memory a
35d50 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
35d60 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b  t.** handed to [
35d70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
35d80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
35d90 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65  alloc()] (or the
35da0 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65  ir.** internal e
35db0 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e  quivalents).  On
35dc0 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ly the value ret
35dd0 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  urned in the.** 
35de0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61  *pHighwater para
35df0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
35e00 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f  3_status()] is o
35e10 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a  f interest.  .**
35e20 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74   The value writt
35e30 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75  en into the *pCu
35e40 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20  rrent parameter 
35e50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  is undefined.</d
35e60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
35e70 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43  ITE_STATUS_PAGEC
35e80 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a  ACHE_USED</dt>.*
35e90 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
35ea0 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65  eter returns the
35eb0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
35ec0 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65   used out of the
35ed0 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 6d  .** [pagecache m
35ee0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
35ef0 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 67   that was config
35f00 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ured using .** [
35f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
35f20 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a  GECACHE].  The.*
35f30 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  * value returned
35f40 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f   is in pages, no
35f50 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  t in bytes.</dd>
35f60 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
35f70 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43  E_STATUS_PAGECAC
35f80 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e  HE_OVERFLOW</dt>
35f90 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
35fa0 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
35fb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35fc0 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 65  es of page cache
35fd0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77  .** allocation w
35fe0 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62  hich could not b
35ff0 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20  e statisfied by 
36000 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
36010 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a  IG_PAGECACHE].**
36020 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72   buffer and wher
36030 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72  e forced to over
36040 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33  flow to [sqlite3
36050 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
36060 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 6c  .** returned val
36070 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f  ue includes allo
36080 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65  cations that ove
36090 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 20  rflowed because 
360a0 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f  they.** where to
360b0 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 65  o large (they we
360c0 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  re larger than t
360d0 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65  he "sz" paramete
360e0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
360f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
36100 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f  ]) and allocatio
36110 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77  ns that overflow
36120 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f  ed because.** no
36130 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 20   space was left 
36140 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
36150 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
36160 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
36170 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f  PAGECACHE_SIZE</
36180 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
36190 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64  parameter record
361a0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65  s the largest me
361b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
361c0 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65  request.** hande
361d0 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 20  d to [pagecache 
361e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
361f0 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c  ].  Only the val
36200 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74  ue returned in t
36210 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65  he.** *pHighwate
36220 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
36230 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
36240 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74  ] is of interest
36250 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .  .** The value
36260 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
36270 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61  e *pCurrent para
36280 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e  meter is undefin
36290 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
362a0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
362b0 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f 64  _SCRATCH_USED</d
362c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
362d0 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73  arameter returns
362e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
362f0 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 20  llocations used 
36300 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  out of the.** [s
36310 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c  cratch memory al
36320 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
36330 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51  red using.** [SQ
36340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
36350 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  TCH].  The value
36360 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20   returned is in 
36370 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74  allocations, not
36380 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 53  .** in bytes.  S
36390 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 68  ince a single th
363a0 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61  read may only ha
363b0 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 61  ve one scratch a
363c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74  llocation.** out
363d0 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d 65  standing at time
363e0 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  , this parameter
363f0 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 68   also reports th
36400 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  e number of thre
36410 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72  ads.** using scr
36420 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 74  atch memory at t
36430 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64  he same time.</d
36440 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
36450 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
36460 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e  CH_OVERFLOW</dt>
36470 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
36480 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
36490 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
364a0 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  es of scratch me
364b0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
364c0 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e  on which could n
364d0 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64  ot be statisfied
364e0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
364f0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 0a  CONFIG_SCRATCH].
36500 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68  ** buffer and wh
36510 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76  ere forced to ov
36520 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74  erflow to [sqlit
36530 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
36540 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74  he values.** ret
36550 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f 76  urned include ov
36560 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 20  erflows because 
36570 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c  the requested al
36580 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f  location was too
36590 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 74  .** larger (that
365a0 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 65   is, because the
365b0 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63   requested alloc
365c0 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 72  ation was larger
365d0 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a   than the.** "sz
365e0 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  " parameter to [
365f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
36600 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 61  RATCH]) and beca
36610 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 62  use no scratch b
36620 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77  uffer.** slots w
36630 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  ere available..*
36640 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
36650 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
36660 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74  SCRATCH_SIZE</dt
36670 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36680 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20  rameter records 
36690 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f  the largest memo
366a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
366b0 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20  quest.** handed 
366c0 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f  to [scratch memo
366d0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20  ry allocator].  
366e0 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72  Only the value r
366f0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a  eturned in the.*
36700 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61  * *pHighwater pa
36710 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
36720 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73  te3_status()] is
36730 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a   of interest.  .
36740 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69  ** The value wri
36750 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70  tten into the *p
36760 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65  Current paramete
36770 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c  r is undefined.<
36780 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
36790 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52  QLITE_STATUS_PAR
367a0 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a  SER_STACK</dt>.*
367b0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
367c0 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
367d0 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72 20   deepest parser 
367e0 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e  stack.  It is on
367f0 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c  ly.** meaningful
36800 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
36810 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 54  mpiled with [YYT
36820 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 54  RACKMAXSTACKDEPT
36830 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  H].</dd>.** </dl
36840 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74  >.**.** New stat
36850 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d 61  us parameters ma
36860 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d 20  y be added from 
36870 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f  time to time..*/
36880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36890 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53  STATUS_MEMORY_US
368a0 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  ED          0.#d
368b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
368c0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53  TUS_PAGECACHE_US
368d0 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  ED       1.#defi
368e0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ne SQLITE_STATUS
368f0 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46  _PAGECACHE_OVERF
36900 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 20  LOW   2.#define 
36910 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43  SQLITE_STATUS_SC
36920 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 20  RATCH_USED      
36930 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
36940 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
36950 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 20  CH_OVERFLOW     
36960 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
36970 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53  _STATUS_MALLOC_S
36980 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a 23  IZE          5.#
36990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
369a0 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43  ATUS_PARSER_STAC
369b0 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66  K         6.#def
369c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
369d0 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45  S_PAGECACHE_SIZE
369e0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
369f0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53   SQLITE_STATUS_S
36a00 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 20  CRATCH_SIZE     
36a10 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
36a20 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
36a30 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 75  Connection Statu
36a40 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 32  s {H17500} <S602
36a50 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
36a60 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  TAL.**.** This i
36a70 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
36a80 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e   to retrieve run
36a90 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f  time status info
36aa0 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75  rmation .** abou
36ab0 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 61  t a single [data
36ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36ad0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
36ae0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
36af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36b00 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 65  ion object to be
36b10 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
36b20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
36b30 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 61  ent.** is the pa
36b40 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 72  rameter to inter
36b50 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e 74  rogate.  Current
36b60 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c  ly, the only all
36b70 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f  owed value.** fo
36b80 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  r the second par
36b90 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 54  ameter is [SQLIT
36ba0 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41  E_DBSTATUS_LOOKA
36bb0 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41  SIDE_USED]..** A
36bc0 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e  dditional option
36bd0 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70  s will likely ap
36be0 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 72  pear in future r
36bf0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
36c00 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72  e..**.** The cur
36c10 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68  rent value of th
36c20 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72 61  e requested para
36c30 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65 6e  meter is written
36c40 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61   into *pCur.** a
36c50 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20 69  nd the highest i
36c60 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c  nstantaneous val
36c70 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ue is written in
36c80 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 0a  to *pHiwtr.  If.
36c90 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 20  ** the resetFlg 
36ca0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
36cb0 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e  e highest instan
36cc0 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73  taneous value is
36cd0 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 64  .** reset back d
36ce0 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 65  own to the curre
36cf0 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  nt value..**.** 
36d00 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
36d10 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64  e3_status()] and
36d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73   [sqlite3_stmt_s
36d30 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  tatus()]..*/.SQL
36d40 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
36d50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
36d60 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a 2c  status(sqlite3*,
36d70 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43   int op, int *pC
36d80 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 2c  ur, int *pHiwtr,
36d90 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a   int resetFlg);.
36da0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36db0 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65   Status Paramete
36dc0 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 20  rs for database 
36dd0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37  connections {H17
36de0 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a  520} <H17500>.**
36df0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
36e00 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62 73  .** Status verbs
36e10 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 62   for [sqlite3_db
36e20 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a  _status()]..**.*
36e30 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
36e40 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f  LITE_DBSTATUS_LO
36e50 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64 74  OKASIDE_USED</dt
36e60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36e70 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
36e80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f  the number of lo
36e90 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 73  okaside memory s
36ea0 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  lots currently.*
36eb0 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f  * checked out.</
36ec0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
36ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
36ee0 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44  BSTATUS_LOOKASID
36ef0 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f  E_USED     0.../
36f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
36f10 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
36f20 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 35 30  t Status {H17550
36f30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58  } <S60200>.** EX
36f40 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
36f50 20 45 61 63 68 20 70 72 65 70 61 72 65 64 20 73   Each prepared s
36f60 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69  tatement maintai
36f70 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53  ns various.** [S
36f80 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53  QLITE_STMTSTATUS
36f90 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 73  _SORT | counters
36fa0 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 74  ] that measure t
36fb0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
36fc0 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 65 72  times it has per
36fd0 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63 20  formed specific 
36fe0 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 65  operations.  The
36ff0 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a  se counters can.
37000 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 6d 6f  ** be used to mo
37010 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 6f 72  nitor the perfor
37020 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 72 69  mance characteri
37030 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 72 65  stics of the pre
37040 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
37050 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  nts.  For exampl
37060 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72  e, if the number
37070 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 73 20   of table steps 
37080 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 73 0a  greatly exceeds.
37090 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
370a0 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 73 20   table searches 
370b0 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 2c 20  or result rows, 
370c0 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e 64 20  that would tend 
370d0 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74  to indicate.** t
370e0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
370f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73   statement is us
37100 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 6c 65  ing a full table
37110 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 68 61   scan rather tha
37120 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20  n.** an index.  
37130 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
37140 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
37150 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 72 65   retrieve and re
37160 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 6c 75  set counter valu
37170 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72  es from.** a [pr
37180 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37190 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
371a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 70 72  gument is the pr
371b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
371c0 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62 65  .** object to be
371d0 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
371e0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
371f0 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ent.** is an int
37200 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 61 20  eger code for a 
37210 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45  specific [SQLITE
37220 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54  _STMTSTATUS_SORT
37230 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74   | counter].** t
37240 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65  o be interrogate
37250 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 72 65  d. .** The curre
37260 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  nt value of the 
37270 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74 65  requested counte
37280 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
37290 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 46 6c  * If the resetFl
372a0 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  g is true, then 
372b0 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20 72  the counter is r
372c0 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 74  eset to zero aft
372d0 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  er this.** inter
372e0 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72 6e  face call return
372f0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
37300 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  o: [sqlite3_stat
37310 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  us()] and [sqlit
37320 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e  e3_db_status()].
37330 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
37340 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
37350 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28  te3_stmt_status(
37360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
37370 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 46  nt op,int resetF
37380 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lg);../*.** CAPI
37390 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72  3REF: Status Par
373a0 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65 70  ameters for prep
373b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
373c0 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35 30  {H17570} <H17550
373d0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
373e0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72  L.**.** These pr
373f0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
37400 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  s define integer
37410 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d 65   codes that name
37420 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75   counter.** valu
37430 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  es associated wi
37440 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  th the [sqlite3_
37450 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 69  stmt_status()] i
37460 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
37470 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
37480 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 72   various counter
37490 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
374a0 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
374b0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53  <dt>SQLITE_STMTS
374c0 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53  TATUS_FULLSCAN_S
374d0 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEP</dt>.** <dd>
374e0 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62  This is the numb
374f0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
37500 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 70   SQLite has step
37510 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a  ped forward in.*
37520 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 72  * a table as par
37530 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c  t of a full tabl
37540 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e  e scan.  Large n
37550 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 20  umbers for this 
37560 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69  counter.** may i
37570 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e  ndicate opportun
37580 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72  ities for perfor
37590 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e  mance improvemen
375a0 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61  t through .** ca
375b0 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64  reful use of ind
375c0 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ices.</dd>.**.**
375d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54   <dt>SQLITE_STMT
375e0 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e  STATUS_SORT</dt>
375f0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20  .** <dd>This is 
37600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f  the number of so
37610 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68  rt operations th
37620 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  at have occurred
37630 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20  ..** A non-zero 
37640 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63 6f  value in this co
37650 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63 61  unter may indica
37660 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  te an opportunit
37670 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d  y to.** improvem
37680 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ent performance 
37690 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c 20  through careful 
376a0 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c  use of indices.<
376b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
376c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
376d0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55  TE_STMTSTATUS_FU
376e0 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20 20  LLSCAN_STEP     
376f0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
37700 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54  _STMTSTATUS_SORT
37710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
37720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37730 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61 63   Custom Page Cac
37740 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50  he Object.** EXP
37750 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
37760 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63  The sqlite3_pcac
37770 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 71 75  he type is opaqu
37780 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65 6d  e.  It is implem
37790 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ented by.** the 
377a0 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65  pluggable module
377b0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
377c0 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65  re has no knowle
377d0 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69  dge of.** its si
377e0 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73  ze or internal s
377f0 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65 76  tructure and nev
37800 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 74 68  er deals with th
37810 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 61  e.** sqlite3_pca
37820 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65 70  che object excep
37830 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64  t by holding and
37840 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 72   passing pointer
37850 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65  s.** to the obje
37860 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73  ct..**.** See [s
37870 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
37880 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 74  thods] for addit
37890 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
378a0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
378b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61  ruct sqlite3_pca
378c0 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63  che sqlite3_pcac
378d0 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  he;../*.** CAPI3
378e0 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e  REF: Application
378f0 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 43 61   Defined Page Ca
37900 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  che..** EXPERIME
37910 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  NTAL.**.** The [
37920 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
37930 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
37940 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74  CACHE], ...) int
37950 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65  erface can.** re
37960 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72 6e  gister an altern
37970 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65  ative page cache
37980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37990 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 6e  by passing in an
379a0 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66   .** instance of
379b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61   the sqlite3_pca
379c0 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75  che_methods stru
379d0 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72  cture. The major
379e0 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68  ity of the .** h
379f0 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 20  eap memory used 
37a00 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 73 65  by sqlite is use
37a10 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61  d by the page ca
37a20 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 61 74  che to cache dat
37a30 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c  a read .** from,
37a40 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65 20   or ready to be 
37a50 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 20  written to, the 
37a60 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 42  database file. B
37a70 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61  y implementing a
37a80 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 65   .** custom page
37a90 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 68 69   cache using thi
37aa0 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 63  s API, an applic
37ab0 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f  ation can contro
37ac0 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69  l more .** preci
37ad0 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 20  sely the amount 
37ae0 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d  of memory consum
37af0 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74 68  ed by sqlite, th
37b00 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a  e way in which .
37b10 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 69  ** said memory i
37b20 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20  s allocated and 
37b30 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68  released, and th
37b40 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20  e policies used 
37b50 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  to .** determine
37b60 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 20 70   exactly which p
37b70 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 62 61  arts of a databa
37b80 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 63 68  se file are cach
37b90 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68  ed and for .** h
37ba0 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ow long..**.** T
37bb0 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
37bc0 68 65 20 73 74 72 75 63 74 75 72 65 20 61 72 65  he structure are
37bd0 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 6e   copied to an in
37be0 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79  ternal buffer by
37bf0 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69   sqlite.** withi
37c00 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73  n the call to [s
37c10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a  qlite3_config]..
37c20 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28  **.** The xInit(
37c30 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c  ) method is call
37c40 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
37c50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37c60 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a  3_initialize()].
37c70 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79  ** (usually only
37c80 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65   once during the
37c90 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
37ca0 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73   process). It is
37cb0 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70   passed.** a cop
37cc0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
37cd0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e  _pcache_methods.
37ce0 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63  pArg value. It c
37cf0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65  an be used to se
37d00 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73  t.** up global s
37d10 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75  tructures and mu
37d20 74 65 78 65 73 20 72 65 71 75 69 72 65 64 20 62  texes required b
37d30 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67  y the custom pag
37d40 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c  e cache .** impl
37d50 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20  ementation. The 
37d60 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68  xShutdown() meth
37d70 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f  od is called fro
37d80 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71  m within .** [sq
37d90 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
37da0 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ], if the applic
37db0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68  ation invokes th
37dc0 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62  is API. It can b
37dd0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65  e used.** to cle
37de0 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74 61  an up any outsta
37df0 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20  nding resources 
37e00 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73  before process s
37e10 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75  hutdown, if requ
37e20 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
37e30 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64  xCreate() method
37e40 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   is used to cons
37e50 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68  truct a new cach
37e60 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a  e instance. The.
37e70 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ** first paramet
37e80 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 74  er, szPage, is t
37e90 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
37ea0 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 74 68   of the pages th
37eb0 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  at must.** be al
37ec0 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 63  located by the c
37ed0 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69 6c  ache. szPage wil
37ee0 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72  l not be a power
37ef0 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20   of two. The.** 
37f00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
37f10 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20   bPurgeable, is 
37f20 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68  true if the cach
37f30 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
37f40 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20  will.** be used 
37f50 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
37f60 65 20 70 61 67 65 73 20 72 65 61 64 20 66 72 6f  e pages read fro
37f70 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20  m a file stored 
37f80 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66  on disk, or.** f
37f90 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 75 73  alse if it is us
37fa0 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d  ed for an in-mem
37fb0 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 54 68  ory database. Th
37fc0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
37fd0 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e  tation.** does n
37fe0 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e  ot have to do an
37ff0 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62  ything special b
38000 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 6c 75  ased on the valu
38010 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 2c  e of bPurgeable,
38020 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c 79  .** it is purely
38030 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a   advisory. .**.*
38040 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a 65  * The xCachesize
38050 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65  () method may be
38060 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 74   called at any t
38070 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74 6f  ime by SQLite to
38080 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 67   set the.** sugg
38090 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 61  ested maximum ca
380a0 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72  che-size (number
380b0 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65 64   of pages stored
380c0 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a 2a   by) the cache.*
380d0 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73 65  * instance passe
380e0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
380f0 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 73  rgument. This is
38100 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 69   the value confi
38110 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74  gured using.** t
38120 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41 47  he SQLite "[PRAG
38130 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 20  MA cache_size]" 
38140 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 68  command. As with
38150 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65 20   the bPurgeable 
38160 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 68  parameter,.** th
38170 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38180 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64   is not required
38190 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20   to do anything 
381a0 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 68 69  special with thi
381b0 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20 69  s.** value, it i
381c0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
381d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65  .**.** The xPage
381e0 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73  count() method s
381f0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
38200 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
38210 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74   currently.** st
38220 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 63 68  ored in the cach
38230 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 61 6e  e supplied as an
38240 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a   argument..** .*
38250 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20 6d  * The xFetch() m
38260 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f  ethod is used to
38270 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61 6e   fetch a page an
38280 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
38290 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 20  er to it. .** A 
382a0 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73 20  'page', in this 
382b0 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62 75  context, is a bu
382c0 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20 62  ffer of szPage b
382d0 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74 20  ytes aligned at 
382e0 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f 75  an.** 8-byte bou
382f0 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65 20  ndary. The page 
38300 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69 73  to be fetched is
38310 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
38320 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 6d  he key. The.** m
38330 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 65  imimum key value
38340 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74 20   is 1. After it 
38350 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65 76  has been retriev
38360 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68 2c  ed using xFetch,
38370 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 73   the page .** is
38380 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
38390 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e pinned..**.** 
383a0 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  If the requested
383b0 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 64 79   page is already
383c0 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
383d0 68 65 2c 20 74 68 65 6e 20 61 20 70 6f 69 6e 74  he, then a point
383e0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 61 63  er to.** the cac
383f0 68 65 64 20 62 75 66 66 65 72 20 73 68 6f 75 6c  hed buffer shoul
38400 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 77 69  d be returned wi
38410 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 73 20  th its contents 
38420 69 6e 74 61 63 74 2e 20 49 66 20 74 68 65 0a 2a  intact. If the.*
38430 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 20 61 6c  * page is not al
38440 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 61 63  ready in the cac
38450 68 65 2c 20 74 68 65 6e 20 74 68 65 20 65 78 70  he, then the exp
38460 65 63 74 65 64 20 62 65 68 61 76 69 6f 75 72 20  ected behaviour 
38470 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 68 65 20  of the.** cache 
38480 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  is determined by
38490 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
384a0 65 20 63 72 65 61 74 65 46 6c 61 67 20 70 61 72  e createFlag par
384b0 61 6d 65 74 65 72 20 70 61 73 73 65 64 0a 2a 2a  ameter passed.**
384c0 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 63 6f   to xFetch, acco
384d0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 6f 6c  rding to the fol
384e0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a 2a 2a  lowing table:.**
384f0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
38500 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 61 6c  r=1 width=85% al
38510 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20 20  ign=center>.**  
38520 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 74 65 46   <tr><th>createF
38530 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 65 64 20  lag<th>Expected 
38540 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 20 20 3c  Behaviour.**   <
38550 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 4c 4c  tr><td>0<td>NULL
38560 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
38570 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 61 63 68  ned. No new cach
38580 65 20 65 6e 74 72 79 20 69 73 20 63 72 65 61 74  e entry is creat
38590 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64  ed..**   <tr><td
385a0 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46  >1<td>If createF
385b0 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 31 2c  lag is set to 1,
385c0 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 73 20   this indicates 
385d0 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 20 20 20  that .**        
385e0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 69          SQLite i
385f0 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e 6e 65 64  s holding pinned
38600 20 70 61 67 65 73 20 74 68 61 74 20 63 61 6e 20   pages that can 
38610 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a 20 20  be unpinned.**  
38620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 62 79                by
38630 20 77 72 69 74 69 6e 67 20 74 68 65 69 72 20 63   writing their c
38640 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 65 20 64  ontents to the d
38650 61 74 61 62 61 73 65 20 66 69 6c 65 20 28 61 0a  atabase file (a.
38660 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  **              
38670 20 20 72 65 6c 61 74 69 76 65 6c 79 20 65 78 70    relatively exp
38680 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 6f 6e  ensive operation
38690 29 2e 20 49 6e 20 74 68 69 73 20 73 69 74 75 61  ). In this situa
386a0 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  tion the.**     
386b0 20 20 20 20 20 20 20 20 20 20 20 63 61 63 68 65             cache
386c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
386d0 68 61 73 20 74 77 6f 20 63 68 6f 69 63 65 73 3a  has two choices:
386e0 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e 20 4e   it can return N
386f0 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ULL,.**         
38700 20 20 20 20 20 20 20 69 6e 20 77 68 69 63 68 20         in which 
38710 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
38720 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e 70 69   attempt to unpi
38730 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a  n one or more .*
38740 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *               
38750 20 70 61 67 65 73 20 62 65 66 6f 72 65 20 72 65   pages before re
38760 2d 72 65 71 75 65 73 74 69 6e 67 20 74 68 65 20  -requesting the 
38770 73 61 6d 65 20 70 61 67 65 2c 20 6f 72 20 69 74  same page, or it
38780 20 63 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20   can.**         
38790 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
387a0 61 20 6e 65 77 20 70 61 67 65 20 61 6e 64 20 72  a new page and r
387b0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
387c0 74 6f 20 69 74 2e 20 49 66 20 61 20 6e 65 77 0a  to it. If a new.
387d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  **              
387e0 20 20 70 61 67 65 20 69 73 20 61 6c 6c 6f 63 61    page is alloca
38