/ Hex Artifact Content
Login

Artifact e50559931ebd0c20728d765e9e31006544eb2738:


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 34 34 20 32 30 30 39 2f 30  n,v 1.444 2009/0
05f0: 34 2f 32 37 20 31 38 3a 34 36 3a 30 36 20 64 72  4/27 18:46:06 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 23 64 65  R | (17<<8)).#de
4010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4020: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4030: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4040: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4060: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4070: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4080: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4090: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
40a0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
40b0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
40c0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
40d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
40e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
40f0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
4100: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4110: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4120: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4130: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4140: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4150: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4160: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4170: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4180: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
4190: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41a0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
41c0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
41d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
41e0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
41f0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4200: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4210: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
4220: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
4230: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
4240: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
4260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4270: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
4280: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4290: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42a0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
42b0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
42c0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
42d0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
42e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
42f0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4300: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
4320: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4330: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
4340: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4350: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4360: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
4370: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4380: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4390: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
43a0: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
43b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
43c0: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
43e0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
43f0: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
4400: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4410: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4420: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4430: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4440: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4450: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4460: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4470: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
4480: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
4490: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
44a0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
44b0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
44c0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
44d0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
44e0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
44f0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4500: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4510: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4520: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4530: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4540: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4550: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4560: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4570: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4580: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
45a0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
45b0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
45c0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
45d0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
45e0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
45f0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4600: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4610: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4620: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4630: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4640: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4650: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4660: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4670: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4680: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4690: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
46a0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
46b0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
46c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
46d0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
46e0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
46f0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4700: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4710: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4720: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4730: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4740: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4750: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4760: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
4770: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4780: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4790: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
47a0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
47b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47c0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
47d0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
47e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47f0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4800: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4810: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4820: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4830: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4840: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4850: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4860: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4880: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
4890: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
48a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48b0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
48c0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
48d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48e0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
48f0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4910: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4920: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4940: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4950: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4970: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4980: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4990: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
49a0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
49b0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
49c0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
49d0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
49e0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
49f0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4a00: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4a10: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4a20: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4a30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4a40: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4a50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4a60: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4a80: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4a90: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4aa0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4ab0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4ac0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4ad0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4ae0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4af0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4b10: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4b20: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4b30: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4b40: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4b50: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4b60: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4b70: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4b80: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4b90: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4ba0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4bb0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4bc0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4bd0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4be0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4bf0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4c00: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4c10: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4c20: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4c30: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4c40: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4c50: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4c60: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4c70: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4c80: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4c90: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4ca0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4cb0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4cc0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4cd0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4ce0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4cf0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4d00: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4d10: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4d20: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4d30: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4d40: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4d50: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4d60: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4d70: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4d80: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4d90: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4da0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4db0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4dc0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4dd0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4df0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4e00: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4e10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4e20: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4e30: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4e40: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4e50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4e60: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4e70: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4e80: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4e90: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4ea0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4eb0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ec0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
4ed0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
4ee0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
4ef0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
4f00: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
4f10: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
4f20: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
4f30: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
4f40: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
4f50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
4f60: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
4f70: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
4f80: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
4f90: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
4fa0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
4fb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
4fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
4fd0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
4fe0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
4ff0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5000: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5010: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5020: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5030: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5050: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5060: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
5070: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
5080: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
5090: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
50a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
50b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
50c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
50d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
50e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
50f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5100: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5110: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5120: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5130: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5140: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5150: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5160: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
5170: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
5180: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
5190: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
51a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
51b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
51c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
51d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
51e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
51f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
5200: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
5210: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
5220: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
5230: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5240: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5250: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5260: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5270: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5280: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5290: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
52a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
52b0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
52c0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
52d0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
52e0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
52f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
5300: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5310: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
5320: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
5330: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5340: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5350: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5360: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5370: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5380: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
53a0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
53c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
53e0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
53f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5400: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5410: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5420: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5430: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5440: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5450: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5460: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5470: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5480: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5490: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
54a0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
54b0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
54c0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
54d0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
54e0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
54f0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5500: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5510: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5520: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5530: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5540: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5550: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5560: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5570: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5580: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5590: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
55a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
55b0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
55c0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
55d0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
55e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
55f0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5600: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5610: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5620: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5630: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5640: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5650: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5660: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5670: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5680: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5690: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
56a0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
56b0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
56c0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
56d0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
56e0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
56f0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5700: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5710: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5720: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5730: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5740: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5750: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5760: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5770: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5780: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5790: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
57a0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
57b0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
57c0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
57d0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
57e0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
57f0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5810: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5820: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5830: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5840: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5860: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5870: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5880: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5890: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
58a0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
58b0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
58c0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
58d0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
58e0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
58f0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5900: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5910: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5920: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5930: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5940: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
5950: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
5960: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
5970: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
5980: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
5990: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
59a0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
59b0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
59c0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
59d0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
59e0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
59f0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
5a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5a20: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5a40: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
5a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a80: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5a90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5aa0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ac0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
5ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ae0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
5af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b00: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
5b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b20: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
5b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5b40: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
5b50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5b60: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
5b70: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
5b80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b90: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
5ba0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
5bb0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
5bc0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5be0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
5bf0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
5c00: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
5c10: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
5c20: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
5c30: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
5c40: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
5c50: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
5c60: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
5c70: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5c80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5c90: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
5ca0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
5cb0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
5cc0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5cd0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5ce0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5cf0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5d00: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5d10: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5d20: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5d30: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5d40: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5d50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5d60: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
5d70: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5d80: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5d90: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5da0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5db0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
5dc0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
5dd0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5de0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
5df0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
5e00: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
5e10: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
5e20: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
5e30: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails 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 6d 69 67 68 74 20 73 65 65   reads might see
5e60: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
5e70: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
5e80: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
5e90: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
5ea0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
5eb0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
5ec0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
5ed0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5ee0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
5ef0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5f00: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
5f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
5f20: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
5f30: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
5f40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
5f50: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
5f60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
5f70: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
5f80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
5f90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
5fa0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5fb0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
5fc0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
5fd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
5fe0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
5ff0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6000: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
6010: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
6020: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
6030: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6040: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6050: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6060: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6070: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6080: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6090: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
60a0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
60b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
60c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
60d0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
60e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
60f0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
6100: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
6110: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
6120: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
6130: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
6140: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6150: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6160: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6170: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6180: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6190: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
61a0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
61b0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
61c0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
61d0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
61e0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
61f0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
6200: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
6210: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6220: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
6230: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
6240: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6250: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6260: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6270: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6280: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6290: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
62a0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
62b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
62c0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
62d0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
62e0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
62f0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
6300: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
6310: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
6320: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
6330: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
6340: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6350: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6360: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6370: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6380: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6390: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
63a0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
63b0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
63c0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
63d0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
63e0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
63f0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6400: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6410: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6420: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6430: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6440: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6450: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6460: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6470: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6480: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
64a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
64b0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
64c0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
64d0: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
64e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
64f0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6500: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6510: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6520: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6530: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6540: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6550: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6560: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6570: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6580: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6590: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
65a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
65b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
65c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
65d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
65e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
65f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6600: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6610: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6620: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6630: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6640: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6650: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6660: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6680: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6690: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
66a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
66b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
66c0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
66d0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
66e0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
66f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6700: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6710: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6720: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6730: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6740: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6750: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6760: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6770: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6780: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6790: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
67a0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
67b0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
67c0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
67d0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
67e0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
67f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6800: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6810: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6820: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6830: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6840: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6850: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6860: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6870: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6880: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6890: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
68a0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
68b0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
68c0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
68d0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
68e0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
68f0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6900: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6910: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6920: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6930: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6940: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6950: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6960: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6970: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6980: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6990: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
69a0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
69b0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
69c0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
69d0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
69e0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
69f0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6a00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6a10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6a20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6a30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6a40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6a50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6a60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6a70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6a80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6a90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
6aa0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6ab0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6ac0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
6ad0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
6ae0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
6af0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
6b00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
6b10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
6b20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
6b30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
6b40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
6b50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
6b60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
6b70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
6b80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6b90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6ba0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6bb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6bc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6bd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6be0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6bf0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6c00: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6c10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6c20: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
6c30: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
6c40: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
6c50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
6c60: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
6c70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
6c80: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6c90: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6ca0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6cb0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6cc0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6cd0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6ce0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6cf0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
6d00: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
6d10: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
6d20: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
6d30: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
6d40: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
6d50: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
6d60: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
6d70: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
6d80: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
6d90: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
6da0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
6db0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
6dc0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
6dd0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
6de0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
6df0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6e00: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6e10: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6e20: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6e30: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6e40: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
6e50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
6e60: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
6e70: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6e80: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
6e90: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
6ea0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
6eb0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
6ec0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
6ed0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
6ee0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
6ef0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
6f00: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
6f10: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
6f20: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
6f30: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
6f40: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
6f50: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
6f60: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
6f70: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
6f80: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
6f90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6fa0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
6fb0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
6fc0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6fd0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
6fe0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
6ff0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7000: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7010: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7020: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7040: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7050: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7060: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7070: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7080: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7090: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
70a0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
70b0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
70c0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
70d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
70e0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
70f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7100: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7110: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7120: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7130: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7150: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7160: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7170: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7180: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7190: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
71a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
71b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
71c0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
71d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
71e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
71f0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7210: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7220: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7230: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7240: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7250: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7260: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7270: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7280: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7290: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
72a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
72b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
72c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
72d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
72e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
72f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7300: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7310: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7320: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7330: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7340: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7350: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7360: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7370: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7380: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7390: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
73a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
73b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
73c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
73d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
73e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
73f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7400: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7410: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7420: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7430: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7440: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7450: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7460: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7470: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7480: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7490: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
74a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
74b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
74c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
74d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
74e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
74f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7500: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7510: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7520: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7530: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7540: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7550: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7560: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7570: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7580: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7590: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
75a0: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
75b0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
75c0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
75d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
75e0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
75f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
7600: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
7610: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
7620: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
7630: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
7640: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
7650: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
7660: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
7670: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
7680: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
7690: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
76a0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
76b0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
76c0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
76d0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
76e0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
76f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
7700: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
7710: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
7720: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
7730: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
7740: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
7750: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it in..**.** The
7760: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7770: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
7780: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
7790: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
77a0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
77b0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
77c0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
77d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
77e0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
77f0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
7800: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
7810: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
7820: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
7830: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
7840: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
7850: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
7860: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
7870: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
7880: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7890: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
78a0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
78b0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
78c0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
78d0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
78e0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
78f0: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
7900: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
7910: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
7920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
7930: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
7940: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
7950: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
7960: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
7970: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
7980: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
7990: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
79a0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
79b0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
79c0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
79d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
79e0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
79f0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
7a00: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
7a10: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
7a20: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
7a30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
7a40: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
7a50: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
7a60: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
7a70: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
7a80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
7a90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
7aa0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
7ab0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
7ac0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
7ad0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
7ae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
7af0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
7b00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
7b10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
7b20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
7b30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
7b40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
7b50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
7b60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
7b70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
7b80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
7b90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
7ba0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
7bb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
7bc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
7bd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
7be0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
7bf0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
7c00: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
7c10: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
7c20: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
7c30: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
7c40: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
7c50: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65  time..**.*/.type
7c60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7c70: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
7c80: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  fs;.struct sqlit
7c90: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
7ca0: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
7cb0: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
7cc0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
7cd0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
7ce0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
7cf0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
7d00: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
7d10: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
7d20: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
7d30: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
7d40: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
7d50: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
7d60: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
7d70: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
7d80: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
7d90: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
7da0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
7db0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
7dc0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
7dd0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
7de0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
7df0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
7e00: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
7e10: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
7e20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
7e30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
7e40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
7e60: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
7e70: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
7e80: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
7e90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ea0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
7eb0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
7ec0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
7ed0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ee0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
7ef0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
7f00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
7f10: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
7f20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7f30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7f40: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7f50: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
7f60: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
7f70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
7f80: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
7f90: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7fb0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7fc0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
7fd0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
7fe0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
7ff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
8000: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
8010: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8020: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8030: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8040: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
8050: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
8060: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
8070: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
8080: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8090: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
80a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
80b0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
80c0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
80d0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
80e0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
80f0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
8100: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
8110: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
8120: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
8130: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
8140: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
8150: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
8160: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
8170: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
8180: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
8190: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
81a0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48  ss VFS method {H
81b0: 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a  11190} <H11140>.
81c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
81d0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
81e0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
81f0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
8200: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
8210: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
8220: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
8230: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
8240: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
8250: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
8260: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
8270: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
8280: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
8290: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
82a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
82b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
82c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
82d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
82e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
82f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8300: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
8310: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
8320: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8330: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
8340: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8350: 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  le..** With SQLI
8360: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
8370: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8380: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
8390: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
83a0: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64   readable..*/.#d
83b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
83c0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
83d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
83e0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
83f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
8400: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
8410: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    2../*.** CAPI3
8420: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
8430: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
8440: 72 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30  ry {H10130} <S20
8450: 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  000><S30100>.**.
8460: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
8470: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
8480: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
8490: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
84a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
84b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
84c0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
84d0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
84e0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
84f0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
8500: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8510: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8530: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
8540: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
8550: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
8560: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8570: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
8580: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
8590: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
85a0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
85b0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
85c0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
85d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
85e0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
85f0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
8600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8610: 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66  n().  Only an ef
8620: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
8630: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
8640: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
8650: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
8660: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
8670: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
8680: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
8690: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
86a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
86b0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
86c0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
86d0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
86e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
86f0: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
8700: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
8710: 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a  ialize().  Only.
8720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
8730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
8750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
8760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
8770: 65 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  er calls to sqli
8780: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
8790: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
87a0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ps..**.** Among 
87b0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71  other things, sq
87c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
87d0: 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a  () shall invoke.
87e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
87f0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
8800: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
8810: 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e  wn().** shall in
8820: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
8830: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  end()..**.** The
8840: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8850: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
8860: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
8870: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
8880: 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61   If for some rea
8890: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
88a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
88b0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
88c0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
88d0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
88e0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
88f0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
8900: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
8910: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
8920: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
8930: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
8940: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
8950: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
8960: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
8970: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
8980: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
8990: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
89a0: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
89b0: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
89c0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
89d0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
89e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
89f0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
8a00: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
8a10: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
8a20: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
8a30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8a40: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
8a50: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
8a60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
8a70: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
8a80: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8a90: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
8aa0: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
8ab0: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
8ac0: 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69  ady.  However, i
8ad0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
8ae0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
8af0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
8b00: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
8b10: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
8b20: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
8b30: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
8b40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
8b50: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
8b60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8b70: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
8b80: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8b90: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
8ba0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
8bb0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
8bc0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
8bd0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
8be0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
8bf0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
8c00: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
8c10: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
8c20: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
8c30: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
8c40: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
8c50: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
8c60: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
8c70: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
8c80: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
8c90: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
8ca0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
8cb0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
8cc0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
8cd0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
8ce0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
8cf0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
8d00: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
8d10: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
8d20: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
8d30: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
8d40: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
8d50: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
8d60: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
8d70: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
8d80: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
8d90: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
8da0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
8db0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
8dc0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
8dd0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
8de0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
8df0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
8e00: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
8e10: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
8e20: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
8e30: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
8e40: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
8e50: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
8e60: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
8e70: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
8e80: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
8e90: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
8ea0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
8eb0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
8ec0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
8ed0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
8ee0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
8ef0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8f00: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
8f10: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
8f20: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
8f30: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
8f40: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
8f50: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8f60: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
8f70: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
8f80: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
8f90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8fa0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
8fb0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
8fc0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
8fd0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
8fe0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
8ff0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
9000: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
9010: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
9020: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9030: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
9040: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9050: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
9060: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
9070: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
9080: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
9090: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
90a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69 78  ompiled for unix
90b0: 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73  , windows, or os
90c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c  /2..** When buil
90d0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
90e0: 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68 65  forms (using the
90f0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
9100: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
9110: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
9120: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
9130: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
9140: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
9150: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
9160: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
9170: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9180: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
9190: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
91a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
91b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
91c0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
91d0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
91e0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
91f0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
9200: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
9210: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
9220: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
9230: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9240: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
9250: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
9260: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
9270: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
9280: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9290: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
92a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
92b0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
92c0: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31  te Library {H141
92d0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30  00} <S20000><S30
92e0: 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
92f0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
9300: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9310: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
9320: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
9330: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
9340: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
9350: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
9360: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
9370: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
9380: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
9390: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
93a0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
93b0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
93c0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
93d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
93e0: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
93f0: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
9400: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
9410: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
9420: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
9430: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
9440: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
9450: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9460: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9470: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
9480: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
9490: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
94a0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
94b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
94c0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
94d0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
94e0: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
94f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
9500: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
9510: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
9520: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
9530: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
9540: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
9550: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
9560: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
9570: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
9580: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
9590: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
95a0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74  tdown()]..** Not
95b0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
95c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
95d0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
95e0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
95f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9600: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
9610: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
9620: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
9630: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
9640: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
9650: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
9660: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
9670: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
9680: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
9690: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
96a0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
96b0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
96c0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
96d0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
96e0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
96f0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
9700: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
9710: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
9720: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
9730: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
9740: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
9750: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
9760: 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66  *.** When a conf
9770: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
9780: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
9790: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
97a0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
97b0: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20  * If the option 
97c0: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
97d0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
97e0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
97f0: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
9800: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
9810: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
9820: 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  code]..**.** Req
9830: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
9840: 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20  14103] [H14106] 
9850: 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33  [H14120] [H14123
9860: 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31  ] [H14126] [H141
9870: 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31  29] [H14132] [H1
9880: 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38  4135].** [H14138
9890: 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31  ] [H14141] [H141
98a0: 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31  44] [H14147] [H1
98b0: 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b  4150] [H14153] [
98c0: 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d  H14156] [H14159]
98d0: 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31  .** [H14162] [H1
98e0: 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a  4165] [H14168].*
98f0: 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
9900: 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
9910: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
9920: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
9930: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
9940: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9950: 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c 53  ons  {H14200} <S
9960: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
9970: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
9980: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
9990: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
99a0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
99b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
99c0: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
99d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99e0: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
99f0: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
9a00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
9a10: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
9a20: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
9a30: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
9a40: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
9a50: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
9a60: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
9a70: 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68  t argument).  Th
9a80: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f  e.** sqlite3_db_
9a90: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9aa0: 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  ce can only be u
9ab0: 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  sed immediately 
9ac0: 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74  after.** the dat
9ad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9ae0: 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
9af0: 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
9b00: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
9b10: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
9b20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
9b30: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].  .**.** The s
9b40: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
9b50: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
9b60: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
9b70: 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72   the.** configur
9b80: 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20  ation verb - an 
9b90: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
9ba0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
9bb0: 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68  .** aspect of th
9bc0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
9bd0: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
9be0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
9bf0: 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20  The only choice 
9c00: 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69  for this value i
9c10: 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  s [SQLITE_DBCONF
9c20: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a  IG_LOOKASIDE]..*
9c30: 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20  * New verbs are 
9c40: 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64  likely to be add
9c50: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9c60: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
9c70: 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61  .** Additional a
9c80: 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20  rguments depend 
9c90: 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a  on the verb..**.
9ca0: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
9cb0: 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 31  .** [H14203] [H1
9cc0: 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b  4206] [H14209] [
9cd0: 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 5d  H14212] [H14215]
9ce0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
9cf0: 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
9d00: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
9d10: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
9d20: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
9d30: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
9d40: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
9d50: 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31  s {H10155} <S201
9d60: 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  20>.** EXPERIMEN
9d70: 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  TAL.**.** An ins
9d80: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
9d90: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
9da0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
9db0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
9dc0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
9dd0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
9de0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
9df0: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
9e00: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
9e10: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
9e20: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
9e30: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9e40: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9e50: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
9e60: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
9e70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
9e80: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
9e90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
9ea0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
9eb0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20  IG_MALLOC].  By 
9ec0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
9ed0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
9ee0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
9ef0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
9f00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69  3_config()] duri
9f10: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
9f20: 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  , an.** applicat
9f30: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
9f40: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  an alternative m
9f50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
9f60: 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f   subsystem.** fo
9f70: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
9f80: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
9f90: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
9fa0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
9fb0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
9fc0: 73 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69  s with a built-i
9fd0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
9fe0: 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65  or that is.** pe
9ff0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
a000: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
a010: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
a020: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
a030: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
a040: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
a050: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
a060: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
a070: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
a080: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
a090: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
a0a0: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
a0b0: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
a0c0: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
a0d0: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
a0e0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
a0f0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
a100: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
a110: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
a120: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
a130: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
a140: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
a150: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
a160: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
a170: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
a180: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
a190: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
a1a0: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65  e xMalloc, xFree
a1b0: 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d  , and xRealloc m
a1c0: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
a1d0: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
a1e0: 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61  loc(), free(), a
a1f0: 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e  nd realloc() fun
a200: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
a210: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
a220: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
a230: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
a240: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a250: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
a260: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
a270: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
a280: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
a290: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
a2a0: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
a2b0: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
a2c0: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
a2d0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
a2e0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
a2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
a300: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
a310: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
a320: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
a330: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
a340: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
a350: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
a360: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
a370: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
a380: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
a390: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
a3a0: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
a3b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
a3c0: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
a3d0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
a3e0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
a3f0: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
a400: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
a410: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
a420: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
a430: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
a440: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
a450: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
a460: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
a470: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
a480: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
a490: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
a4a0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
a4b0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
a4c0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
a4d0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
a4e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
a4f0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
a500: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
a510: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
a520: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
a530: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
a540: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
a550: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
a560: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
a570: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
a580: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a590: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a5a0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
a5b0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
a5c0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a5d0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
a5e0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
a5f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
a600: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
a610: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
a620: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
a630: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
a640: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
a650: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
a660: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
a670: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
a680: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
a690: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
a6a0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
a6b0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
a6c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
a6d0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
a6e0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
a6f0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
a700: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
a710: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
a720: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
a730: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
a740: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
a750: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
a760: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a770: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
a780: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
a790: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
a7a0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
a7b0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
a7c0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
a7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
a7e0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
a7f0: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
a800: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
a810: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
a820: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
a830: 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30  s {H10160} <S200
a840: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
a850: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
a860: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
a870: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
a880: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
a890: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
a8a0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
a8b0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
a8c0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
a8d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
a8e0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
a8f0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
a900: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
a910: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
a920: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
a930: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
a940: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
a950: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
a960: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
a970: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
a980: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
a990: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
a9a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
a9b0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
a9c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
a9d0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
a9e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a9f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
aa00: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
aa10: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
aa20: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
aa30: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
aa40: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
aa50: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
aa60: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
aa70: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
aa80: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
aa90: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
aaa0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
aab0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
aac0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
aad0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
aae0: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
aaf0: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
ab00: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
ab10: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
ab20: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
ab30: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e  gle thread.</dd>
ab40: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ab50: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
ab60: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
ab70: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
ab80: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ab90: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
aba0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
abb0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
abc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
abd0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
abe0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
abf0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
ac00: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
ac10: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
ac20: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
ac30: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
ac40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
ac50: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ac60: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
ac70: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
ac80: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
ac90: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
aca0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
acb0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
acc0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
acd0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
ace0: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
acf0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
ad00: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
ad10: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
ad20: 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20  same time.  See 
ad30: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
ad40: 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74  ode].** document
ad50: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
ad60: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
ad70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ad80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ad90: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
ada0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
adb0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
adc0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
add0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
ade0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
adf0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ae00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ae10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ae20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ae30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ae40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ae50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ae60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ae70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ae80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ae90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
aea0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
aeb0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
aec0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
aed0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
aee0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
aef0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
af00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
af10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
af20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
af30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
af40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
af50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
af60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
af70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
af80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
af90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
afa0: 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68   time..** See th
afb0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
afc0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
afd0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
afe0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
aff0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b000: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
b010: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b020: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
b030: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b040: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
b050: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
b060: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
b070: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b080: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
b090: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
b0a0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
b0b0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
b0c0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b0d0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
b0e0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
b0f0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
b100: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b110: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
b120: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
b130: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b140: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
b150: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b160: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
b170: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
b180: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
b190: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
b1a0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
b1b0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
b1c0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
b1d0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b1e0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
b1f0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
b200: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
b210: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
b220: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
b230: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
b240: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
b250: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
b260: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
b270: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
b280: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
b290: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
b2a0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
b2b0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
b2c0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
b2d0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
b2e0: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
b2f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b300: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
b310: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b320: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
b330: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
b340: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
b350: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
b360: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
b370: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
b380: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
b390: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
b3a0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
b3b0: 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65  cs. When disable
b3c0: 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
b3d0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
b3e0: 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f  es become .** no
b3f0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
b400: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
b410: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
b420: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
b430: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
b440: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
b450: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
b460: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
b470: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  imit()].**   <li
b480: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
b490: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a  s()].**   </ul>.
b4a0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
b4b0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b4c0: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
b4d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b4e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
b4f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
b500: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
b510: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
b520: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
b530: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
b540: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
b550: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
b560: 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  y, the.** size o
b570: 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62  f each scratch b
b580: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
b590: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75  the number of bu
b5a0: 66 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20  ffers (N).  The 
b5b0: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
b5c0: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
b5d0: 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20  e of 16. The sz 
b5e0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b5f0: 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a   be a few bytes.
b600: 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  ** larger than t
b610: 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63  he actual scratc
b620: 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  h space required
b630: 20 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76   due internal ov
b640: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
b650: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
b660: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
b670: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
b680: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
b690: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
b6a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
b6b0: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
b6c0: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
b6d0: 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20  fer at once per 
b6e0: 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20  thread, so.** N 
b6f0: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
b700: 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
b710: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b720: 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a  threads.  The sz
b730: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68  .** parameter sh
b740: 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20  ould be 6 times 
b750: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b760: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
b770: 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53   page size..** S
b780: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61  cratch buffers a
b790: 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20  re used as part 
b7a0: 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c  of the btree bal
b7b0: 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  ance operation. 
b7c0: 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65   If.** The btree
b7d0: 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20   balancer needs 
b7e0: 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  additional memor
b7f0: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
b800: 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20   provided by.** 
b810: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
b820: 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68  or if no scratch
b830: 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73   buffer space is
b840: 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
b850: 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20   SQLite.** goes 
b860: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
b870: 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20  oc()] to obtain 
b880: 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65  the memory it ne
b890: 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  eds.</dd>.**.** 
b8a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
b8b0: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
b8c0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
b8d0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
b8e0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
b8f0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
b900: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
b910: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
b920: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
b930: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
b940: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
b950: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
b960: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
b970: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
b980: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
b990: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
b9a0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
b9b0: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
b9c0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
b9d0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
b9e0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
b9f0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
ba00: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
ba10: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  : A pointer to t
ba20: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  he.** memory, th
ba30: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
ba40: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
ba50: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
ba60: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
ba70: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
ba80: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72   must be a power
ba90: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
baa0: 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20  512 and 32768.  
bab0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
bac0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
bad0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
bae0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
baf0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
bb00: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
bb10: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
bb20: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
bb30: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
bb40: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
bb50: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
bb60: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
bb70: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
bb80: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
bb90: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
bba0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
bbb0: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
bbc0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
bbd0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
bbe0: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
bbf0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
bc00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
bc10: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
bc20: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
bc30: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
bc40: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65  tation might use
bc50: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
bc60: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f  the N buffers to
bc70: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79   hold .** memory
bc80: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f   accounting info
bc90: 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a  rmation. </dd>.*
bca0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
bcb0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
bcc0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bcd0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
bce0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
bcf0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
bd00: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
bd10: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
bd20: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
bd30: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
bd40: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
bd50: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
bd60: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
bd70: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
bd80: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
bd90: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
bda0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
bdb0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
bdc0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75  e memory, the nu
bdd0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
bde0: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
bdf0: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
be00: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
be10: 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74  n size.  If.** t
be20: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
be30: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
be40: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
be50: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
be60: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
be70: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
be80: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
be90: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
bea0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
beb0: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
bec0: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
bed0: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
bee0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66  FIG_MALLOC].  If
bef0: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
bf00: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
bf10: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
bf20: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
bf30: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
bf40: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
bf50: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
bf60: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
bf70: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
bf80: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
bf90: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
bfa0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
bfb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bfc0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
bfd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
bfe0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
bff0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c000: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c010: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c020: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c030: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
c040: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
c050: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
c060: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
c070: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
c080: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
c090: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
c0a0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c0b0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
c0c0: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
c0d0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
c0e0: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
c0f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c100: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
c110: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c120: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c130: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c140: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c150: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c160: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c170: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
c180: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
c190: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
c1a0: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
c1b0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c1c0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c1d0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
c1e0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  ex routines..** 
c1f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
c200: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
c210: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
c220: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
c230: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
c240: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
c250: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
c260: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
c270: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
c280: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
c290: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c2a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c2b0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
c2c0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DE</dt>.** <dd>T
c2d0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c2e0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
c2f0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
c300: 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
c310: 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f  ory allcation lo
c320: 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61  okaside optimiza
c330: 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74  tion.  The first
c340: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
c350: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
c360: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
c370: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
c380: 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
c390: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
c3a0: 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
c3b0: 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
c3c0: 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
c3d0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c3e0: 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a  FIG_PCACHE</dt>.
c3f0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c400: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
c410: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
c420: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
c430: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
c440: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
c450: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
c460: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
c470: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
c480: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
c490: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
c4a0: 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d  ation.  SQLite m
c4b0: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
c4c0: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
c4d0: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
c4e0: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
c4f0: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
c500: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c510: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
c520: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
c530: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c540: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c550: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c560: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
c570: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
c580: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
c590: 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
c5a0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
c5b0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
c5c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
c5d0: 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  that object.</dd
c5e0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
c5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c600: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c610: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
c620: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c630: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
c640: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
c650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c660: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
c670: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
c680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c690: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
c6a0: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
c6b0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c6c0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
c6d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c6e0: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
c6f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c700: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
c720: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
c730: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
c740: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
c750: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c760: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
c770: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
c780: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
c790: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c7a0: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
c7b0: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
c7c0: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
c7d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c7e0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c7f0: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
c800: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
c810: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
c820: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
c830: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
c840: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c850: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c860: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
c870: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
c880: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c890: 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
c8a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
c8b0: 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
c8c0: 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
c8d0: 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
c8e0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
c8f0: 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
c900: 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
c910: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
c920: 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
c930: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
c940: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c960: 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
c970: 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
c980: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
c990: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
c9a0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
c9b0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
c9c0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
c9d0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
c9e0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
c9f0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
ca00: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
ca10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ca20: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ca30: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
ca40: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ca50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
ca60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ca70: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
ca80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca90: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
caa0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
cab0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
cac0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
cad0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cae0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
caf0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
cb00: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
cb10: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
cb20: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
cb30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cb40: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
cb50: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
cb60: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
cb70: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cb80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
cb90: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
cba0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
cbb0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
cbc0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
cbd0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
cbe0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
cbf0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
cc00: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
cc10: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
cc20: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
cc30: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
cc40: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
cc50: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
cc60: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
cc70: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
cc80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
cc90: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
cca0: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
ccb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
ccc0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
ccd0: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
cce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
ccf0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cd00: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
cd10: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
cd20: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
cd30: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
cd40: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
cd50: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
cd60: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
cd70: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
cd80: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
cd90: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
cda0: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
cdb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cdc0: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
cdd0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
cde0: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
cdf0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
ce00: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
ce10: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
ce20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ce30: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
ce40: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
ce50: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ce60: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
ce70: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
ce80: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
ce90: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
cea0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
ceb0: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
cec0: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
ced0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
cee0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
cef0: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
cf00: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
cf10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
cf20: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
cf30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
cf40: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
cf50: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
cf60: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
cf70: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
cf80: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
cf90: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
cfa0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
cfb0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
cfc0: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
cfd0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
cfe0: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
cff0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
d000: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
d010: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
d020: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
d030: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
d040: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d  nts:.** [H12201]
d050: 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74   [H12202].*/.int
d060: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
d070: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
d080: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
d090: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
d0a0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
d0b0: 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d  t Rowid {H12220}
d0c0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
d0d0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
d0e0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
d0f0: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
d100: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
d110: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
d120: 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
d130: 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20  id"]. The rowid 
d140: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
d150: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
d160: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
d170: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
d180: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
d190: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
d1a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
d1b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
d1c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
d1d0: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68  olumns. If.** th
d1e0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
d1f0: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
d200: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
d210: 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
d220: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
d230: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
d240: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
d250: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
d260: 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
d270: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
d280: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
d290: 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
d2a0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
d2b0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
d2c0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
d2d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d2e0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
d2f0: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
d300: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
d310: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
d320: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d330: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
d340: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
d350: 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
d360: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
d370: 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
d380: 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
d390: 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
d3a0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
d3b0: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
d3c0: 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
d3d0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
d3e0: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
d3f0: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
d400: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d410: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
d420: 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
d430: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
d440: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
d450: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
d460: 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54  **.** An [INSERT
d470: 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
d480: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
d490: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
d4a0: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
d4b0: 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
d4c0: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
d4d0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d4e0: 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
d4f0: 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45  tine.  Thus INSE
d500: 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
d510: 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
d520: 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
d530: 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
d540: 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
d550: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
d560: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
d570: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
d580: 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
d590: 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65  tion fails.  Whe
d5a0: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
d5b0: 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
d5c0: 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
d5d0: 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
d5e0: 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
d5f0: 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
d600: 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
d610: 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
d620: 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
d630: 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
d640: 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
d650: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
d660: 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
d670: 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
d680: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
d690: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
d6a0: 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
d6b0: 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
d6c0: 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
d6d0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
d6e0: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
d6f0: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
d700: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
d710: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
d720: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
d730: 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 32 32 32   [H12221] [H1222
d740: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
d750: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
d760: 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
d770: 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
d780: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
d790: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
d7a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
d7b0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d7c0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
d7d0: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
d7e0: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
d7f0: 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
d800: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
d810: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
d820: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
d830: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
d840: 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
d850: 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
d860: 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
d870: 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
d880: 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
d890: 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
d8a0: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
d8b0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
d8c0: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
d8d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d8e0: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
d8f0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
d900: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
d910: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
d920: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
d930: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
d940: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
d950: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
d960: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
d970: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
d980: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
d990: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
d9a0: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
d9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d9c0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
d9d0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
d9e0: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
d9f0: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
da00: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
da10: 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
da20: 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
da30: 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
da40: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
da50: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
da60: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
da70: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
da80: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
da90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
daa0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
dab0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
dac0: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
dad0: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
dae0: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
daf0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
db00: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
db10: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
db20: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
db30: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
db40: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
db50: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
db60: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
db70: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
db80: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
db90: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
dba0: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
dbb0: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
dbc0: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
dbd0: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
dbe0: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
dbf0: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
dc00: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
dc10: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
dc20: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
dc30: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
dc40: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
dc50: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
dc60: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
dc70: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
dc80: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
dc90: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
dca0: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
dcb0: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
dcc0: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
dcd0: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
dce0: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
dcf0: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
dd00: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
dd10: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
dd20: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
dd30: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
dd40: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
dd50: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
dd60: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
dd70: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
dd80: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
dd90: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
dda0: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
ddb0: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
ddc0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
ddd0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
dde0: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
ddf0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
de00: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
de10: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
de20: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
de30: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
de40: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
de50: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
de60: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
de70: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
de80: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
de90: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
dea0: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
deb0: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
dec0: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
ded0: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
dee0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
def0: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
df00: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
df10: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
df20: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
df30: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
df40: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
df50: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
df60: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
df70: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
df80: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
df90: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
dfa0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
dfb0: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
dfc0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
dfd0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
dfe0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
dff0: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
e000: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
e010: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
e020: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
e030: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
e040: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
e050: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
e060: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
e070: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
e080: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
e090: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
e0a0: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
e0b0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
e0c0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
e0d0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
e0e0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
e0f0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
e100: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
e110: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
e120: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
e130: 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d 75 63   Doing so is muc
e140: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
e150: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
e160: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
e170: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
e180: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 20  from the table. 
e190: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
e1a0: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
e1b0: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
e1c0: 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
e1d0: 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
e1e0: 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
e1f0: 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
e200: 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
e210: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
e220: 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
e230: 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
e240: 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
e250: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
e260: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
e270: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
e280: 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
e290: 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
e2a0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
e2b0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
e2c0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
e2d0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
e2e0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
e2f0: 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 72 65   instead.  Or re
e300: 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68  compile using th
e310: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  e.** [SQLITE_OMI
e320: 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d  T_TRUNCATE_OPTIM
e330: 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65  IZATION] compile
e340: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20  -time option to 
e350: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f  disable the.** o
e360: 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61  ptimization on a
e370: 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  ll queries..**.*
e380: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
e390: 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48 31 32  ** [H12241] [H12
e3a0: 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  243].**.** If a 
e3b0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
e3c0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
e3d0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
e3e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
e3f0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
e400: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
e410: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
e420: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
e430: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
e440: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
e450: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
e460: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
e470: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
e480: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
e490: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
e4a0: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20  dified {H12260} 
e4b0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
e4c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
e4d0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
e4e0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
e4f0: 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
e500: 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45  .** UPDATE or DE
e510: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
e520: 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
e530: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e540: 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54  was opened..** T
e550: 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65  he count include
e560: 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72  s all changes fr
e570: 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63  om all trigger c
e580: 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65  ontexts.  Howeve
e590: 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
e5a0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
e5b0: 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
e5c0: 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41   implement REPLA
e5d0: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  CE constraints,.
e5e0: 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
e5f0: 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
e600: 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62  ing, or DROP tab
e610: 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a  le processing..*
e620: 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72  * The changes ar
e630: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
e640: 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  n as the stateme
e650: 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
e660: 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  em is.** complet
e670: 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
e680: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
e690: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
e6a0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
e6b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
e6c0: 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
e6d0: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
e6e0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
e6f0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
e700: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
e710: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
e720: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
e730: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
e740: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
e750: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
e760: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
e770: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
e780: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
e790: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
e7a0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
e7b0: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
e7c0: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
e7d0: 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
e7e0: 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
e7f0: 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
e800: 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
e810: 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
e820: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
e830: 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
e840: 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
e850: 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
e860: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
e870: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
e880: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
e890: 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
e8a0: 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
e8b0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
e8c0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
e8d0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
e8e0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
e8f0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
e900: 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72 20 72   instead.   Or r
e910: 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74  ecompile using t
e920: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  he.** [SQLITE_OM
e930: 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49  IT_TRUNCATE_OPTI
e940: 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c  MIZATION] compil
e950: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f  e-time option to
e960: 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
e970: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20  optimization on 
e980: 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  all queries..**.
e990: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
e9a0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
e9b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
e9c0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
e9d0: 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20 5b  s:.** [H12261] [
e9e0: 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12263].**.** If
e9f0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
ea00: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
ea10: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
ea20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ea30: 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
ea40: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
ea50: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
ea60: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
ea70: 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
ea80: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
ea90: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
eaa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
eab0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
eac0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
ead0: 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
eae0: 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
eaf0: 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20   Query {H12270} 
eb00: 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30500>.**.** T
eb10: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
eb20: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
eb30: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
eb40: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
eb50: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
eb60: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
eb70: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
eb80: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
eb90: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
eba0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
ebb0: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
ebc0: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
ebd0: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
ebe0: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
ebf0: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
ec00: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
ec10: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
ec20: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
ec30: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
ec40: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
ec50: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
ec60: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
ec70: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
ec80: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
ec90: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
eca0: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
ecb0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
ecc0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
ecd0: 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
ece0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
ecf0: 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
ed00: 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
ed10: 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
ed20: 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
ed30: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ns..**.** If an 
ed40: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
ed50: 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
ed60: 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
ed70: 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
ed80: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
ed90: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
eda0: 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
edb0: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
edc0: 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
edd0: 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
ede0: 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
edf0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53  tion..**.** An S
ee00: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
ee10: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
ee20: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
ee30: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
ee40: 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72  .** If the inter
ee50: 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
ee60: 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
ee70: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
ee80: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
ee90: 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
eea0: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
eeb0: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
eec0: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
eed0: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
eee0: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
eef0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
ef00: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
ef10: 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
ef20: 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
ef30: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
ef40: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
ef50: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
ef60: 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
ef70: 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77 20 53  lete.  Any new S
ef80: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
ef90: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
efa0: 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
efb0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
efc0: 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
efd0: 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
efe0: 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
eff0: 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
f000: 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
f010: 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
f020: 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
f030: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
f040: 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 4e  rrupt() call.  N
f050: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
f060: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
f070: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
f080: 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
f090: 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
f0a0: 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
f0b0: 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
f0c0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f0d0: 74 28 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  t()..** A call t
f0e0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
f0f0: 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
f100: 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
f110: 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
f120: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
f130: 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
f140: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
f150: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
f160: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
f170: 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
f180: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
f190: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
f1a0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
f1b0: 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b 48  :.** [H12271] [H
f1c0: 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  12272].**.** If 
f1d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
f1e0: 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
f1f0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
f200: 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
f210: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
f220: 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
f230: 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
f240: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
f250: 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
f260: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f270: 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
f280: 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
f290: 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31   Is Complete {H1
f2a0: 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a  0510} <S70200>.*
f2b0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
f2c0: 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66  nes are useful f
f2d0: 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  or command-line 
f2e0: 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
f2f0: 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
f300: 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
f310: 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
f320: 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c  m complete a SQL
f330: 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
f340: 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
f350: 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
f360: 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
f370: 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
f380: 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
f390: 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  g.  These routin
f3a0: 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  es return true i
f3b0: 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
f3c0: 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
f3d0: 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
f3e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41  QL statement.  A
f3f0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
f400: 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
f410: 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
f420: 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
f430: 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
f440: 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f  not a fragment o
f450: 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52  f a.** CREATE TR
f460: 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
f470: 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61    Semicolons tha
f480: 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
f490: 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
f4a0: 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
f4b0: 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
f4c0: 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
f4d0: 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
f4e0: 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
f4f0: 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
f500: 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
f510: 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
f520: 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
f530: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
f540: 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
f550: 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
f560: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
f570: 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
f580: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
f590: 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
f5a0: 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
f5b0: 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
f5c0: 51 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  QL..**.** Requir
f5d0: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 5d  ements: [H10511]
f5e0: 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a 20   [H10512].**.** 
f5f0: 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
f600: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
f610: 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
f620: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
f630: 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
f640: 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
f650: 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
f660: 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
f670: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
f680: 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
f690: 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
f6a0: 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
f6b0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
f6c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
f6d0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
f6e0: 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
f6f0: 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
f700: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
f710: 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
f720: 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
f730: 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31  _BUSY Errors {H1
f740: 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a  2310} <S40400>.*
f750: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
f760: 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
f770: 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
f780: 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
f790: 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
f7a0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
f7b0: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
f7c0: 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
f7d0: 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
f7e0: 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
f7f0: 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ocked..**.** If 
f800: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
f810: 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
f820: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
f830: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
f840: 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
f850: 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
f860: 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
f870: 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49  ring the lock. I
f880: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
f890: 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
f8a0: 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
f8b0: 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e  lback will be in
f8c0: 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
f8d0: 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
f8e0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f8f0: 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65  nt to the handle
f900: 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
f910: 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
f920: 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
f930: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
f940: 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
f950: 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20  handler().  The 
f960: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
f970: 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  to.** the handle
f980: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
f990: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
f9a0: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
f9b0: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
f9c0: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
f9d0: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
f9e0: 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62  nt.  If the.** b
f9f0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
fa00: 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
fa10: 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
fa20: 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
fa30: 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
fa40: 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
fa50: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
fa60: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
fa70: 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
fa80: 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
fa90: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
faa0: 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
fab0: 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
fac0: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
fad0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
fae0: 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
faf0: 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
fb00: 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
fb10: 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
fb20: 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
fb30: 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
fb40: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
fb50: 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
fb60: 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49  ck contention. I
fb70: 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
fb80: 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
fb90: 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
fba0: 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
fbb0: 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
fbc0: 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
fbd0: 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
fbe0: 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
fbf0: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
fc00: 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
fc10: 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
fc20: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
fc30: 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
fc40: 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
fc50: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
fc60: 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
fc70: 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
fc80: 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
fc90: 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
fca0: 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
fcb0: 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
fcc0: 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
fcd0: 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
fce0: 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
fcf0: 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
fd00: 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
fd10: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
fd20: 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
fd30: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
fd40: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
fd50: 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
fd60: 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
fd70: 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
fd80: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
fd90: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
fda0: 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
fdb0: 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
fdc0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
fdd0: 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
fde0: 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
fdf0: 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
fe00: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
fe10: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
fe20: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
fe30: 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
fe40: 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
fe50: 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
fe60: 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
fe70: 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
fe80: 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
fe90: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
fea0: 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
feb0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
fec0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
fed0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  LL..**.** The [S
fee0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
fef0: 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
ff00: 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
ff10: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
ff20: 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
ff30: 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
ff40: 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
ff50: 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
ff60: 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
ff70: 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
ff80: 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
ff90: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
ffa0: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
ffb0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
ffc0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ffd0: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
ffe0: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
fff0: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
10000 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
10010 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
10020 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
10030 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
10040 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
10050 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
10060 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73  aders.  If it is
10070 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
10080 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
10090 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
100a0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
100b0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
100c0 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
100d0 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
100e0 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
100f0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
10100 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
10110 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
10120 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
10130 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
10140 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73  _BLOCKED].  This
10150 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
10160 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
10170 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
10180 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
10190 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
101a0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
101b0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
101c0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
101d0 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
101e0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
101f0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
10200 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
10210 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
10220 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
10230 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  tant..**.** Ther
10240 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
10250 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
10260 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
10270 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
10280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
10290 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
102a0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
102b0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
102c0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
102d0 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c    Note that call
102e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
102f0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
10300 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
10310 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
10320 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
10330 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
10340 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
10350 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
10360 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
10370 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10380 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
10390 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
103a0 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
103b0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
103c0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
103d0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52 65  avior..** .** Re
103e0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
103f0 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32 5d  H12311] [H12312]
10400 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33 31   [H12314] [H1231
10410 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a 2a  6] [H12318].**.*
10420 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
10430 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
10440 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
10450 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
10460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10470 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
10480 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
10490 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
104a0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
104b0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
104c0 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
104d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
104e0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
104f0 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20  imeout {H12340} 
10500 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40410>.**.** T
10510 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
10520 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
10530 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
10540 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
10550 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
10560 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
10570 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
10580 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
10590 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
105a0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
105b0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
105c0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
105d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
105e0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
105f0 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33  cumulated. {H123
10600 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d  43} After "ms" m
10610 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
10620 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
10630 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
10640 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
10650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
10660 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
10670 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
10680 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
10690 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  KED]..**.** Call
106a0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
106b0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
106c0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
106d0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
106e0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
106f0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
10700 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
10710 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
10720 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
10730 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
10740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10750 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
10760 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
10770 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
10780 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
10790 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
107a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
107b0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
107c0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
107d0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
107e0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
107f0 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a  s cleared..**.**
10800 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
10810 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32 33  * [H12341] [H123
10820 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f 0a  43] [H12344].*/.
10830 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
10840 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
10850 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
10860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10870 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
10880 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
10890 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c  eries {H12370} <
108a0 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65  S10000>.**.** De
108b0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
108c0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
108d0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
108e0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
108f0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
10900 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
10910 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
10920 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
10930 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
10940 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
10950 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
10960 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
10970 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
10980 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
10990 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
109a0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
109b0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
109c0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
109d0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
109e0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
109f0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
10a00 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
10a10 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
10a20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
10a30 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
10a40 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
10a50 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
10a60 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
10a70 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
10a80 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
10a90 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
10aa0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
10ab0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
10ac0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
10ad0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
10ae0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
10af0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
10b00 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
10b10 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
10b20 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
10b30 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
10b40 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
10b50 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
10b60 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
10b70 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
10b80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
10b90 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
10ba0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
10bb0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
10bc0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
10bd0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
10be0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
10bf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
10c00 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
10c10 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
10c20 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
10c30 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
10c40 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
10c50 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
10c60 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
10c70 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
10c80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10c90 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
10ca0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
10cb0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
10cc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
10cd0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
10ce0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
10cf0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
10d00 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
10d10 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
10d20 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
10d30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
10d40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
10d50 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
10d60 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
10d70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
10d80 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
10d90 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
10da0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
10db0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
10dc0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
10dd0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
10de0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
10df0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
10e00 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
10e10 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
10e20 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
10e30 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
10e40 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
10e50 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
10e60 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
10e70 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
10e80 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
10e90 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
10ea0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
10eb0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
10ec0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
10ed0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
10ee0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
10ef0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
10f00 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
10f10 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
10f20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
10f30 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
10f40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
10f50 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
10f60 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
10f70 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
10f80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
10f90 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
10fa0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
10fb0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
10fc0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
10fd0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
10fe0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
10ff0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11010 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
11020 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
11030 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
11040 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
11050 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
11060 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
11070 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
11080 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
11090 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  s 2nd parameter.
110a0 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72    It returns a r
110b0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
110c0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
110d0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
110e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
110f0 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e  After the callin
11100 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66  g function has f
11110 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
11120 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f  e result, it sho
11130 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  uld.** pass the 
11140 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
11150 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
11160 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
11170 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
11180 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
11190 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
111a0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
111b0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
111c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
111d0 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
111e0 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
111f0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
11200 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
11210 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
11220 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
11230 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
11240 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
11250 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
11260 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
11270 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
11280 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
11290 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
112a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
112b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
112c0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
112d0 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
112e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
112f0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
11300 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
11310 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
11320 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
11330 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
11340 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
11350 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
11360 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
11370 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
11380 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
11390 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
113a0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
113b0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
113c0 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
113d0 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
113e0 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
113f0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
11400 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
11410 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
11420 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
11430 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c  rcode()] or [sql
11440 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
11450 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11460 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d 20  ts:.** [H12371] 
11470 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37 34  [H12373] [H12374
11480 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32 33  ] [H12376] [H123
11490 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a  79] [H12382].*/.
114a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
114b0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
114c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
114d0 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
114e0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
114f0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
11500 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
11510 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
11520 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
11530 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
11540 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
11550 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
11560 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
11570 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
11580 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
11590 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
115a0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
115b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
115c0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
115d0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
115e0 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
115f0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
11600 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
11610 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
11620 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
11630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11640 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
11650 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
11660 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53  ions {H17400} <S
11670 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a  70000><S20000>.*
11680 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
11690 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b  nes are workalik
116a0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
116b0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
116c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
116d0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
116e0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  library..**.** T
116f0 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
11700 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
11710 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
11720 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
11730 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
11740 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
11750 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
11760 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
11770 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
11780 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
11790 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
117a0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
117b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
117c0 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65  ].  Both routine
117d0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
117e0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
117f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11800 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
11810 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
11820 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
11830 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
11840 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73  ring..**.** In s
11850 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11860 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
11870 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
11880 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
11890 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
118a0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
118b0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
118c0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
118d0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
118e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
118f0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
11900 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
11910 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
11920 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
11930 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
11940 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
11950 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
11960 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20  om snprintf().  
11970 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
11980 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
11990 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
119a0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
119b0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
119c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
119d0 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74  ty.  Note also t
119e0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
119f0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
11a00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
11a10 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
11a20 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
11a30 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
11a40 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
11a50 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
11a60 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  r.  We admit tha
11a70 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
11a80 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
11a90 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
11aa0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
11ab0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
11ac0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
11ad0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
11ae0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
11af0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
11b00 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
11b10 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
11b20 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20  ..**.** As long 
11b30 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
11b40 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
11b50 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
11b60 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
11b70 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
11b80 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
11b90 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
11ba0 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ted.  The first.
11bb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
11bc0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
11bd0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
11be0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
11bf0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
11c00 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
11c10 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
11c20 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
11c30 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
11c40 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
11c50 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
11c60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
11c70 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
11c80 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
11c90 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
11ca0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
11cb0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
11cc0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
11cd0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
11ce0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
11cf0 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
11d00 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
11d10 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
11d20 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
11d30 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
11d40 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
11d50 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  * The %q option 
11d60 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
11d70 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
11d80 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
11d90 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
11da0 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
11db0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
11dc0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
11dd0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
11de0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
11df0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
11e00 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
11e10 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c  teral.  By doubl
11e20 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
11e30 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
11e40 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
11e50 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
11e60 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
11e70 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
11e80 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
11e90 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
11ea0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
11eb0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
11ec0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
11ed0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
11ee0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
11ef0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
11f00 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
11f10 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
11f20 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
11f30 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
11f40 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
11f50 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
11f60 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
11f70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11f80 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
11f90 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
11fa0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
11fb0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
11fc0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
11fd0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
11fe0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
11ff0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
12000 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
12010 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
12020 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
12030 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
12040 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
12050 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
12060 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
12070 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
12080 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
12090 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
120a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
120b0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
120c0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
120d0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
120e0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
120f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12100 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
12110 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
12120 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
12130 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
12140 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
12150 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
12160 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12170 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
12180 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12190 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
121a0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
121b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
121c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
121d0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
121e0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
121f0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
12200 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
12210 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
12220 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
12230 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
12240 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
12250 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
12260 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74  **.** The %Q opt
12270 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
12280 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
12290 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
122a0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
122b0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
122c0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
122d0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
122e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
122f0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
12300 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
12310 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
12320 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
12330 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
12340 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
12350 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  es) in place of 
12360 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20  the %Q option.  
12370 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
12380 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
12390 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
123a0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
123b0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
123c0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
123d0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
123e0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
123f0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
12400 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
12410 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
12420 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
12430 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
12440 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
12450 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
12460 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
12470 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
12480 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
12490 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
124a0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
124b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
124c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25  er..**.** The "%
124d0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
124e0 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74  tion works exact
124f0 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74  ly like "%s" wit
12500 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
12510 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
12520 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
12530 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
12540 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
12550 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
12560 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
12570 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
12580 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ing. {END}.**.**
12590 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
125a0 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 31 37 34  * [H17403] [H174
125b0 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a  06] [H17407].*/.
125c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
125d0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
125e0 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
125f0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
12600 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
12610 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
12620 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
12630 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
12640 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
12650 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
12660 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
12670 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20  system {H17300} 
12680 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
12690 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20  he SQLite core  
126a0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
126b0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
126c0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
126d0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
126e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
126f0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
12700 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
12710 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
12720 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
12730 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
12740 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
12750 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
12760 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
12770 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
12780 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
12790 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
127a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
127b0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
127c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
127d0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
127e0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
127f0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
12800 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
12810 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
12820 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
12830 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
12840 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
12850 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
12860 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
12870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
12880 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
12890 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
128a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
128b0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
128c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
128d0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
128e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
128f0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
12900 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
12910 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
12920 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
12930 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
12940 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
12950 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
12960 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
12970 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
12980 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
12990 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
129a0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
129b0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
129c0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
129d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
129e0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
129f0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
12a00 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
12a10 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
12a20 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
12a30 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
12a40 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
12a50 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
12a60 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
12a70 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
12a80 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
12a90 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
12aa0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
12ab0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
12ac0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
12ad0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
12ae0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
12af0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
12b00 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
12b10 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
12b20 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
12b30 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
12b40 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
12b50 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
12b60 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
12b70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
12b80 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  alloc()..**.** T
12b90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
12ba0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
12bb0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
12bc0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
12bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
12be0 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
12bf0 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
12c00 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
12c10 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
12c20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12c30 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
12c40 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
12c50 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74  parameter.  If t
12c60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12c70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
12c80 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
12c90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
12ca0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
12cb0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
12cc0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
12cd0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
12ce0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
12cf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
12d00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12d10 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  ..** If the seco
12d20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
12d30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12d40 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
12d50 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
12d60 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
12d70 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
12d80 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
12d90 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
12da0 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
12db0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
12dc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12dd0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  ..** sqlite3_rea
12de0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
12df0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
12e00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
12e10 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
12e20 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
12e30 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
12e40 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
12e50 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49  navailable..** I
12e60 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
12e70 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
12e80 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
12e90 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
12ea0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
12eb0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
12ec0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
12ed0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
12ee0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
12ef0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12f00 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
12f10 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
12f20 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  ed..** If sqlite
12f30 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
12f40 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
12f50 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
12f60 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
12f70 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  eed..**.** The m
12f80 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
12f90 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
12fa0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
12fb0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
12fc0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
12fd0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
12fe0 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45  yte boundary. {E
12ff0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ND}.**.** The de
13000 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
13010 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f  tion of the memo
13020 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
13030 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20  bsystem uses.** 
13040 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  the malloc(), re
13050 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
13060 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
13070 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
13080 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38  brary..** {H1738
13090 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  2} However, if S
130a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
130b0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
130c0 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
130d0 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72  =<i>NNN</i> C pr
130e0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
130f0 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f   (where <i>NNN</
13100 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  i>.** is an inte
13110 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74  ger), then SQLit
13120 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
13130 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65  c array of at le
13140 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69  ast.** <i>NNN</i
13150 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
13160 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72  and uses that ar
13170 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ray for all of i
13180 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65  ts dynamic.** me
13190 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
131a0 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
131b0 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
131c0 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e  allocator option
131d0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65  s.** may be adde
131e0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
131f0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
13200 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
13210 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
13220 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
13230 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
13240 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
13250 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
13260 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
13270 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
13280 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
13290 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
132a0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
132b0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
132c0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
132d0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
132e0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
132f0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
13300 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
13310 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
13320 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
13330 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
13340 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
13350 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
13360 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
13370 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
13380 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
13390 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
133a0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
133b0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
133c0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
133d0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
133e0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
133f0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
13400 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
13410 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
13420 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
13430 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
13440 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
13450 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
13460 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
13470 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
13480 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  OMEM]..**.** Req
13490 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
134a0 31 37 33 30 33 5d 20 5b 48 31 37 33 30 34 5d 20  17303] [H17304] 
134b0 5b 48 31 37 33 30 35 5d 20 5b 48 31 37 33 30 36  [H17305] [H17306
134c0 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48 31 37 33  ] [H17310] [H173
134d0 31 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b 48 31  12] [H17315] [H1
134e0 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31  7318].** [H17321
134f0 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48 31 37 33  ] [H17322] [H173
13500 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  23].**.** The po
13510 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
13520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
13530 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
13540 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
13550 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
13560 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
13570 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
13580 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
13590 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
135a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
135b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
135c0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
135d0 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
135e0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
135f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
13600 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
13610 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
13620 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
13630 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
13640 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
13650 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
13660 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
13670 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13680 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
13690 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
136a0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
136b0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
136c0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
136d0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
136e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
136f0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
13700 20 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37   Statistics {H17
13710 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a  370} <S30210>.**
13720 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
13730 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
13740 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
13750 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
13760 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
13770 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13780 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
13790 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
137a0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
137b0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
137c0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
137d0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
137e0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
137f0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
13800 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 5b  s:.** [H17371] [
13810 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37 34 5d  H17373] [H17374]
13820 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73 71 6c   [H17375].*/.sql
13830 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
13840 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
13850 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
13860 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
13870 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
13880 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
13890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
138a0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
138b0 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31  er Generator {H1
138c0 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7390} <S20000>.*
138d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
138e0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
138f0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
13900 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
13910 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
13920 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
13930 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
13940 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
13950 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
13960 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
13970 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
13980 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
13990 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
139a0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
139b0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
139c0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
139d0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
139e0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
139f0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
13a00 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
13a10 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
13a20 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
13a30 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
13a40 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  oses..**.** A ca
13a50 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
13a60 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
13a70 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
13a80 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
13a90 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74  *.** The first t
13aa0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
13ab0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
13ac0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
13ad0 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
13ae0 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
13af0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
13b00 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
13b10 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
13b20 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
13b30 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
13b40 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
13b50 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20  ] object..** On 
13b60 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
13b70 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
13b80 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
13b90 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
13ba0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
13bb0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
13bc0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
13bd0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
13be0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a  ss.** method..**
13bf0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
13c00 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a 2a 2f  :.** [H17392].*/
13c10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
13c20 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
13c30 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
13c40 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
13c50 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
13c60 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
13c70 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30  {H12500} <S70100
13c80 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
13c90 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
13ca0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
13cb0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
13cc0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
13cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
13ce0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
13cf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
13d00 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
13d10 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
13d20 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
13d30 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
13d40 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
13d50 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
13d60 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
13d70 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
13d80 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
13d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13da0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
13db0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
13dc0 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73  ()].  At various
13dd0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
13de0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
13df0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
13e00 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
13e10 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
13e20 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
13e30 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
13e40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
13e50 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
13e60 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
13e70 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
13e80 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
13e90 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
13ea0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
13eb0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
13ec0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
13ed0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
13ee0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
13ef0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
13f00 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
13f10 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
13f20 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
13f30 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
13f40 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
13f50 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
13f60 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
13f70 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
13f80 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20  h an error.  If 
13f90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
13fa0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
13fb0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
13fc0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
13fd0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
13fe0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
13ff0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
14000 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
14010 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
14020 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
14030 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
14040 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
14050 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
14060 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
14070 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
14080 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
14090 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
140a0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
140b0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
140c0 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74  d is ok.  When t
140d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
140e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
140f0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
14100 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14110 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
14120 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
14130 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
14140 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
14150 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
14160 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
14170 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
14180 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68  s denied.  If th
14190 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
141a0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
141b0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
141c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
141d0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
141e0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
141f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14200 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
14210 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
14220 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
14230 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
14240 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
14250 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
14260 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
14270 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
14280 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
14290 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
142a0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
142b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
142c0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
142d0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
142e0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
142f0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
14300 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  le..**.** The fi
14310 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14320 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14330 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
14340 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
14350 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
14360 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
14370 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
14380 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f  erface. The seco
14390 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
143a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
143b0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
143c0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
143d0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
143e0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
143f0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
14400 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
14410 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
14420 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
14430 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
14440 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
14450 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
14460 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
14470 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
14480 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
14490 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
144a0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
144b0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
144c0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
144d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
144e0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
144f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
14500 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
14510 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
14520 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
14530 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
14540 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
14550 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
14560 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
14570 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
14580 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
14590 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
145a0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
145b0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
145c0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
145d0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
145e0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
145f0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
14600 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
14610 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
14620 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
14630 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
14640 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
14650 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
14660 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
14670 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
14680 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
14690 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
146a0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
146b0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
146c0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
146d0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
146e0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
146f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
14700 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
14710 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
14720 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
14730 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
14740 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
14750 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
14760 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
14770 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
14780 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
14790 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
147a0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
147b0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
147c0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
147d0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
147e0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
147f0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
14800 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
14810 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
14820 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
14830 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
14840 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
14850 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
14860 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
14870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14880 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
14890 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
148a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
148b0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
148c0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
148d0 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20   call.  Disable 
148e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
148f0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
14900 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
14910 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
14920 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
14930 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
14940 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14950 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
14960 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
14970 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
14980 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
14990 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
149a0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
149b0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
149c0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
149d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
149e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
149f0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
14a00 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
14a10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
14a20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
14a30 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
14a40 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
14a50 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74  *.** When [sqlit
14a60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14a70 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
14a80 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
14a90 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
14aa0 74 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65  t might be repre
14ab0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
14ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
14ad0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
14ae0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
14af0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
14b00 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
14b10 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
14b20 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
14b30 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
14b40 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
14b50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
14b60 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  p()]..**.** Note
14b70 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
14b80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
14b90 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
14ba0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
14bb0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
14bc0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
14bd0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
14be0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
14bf0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
14c00 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
14c10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
14c20 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
14c30 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d  nts:.** [H12501]
14c40 20 5b 48 31 32 35 30 32 5d 20 5b 48 31 32 35 30   [H12502] [H1250
14c50 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48 31 32  3] [H12504] [H12
14c60 35 30 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48  505] [H12506] [H
14c70 31 32 35 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a  12507] [H12510].
14c80 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48 31 32  ** [H12511] [H12
14c90 35 31 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48  512] [H12520] [H
14ca0 31 32 35 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a  12521] [H12522].
14cb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
14cc0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
14cd0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
14ce0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
14cf0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
14d00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
14d10 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
14d20 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
14d30 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
14d40 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
14d50 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
14d60 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31  des {H12590} <H1
14d70 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
14d80 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
14d90 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
14da0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
14db0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
14dc0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
14dd0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
14de0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
14df0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
14e00 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
14e10 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
14e20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
14e30 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
14e40 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
14e50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
14e60 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
14e70 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
14e80 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
14e90 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
14ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
14eb0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
14ec0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
14ed0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
14ee0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
14ef0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
14f00 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
14f10 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
14f20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
14f30 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
14f40 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
14f50 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48   Action Codes {H
14f60 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12550} <H12500>.
14f70 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
14f80 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
14f90 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
14fa0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
14fb0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
14fc0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
14fd0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
14fe0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
14ff0 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
15000 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
15010 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
15020 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
15030 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
15040 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
15050 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
15060 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
15070 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
15080 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
15090 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
150a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
150b0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
150c0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
150d0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
150e0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
150f0 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
15100 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
15110 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
15120 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
15130 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
15140 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
15150 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
15160 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
15170 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
15180 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
15190 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
151a0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
151b0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
151c0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
151d0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
151e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
151f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
15200 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
15210 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
15220 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
15230 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
15240 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
15250 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
15260 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
15270 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
15280 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
15290 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
152a0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
152b0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
152c0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
152d0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
152e0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
152f0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
15300 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ode..**.** Requi
15310 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
15320 35 35 31 5d 20 5b 48 31 32 35 35 32 5d 20 5b 48  551] [H12552] [H
15330 31 32 35 35 33 5d 20 5b 48 31 32 35 35 34 5d 0a  12553] [H12554].
15340 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
15350 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15360 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
15370 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
15380 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
15390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
153a0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
153b0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
153c0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
153d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
153e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
153f0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
15400 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
15410 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
15420 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15440 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
15450 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
15460 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
15470 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15490 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
154a0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
154b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
154c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
154d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
154e0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
154f0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
15500 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
15510 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15520 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
15530 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
15540 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
15550 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
15560 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15570 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
15580 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
15590 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
155a0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
155b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
155c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
155d0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
155e0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
155f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
15600 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15610 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
15620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
15630 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15640 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15650 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15660 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
15670 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
15680 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
15690 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
156a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
156b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
156c0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
156d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
156e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
156f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15700 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
15710 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
15720 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
15730 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15740 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15750 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
15760 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
15770 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
15780 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15790 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
157a0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
157b0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
157c0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
157d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
157e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
157f0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
15800 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
15810 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
15820 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15840 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
15850 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
15860 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
15870 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
15880 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15890 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
158a0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
158b0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
158c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
158d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
158e0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
158f0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
15900 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
15910 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
15930 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
15940 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
15950 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
15960 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
15970 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
15980 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
15990 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
159a0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
159b0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
159c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
159d0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
159e0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
159f0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
15a00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
15a20 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
15a30 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
15a40 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
15a50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15a60 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
15a70 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
15a80 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
15a90 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
15aa0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
15ab0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
15ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
15ad0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
15ae0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
15af0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15b00 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
15b10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
15b20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
15b30 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
15b40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15b50 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
15b60 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
15b70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
15b80 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
15b90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15ba0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
15bb0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
15bc0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
15bd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15be0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15bf0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
15c00 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
15c10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
15c20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
15c30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15c40 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
15c50 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
15c60 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
15c70 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
15c80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15c90 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
15ca0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
15cb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15cc0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
15cd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15ce0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
15cf0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
15d00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15d10 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
15d20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15d30 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
15d40 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
15d50 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
15d60 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
15d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15d80 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
15d90 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
15da0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
15db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15dc0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
15dd0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
15de0 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30   {H12280} <S6040
15df0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
15e00 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  AL.**.** These r
15e10 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
15e20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15e30 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
15e40 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
15e50 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
15e60 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
15e70 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
15e80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
15e90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
15ea0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
15eb0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
15ec0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
15ed0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
15ee0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
15ef0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
15f00 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
15f10 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
15f20 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
15f30 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
15f40 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15f50 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
15f60 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
15f70 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
15f80 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
15f90 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
15fa0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
15fb0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
15fc0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
15fd0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
15fe0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
15ff0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
16000 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
16010 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
16020 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  er..**.** The ca
16030 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
16040 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
16050 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
16060 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
16070 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
16080 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54  ent finishes.  T
16090 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
160a0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
160b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
160c0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
160d0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
160e0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
160f0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
16100 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
16110 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  k to run..**.** 
16120 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
16130 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 32 32 38   [H12281] [H1228
16140 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48 31 32  2] [H12283] [H12
16150 32 38 34 5d 20 5b 48 31 32 32 38 35 5d 20 5b 48  284] [H12285] [H
16160 31 32 32 38 37 5d 20 5b 48 31 32 32 38 38 5d 20  12287] [H12288] 
16170 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 32  [H12289].** [H12
16180 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  290].*/.SQLITE_E
16190 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
161a0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
161b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
161c0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
161d0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
161e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
161f0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
16200 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
16210 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
16220 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
16230 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
16240 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
16250 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
16260 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
16270 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20  gress Callbacks 
16280 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30  {H12910} <S60400
16290 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
162a0 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
162b0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
162c0 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
162d0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
162e0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
162f0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
16300 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
16310 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
16320 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
16330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16340 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
16350 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
16360 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
16370 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
16380 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
16390 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
163a0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
163b0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ry..**.** If the
163c0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
163d0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
163e0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
163f0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
16400 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
16410 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
16420 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
16430 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
16440 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
16450 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
16460 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
16470 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  ss handler must 
16480 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
16490 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
164a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
164b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
164c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
164d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
164e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
164f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16500 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
16510 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
16520 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
16530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16540 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
16550 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
16560 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
16570 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
16580 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 5d  nts:.** [H12911]
16590 20 5b 48 31 32 39 31 32 5d 20 5b 48 31 32 39 31   [H12912] [H1291
165a0 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48 31 32  3] [H12914] [H12
165b0 39 31 35 5d 20 5b 48 31 32 39 31 36 5d 20 5b 48  915] [H12916] [H
165c0 31 32 39 31 37 5d 20 5b 48 31 32 39 31 38 5d 0a  12917] [H12918].
165d0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
165e0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
165f0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
16600 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
16610 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
16620 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
16630 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
16640 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e Connection {H1
16650 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a  2700} <S40200>.*
16660 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
16670 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
16680 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
16690 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
166a0 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
166b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
166c0 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  . The filename a
166d0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
166e0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
166f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
16700 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
16710 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
16720 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
16730 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
16740 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
16750 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64  3_open16(). A [d
16760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16770 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
16780 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
16790 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
167a0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
167b0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
167c0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
167d0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
167e0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
167f0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
16800 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
16810 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
16820 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
16830 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
16840 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
16850 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
16860 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49  e3].** object. I
16870 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
16880 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
16890 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
168a0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
168b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
168c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
168d0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
168e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
168f0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
16900 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
16910 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
16920 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
16930 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
16940 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
16950 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
16960 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
16970 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  or..**.** The de
16980 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
16990 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
169a0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
169b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
169c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
169d0 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
169e0 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
169f0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
16a00 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
16a10 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
16a20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
16a30 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
16a40 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
16a50 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
16a60 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
16a70 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
16a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16a90 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
16aa0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
16ab0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
16ac0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
16ad0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
16ae0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
16af0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
16b00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
16b10 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
16b20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
16b30 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
16b40 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
16b50 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
16b60 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
16b70 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
16b80 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
16b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16ba0 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70  on.  The flags p
16bb0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b  arameter can tak
16bc0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
16bd0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
16be0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
16bf0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
16c00 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
16c10 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f  _OPEN_NOMUTEX] o
16c20 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  r [SQLITE_OPEN_F
16c30 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a  ULLMUTEX] flags:
16c40 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
16c50 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
16c60 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
16c70 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
16c80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
16c90 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
16ca0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
16cb0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
16cc0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
16cd0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
16ce0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
16cf0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
16d00 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
16d10 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
16d20 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
16d30 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
16d40 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
16d50 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
16d60 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
16d70 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
16d80 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
16d90 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
16da0 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
16db0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
16dc0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
16dd0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
16de0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
16df0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
16e00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
16e10 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
16e20 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
16e30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
16e40 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16e50 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
16e60 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
16e70 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a   creates it if.*
16e80 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
16e90 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
16ea0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
16eb0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
16ec0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
16ed0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
16ee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
16ef0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
16f00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
16f10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
16f20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
16f30 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
16f40 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
16f50 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
16f60 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
16f70 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
16f80 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
16f90 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
16fa0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
16fb0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
16fc0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73  FULLMUTEX] flags
16fd0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
16fe0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
16ff0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
17000 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
17010 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
17020 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
17030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17040 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
17050 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
17060 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
17070 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
17080 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
17090 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
170a0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
170b0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
170c0 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ime.  If the.** 
170d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
170e0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
170f0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
17100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17110 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
17120 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
17130 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
17140 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
17150 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
17160 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
17170 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
17180 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  start-time..**.*
17190 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
171a0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
171b0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
171c0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
171d0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
171e0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
171f0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
17200 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20   This in-memory 
17210 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
17220 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
17230 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17240 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
17250 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
17260 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
17270 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
17280 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
17290 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
172a0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
172b0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
172c0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
172d0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
172e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
172f0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
17300 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
17310 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
17320 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
17330 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
17340 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
17350 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
17360 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
17370 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
17380 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
17390 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
173a0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
173b0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
173c0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
173d0 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73  e created.  This
173e0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
173f0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
17400 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
17410 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
17420 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17430 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
17440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
17450 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
17460 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
17470 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
17480 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17490 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
174a0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
174b0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
174c0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
174d0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
174e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
174f0 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20  ld use.  If the 
17500 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17510 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
17520 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
17530 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
17540 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
17550 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  sed..**.** <b>No
17560 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
17570 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
17580 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
17590 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
175a0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
175b0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
175c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
175d0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
175e0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
175f0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
17600 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
17610 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
17620 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
17630 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
17640 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
17650 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
17660 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
17670 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
17680 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
17690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
176a0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
176b0 73 3a 0a 2a 2a 20 5b 48 31 32 37 30 31 5d 20 5b  s:.** [H12701] [
176c0 48 31 32 37 30 32 5d 20 5b 48 31 32 37 30 33 5d  H12702] [H12703]
176d0 20 5b 48 31 32 37 30 34 5d 20 5b 48 31 32 37 30   [H12704] [H1270
176e0 36 5d 20 5b 48 31 32 37 30 37 5d 20 5b 48 31 32  6] [H12707] [H12
176f0 37 30 39 5d 20 5b 48 31 32 37 31 31 5d 0a 2a 2a  709] [H12711].**
17700 20 5b 48 31 32 37 31 32 5d 20 5b 48 31 32 37 31   [H12712] [H1271
17710 33 5d 20 5b 48 31 32 37 31 34 5d 20 5b 48 31 32  3] [H12714] [H12
17720 37 31 37 5d 20 5b 48 31 32 37 31 39 5d 20 5b 48  717] [H12719] [H
17730 31 32 37 32 31 5d 20 5b 48 31 32 37 32 33 5d 0a  12721] [H12723].
17740 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
17750 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
17760 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
17770 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
17780 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
17790 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
177a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
177b0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
177c0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
177d0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
177e0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
177f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
17800 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
17810 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
17820 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
17830 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
17840 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
17850 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
17860 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
17870 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
17880 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
17890 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
178a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
178b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
178c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
178d0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
178e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
178f0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
17900 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
17910 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
17920 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
17930 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
17940 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
17950 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
17960 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32  s {H12800} <S602
17970 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
17980 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
17990 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
179a0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
179b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
179c0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
179d0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
179e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
179f0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
17a00 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
17a10 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
17a20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17a30 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
17a40 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
17a50 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
17a60 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
17a70 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
17a80 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
17a90 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
17aa0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
17ab0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  .  The sqlite3_e
17ac0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
17ad0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
17ae0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
17af0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
17b00 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
17b10 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
17b20 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
17b30 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
17b40 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
17b50 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  isabled..**.** T
17b60 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
17b70 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
17b80 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
17b90 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
17ba0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
17bb0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
17bc0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
17bd0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
17be0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
17bf0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
17c00 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
17c10 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
17c20 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
17c30 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
17c40 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
17c50 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
17c60 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
17c70 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
17c80 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
17c90 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
17ca0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
17cb0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
17cc0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
17cd0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
17ce0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  face functions..
17cf0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
17d00 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
17d10 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
17d20 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
17d30 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
17d40 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
17d50 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
17d60 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
17d70 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
17d80 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
17d90 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
17da0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
17db0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
17dc0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
17dd0 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
17de0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
17df0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
17e00 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
17e10 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
17e20 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
17e30 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
17e40 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
17e50 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
17e60 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
17e70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17e80 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
17e90 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
17ea0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
17eb0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
17ec0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
17ed0 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
17ee0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
17ef0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
17f00 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
17f10 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
17f20 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
17f30 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
17f40 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
17f50 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
17f60 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
17f70 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
17f80 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
17f90 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
17fa0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
17fb0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
17fc0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
17fd0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
17fe0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
17ff0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
18000 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
18010 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  be set..**.** Re
18020 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
18030 48 31 32 38 30 31 5d 20 5b 48 31 32 38 30 32 5d  H12801] [H12802]
18040 20 5b 48 31 32 38 30 33 5d 20 5b 48 31 32 38 30   [H12803] [H1280
18050 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b 48 31 32  7] [H12808] [H12
18060 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  809].*/.int sqli
18070 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
18080 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
18090 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
180a0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
180b0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
180c0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
180d0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
180e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
180f0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
18100 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18110 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
18120 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30  t Object {H13000
18130 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45  } <H13010>.** KE
18140 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
18150 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
18160 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
18170 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
18180 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
18190 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
181a0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
181b0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
181c0 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
181d0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
181e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
181f0 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
18200 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
18210 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
18220 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
18230 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
18240 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
18250 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
18260 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
18270 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
18280 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
18290 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
182a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
182b0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
182c0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
182d0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
182e0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
182f0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
18300 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
18310 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
18320 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
18330 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
18340 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
18350 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
18360 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
18370 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
18380 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
18390 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
183a0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
183b0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
183c0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
183d0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
183e0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
183f0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
18400 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
18410 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
18420 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
18430 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
18440 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
18450 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
18460 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
18470 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
18480 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
18490 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
184a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
184b0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
184c0 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36  s {H12760} <S206
184d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00>.**.** This i
184e0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
184f0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
18500 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
18510 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
18520 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
18530 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
18540 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
18550 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
18560 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18570 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
18580 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
18590 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
185a0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
185b0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
185c0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
185d0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
185e0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
185f0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
18600 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
18610 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
18620 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
18630 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
18640 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20  hat construct.  
18650 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  The function ret
18660 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d  urns the old lim
18670 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  it..**.** If the
18680 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
18690 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
186a0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
186b0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20  changed..** For 
186c0 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  the limit catego
186d0 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d  ry of SQLITE_LIM
186e0 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20  IT_XYZ there is 
186f0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
18700 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
18710 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f  ].** set by a co
18720 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
18730 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
18740 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74  named .** [limit
18750 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  s | SQLITE_MAX_X
18760 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  YZ]..** (The "_L
18770 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
18780 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
18790 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74   "_MAX_".).** At
187a0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
187b0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
187c0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
187d0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
187e0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
187f0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
18800 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52  r limit..**.** R
18810 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un time limits a
18820 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
18830 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
18840 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
18850 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
18860 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
18870 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
18880 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
18890 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
188a0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
188b0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
188c0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
188d0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
188e0 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
188f0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
18900 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
18910 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
18920 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
18930 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
18940 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
18950 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
18960 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
18970 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
18980 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
18990 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
189a0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
189b0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
189c0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
189d0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
189e0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
189f0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
18a00 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
18a10 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
18a20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
18a30 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
18a40 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
18a50 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
18a60 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
18a70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
18a80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
18a90 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
18aa0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
18ab0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
18ac0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
18ad0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
18ae0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
18af0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
18b00 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
18b10 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
18b20 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
18b30 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
18b40 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
18b50 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
18b60 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
18b70 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
18b80 20 5b 48 31 32 37 36 32 5d 20 5b 48 31 32 37 36   [H12762] [H1276
18b90 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a 2f 0a 69  6] [H12769].*/.i
18ba0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
18bb0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
18bc0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
18bd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18be0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
18bf0 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37  Categories {H127
18c00 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20  90} <H12760>.** 
18c10 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
18c20 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69   category} {limi
18c30 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
18c40 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
18c50 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
18c60 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
18c70 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
18c80 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
18c90 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
18ca0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
18cb0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
18cc0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
18cd0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
18ce0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
18cf0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
18d00 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
18d10 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
18d20 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
18d30 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
18d40 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
18d50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
18d60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
18d70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
18d80 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
18d90 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
18da0 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20   row.<dd>.**.** 
18db0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
18dc0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
18dd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18de0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
18df0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
18e00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18e10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
18e20 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
18e30 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18e40 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
18e50 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
18e60 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
18e70 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
18e80 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
18e90 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18ea0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
18eb0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
18ec0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
18ed0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
18ee0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
18f00 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
18f10 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
18f20 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
18f30 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
18f40 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  ression.</dd>.**
18f50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18f60 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
18f70 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
18f80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
18f90 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
18fa0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
18fb0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
18fc0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18fd0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
18fe0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18ff0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
19000 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
19010 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
19020 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
19030 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
19040 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
19050 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
19060 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
19070 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
19080 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
19090 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
190a0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
190b0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  nction.</dd>.**.
190c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
190d0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
190e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
190f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
19100 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
19110 64 20 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64  d databases].</d
19120 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19130 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
19140 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
19150 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
19160 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
19170 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
19180 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
19190 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
191a0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a  operators.</dd>.
191b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
191c0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
191d0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
191e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
191f0 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
19200 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
19210 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
19220 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
19230 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
19240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
19250 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
19260 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
19270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
19280 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
19290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
192a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
192b0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
192c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
192d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
192e0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
192f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19300 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
19310 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
19320 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
19330 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
19340 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
19350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19360 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
19370 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
19380 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
19390 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
193a0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
193b0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
193c0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
193d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
193e0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
193f0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
19400 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
19410 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
19420 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43        9../*.** C
19430 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
19440 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
19450 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31  ent {H13010} <S1
19460 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0000>.** KEYWORD
19470 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
19480 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
19490 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
194a0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
194b0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
194c0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
194d0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
194e0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
194f0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
19500 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19510 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
19520 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
19530 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
19540 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
19550 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
19560 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
19570 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
19580 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
19590 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
195a0 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
195b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
195c0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
195d0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
195e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
195f0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
19600 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
19610 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
19620 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
19630 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
19640 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
19650 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
19660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19670 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
19680 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
19690 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
196a0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
196b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
196c0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
196d0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
196e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
196f0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
19700 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
19710 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
19720 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
19730 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
19740 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
19750 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
19760 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
19770 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
19780 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
19790 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
197a0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
197b0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
197c0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
197d0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
197e0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
197f0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
19800 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
19810 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
19820 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
19830 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
19840 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
19850 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
19860 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
19870 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
19880 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
19890 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
198a0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
198b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
198c0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
198d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
198e0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
198f0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
19900 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
19910 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
19920 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 7a  tes..**.** If pz
19930 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
19940 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
19950 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
19960 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
19970 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
19980 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
19990 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
199a0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
199b0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
199c0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
199d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
199e0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
199f0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
19a00 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
19a10 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
19a20 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  ** *ppStmt is le
19a30 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
19a40 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
19a50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
19a60 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
19a70 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
19a80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
19a90 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
19aa0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
19ab0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
19ac0 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74    If the input t
19ad0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
19ae0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
19af0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
19b00 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
19b10 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
19b20 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
19b30 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
19b40 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
19b50 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
19b60 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
19b70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
19b80 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
19b90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
19ba0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
19bb0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
19bc0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
19bd0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
19be0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
19bf0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
19c00 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
19c10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
19c20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
19c30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
19c40 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
19c50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
19c60 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
19c70 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
19c80 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
19c90 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
19ca0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
19cb0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
19cc0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
19cd0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
19ce0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
19cf0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
19d00 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
19d10 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
19d20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19d30 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
19d40 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
19d50 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
19d60 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
19d70 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
19d80 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
19d90 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
19da0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
19db0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
19dc0 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
19dd0 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
19de0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
19df0 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
19e00 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
19e10 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
19e20 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
19e30 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
19e40 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
19e50 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
19e60 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
19e70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
19e80 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
19e90 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
19ea0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
19eb0 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
19ec0 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
19ed0 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
19ee0 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
19ef0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
19f00 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
19f10 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
19f20 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
19f30 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
19f40 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
19f50 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
19f60 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
19f70 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
19f80 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
19f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19fa0 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
19fb0 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
19fc0 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
19fd0 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
19fe0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
19ff0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1a000 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1a010 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1a020 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1a030 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1a040 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1a050 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1a060 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1a070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a080 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1a090 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1a0a0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1a0b0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1a0c0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1a0d0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1a0e0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1a0f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1a100 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1a110 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1a120 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1a130 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1a140 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1a150 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1a160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1a170 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1a180 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1a190 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1a1a0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1a1b0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1a1c0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1a1d0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1a1e0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1a1f0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1a200 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1a210 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1a220 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  l>.**.** Require
1a230 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 30 31  ments:.** [H1301
1a240 31 5d 20 5b 48 31 33 30 31 32 5d 20 5b 48 31 33  1] [H13012] [H13
1a250 30 31 33 5d 20 5b 48 31 33 30 31 34 5d 20 5b 48  013] [H13014] [H
1a260 31 33 30 31 35 5d 20 5b 48 31 33 30 31 36 5d 20  13015] [H13016] 
1a270 5b 48 31 33 30 31 39 5d 20 5b 48 31 33 30 32 31  [H13019] [H13021
1a280 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ].**.*/.int sqli
1a290 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
1a2a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1a2b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1a2c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1a2d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1a2e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1a2f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1a300 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1a310 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1a320 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1a330 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1a340 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1a350 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1a360 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1a370 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1a380 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1a390 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1a3a0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1a3b0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1a3c0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1a3d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a3e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1a3f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1a400 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1a410 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1a420 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1a430 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1a440 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1a450 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1a460 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1a470 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1a480 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1a490 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1a4a0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1a4b0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1a4c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1a4d0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1a4e0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1a4f0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1a500 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1a510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1a520 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
1a530 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a540 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1a550 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a560 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1a570 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1a580 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1a590 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1a5a0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1a5b0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1a5c0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1a5d0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1a5e0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1a5f0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1a600 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1a610 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1a620 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1a630 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1a640 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1a650 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1a660 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1a670 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a680 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a690 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a6a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1a6b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a6c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a6d0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1a6e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a6f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a700 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a710 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a720 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a730 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a740 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a750 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a760 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1a770 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a780 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a790 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a7a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a7b0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1a7c0 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30  ement SQL {H1310
1a7d0 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a  0} <H13000>.**.*
1a7e0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1a7f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a800 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
1a810 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
1a820 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
1a830 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
1a840 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1a850 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
1a860 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
1a870 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1a880 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1a890 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a8a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a8b0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1a8c0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1a8d0 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48 31 33 31  * [H13101] [H131
1a8e0 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a 2a 2f 0a  02] [H13103].*/.
1a8f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1a900 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
1a910 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1a920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1a930 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
1a940 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48   Value Object {H
1a950 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15000} <S20200>.
1a960 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1a970 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a980 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1a990 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1a9a0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1a9b0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1a9c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1a9d0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1a9e0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1a9f0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1aa00 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1aa10 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1aa20 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
1aa30 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1aa40 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20   stores. Values 
1aa50 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
1aa60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
1aa70 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
1aa80 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
1aa90 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
1aaa0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
1aab0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
1aac0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1aad0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
1aae0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
1aaf0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
1ab00 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
1ab10 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
1ab20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ab30 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
1ab40 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
1ab50 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
1ab60 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
1ab70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ab80 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
1ab90 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1aba0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
1abb0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
1abc0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1abd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
1abe0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
1abf0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ac00 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
1ac10 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
1ac20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
1ac30 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
1ac40 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
1ac50 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
1ac60 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
1ac70 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
1ac80 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ac90 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1aca0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
1acb0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
1acc0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1acd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
1ace0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1acf0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
1ad00 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
1ad10 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
1ad20 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
1ad30 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
1ad40 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
1ad50 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
1ad60 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
1ad70 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
1ad80 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
1ad90 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
1ada0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
1adb0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1adc0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
1add0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
1ade0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
1adf0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1ae00 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1ae10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ae20 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
1ae30 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
1ae40 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
1ae50 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
1ae60 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
1ae70 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
1ae80 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1ae90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
1aea0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
1aeb0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1aec0 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  een between prot
1aed0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1aee0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1aef0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1af00 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
1af10 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
1af20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1af30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1af40 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
1af50 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
1af60 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
1af70 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
1af80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1af90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
1afa0 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
1afb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
1afc0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
1afd0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
1afe0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
1aff0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
1b000 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
1b010 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1b020 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
1b030 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
1b040 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1b050 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
1b060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1b070 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
1b080 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
1b090 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
1b0a0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
1b0b0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
1b0c0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
1b0d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1b0e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
1b0f0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
1b100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
1b110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b120 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
1b130 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36  text Object {H16
1b140 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  001} <S20200>.**
1b150 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
1b160 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
1b170 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
1b180 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
1b190 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
1b1a0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
1b1b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
1b1c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
1b1d0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
1b1e0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
1b1f0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
1b200 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1b210 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
1b220 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1b230 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1b240 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
1b250 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
1b260 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
1b270 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
1b280 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1b290 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
1b2a0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
1b2b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
1b2c0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
1b2d0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
1b2e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
1b2f0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
1b300 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
1b310 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
1b320 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
1b330 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
1b340 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1b350 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
1b360 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
1b370 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
1b380 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
1b390 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
1b3a0 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35  Statements {H135
1b3b0 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20  00} <S70300>.** 
1b3c0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
1b3d0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
1b3e0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
1b3f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1b400 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
1b410 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
1b420 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
1b430 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
1b440 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ing}.**.** In th
1b450 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
1b460 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b470 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1b480 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
1b490 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
1b4a0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
1b4b0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
1b4c0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72  one of these for
1b4d0 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ms:.**.** <ul>.*
1b4e0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
1b4f0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
1b500 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
1b510 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
1b520 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
1b530 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   In the paramete
1b540 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62  r forms shown ab
1b550 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e  ove NNN is an in
1b560 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
1b570 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20  * and VVV is an 
1b580 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
1b590 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68  rameter name. Th
1b5a0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
1b5b0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
1b5c0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
1b5d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1b5e0 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
1b5f0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
1b600 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
1b610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1b620 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
1b630 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
1b640 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1b650 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
1b660 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1b670 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
1b680 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1b690 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1b6a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1b6b0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
1b6c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1b6d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
1b6e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1b6f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1b700 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
1b710 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
1b720 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65  e set..** The le
1b730 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
1b740 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1b750 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1b760 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1b770 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1b780 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1b790 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1b7a0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1b7b0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1b7c0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1b7d0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1b7e0 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69  rrence..** The i
1b7f0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
1b800 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
1b810 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
1b820 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1b830 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1b840 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
1b850 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
1b860 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
1b870 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
1b880 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
1b890 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c  ..** The NNN val
1b8a0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
1b8b0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
1b8c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1b8d0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
1b8e0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1b8f0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
1b900 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
1b910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
1b920 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1b930 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
1b940 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
1b950 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  .**.** In those 
1b960 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
1b970 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
1b980 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
1b990 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1b9a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1b9b0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
1b9c0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
1b9d0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1b9e0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
1b9f0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
1ba00 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
1ba10 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
1ba20 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
1ba30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
1ba40 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
1ba50 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
1ba60 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
1ba70 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
1ba80 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1ba90 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1baa0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67  ** The fifth arg
1bab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1bac0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1bad0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1bae0 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1baf0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1bb00 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1bb10 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1bb20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1bb30 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1bb40 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1bb50 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74  ed with it. If t
1bb60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1bb70 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
1bb80 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
1bb90 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
1bba0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
1bbb0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
1bbc0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
1bbd0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
1bbe0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
1bbf0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
1bc00 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
1bc10 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
1bc20 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
1bc30 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1bc40 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
1bc50 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
1bc60 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
1bc70 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
1bc80 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
1bc90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1bca0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1bcb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1bcc0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1bcd0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
1bce0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
1bcf0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
1bd00 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
1bd10 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  es.  A zeroblob 
1bd20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
1bd30 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
1bd40 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
1bd50 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
1bd60 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
1bd70 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
1bd80 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
1bd90 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
1bda0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
1bdb0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
1bdc0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
1bdd0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
1bde0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1bdf0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
1be00 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
1be10 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
1be20 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   A negative valu
1be30 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
1be40 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
1be50 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
1be60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1be70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1be80 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
1be90 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
1bea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1beb0 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
1bec0 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
1bed0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
1bee0 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
1bef0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1bf00 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
1bf10 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
1bf20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1bf30 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
1bf40 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
1bf50 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
1bf60 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
1bf70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1bf80 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1bf90 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
1bfa0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
1bfb0 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
1bfc0 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
1bfd0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
1bfe0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
1bff0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
1c000 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
1c010 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
1c020 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
1c030 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
1c040 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
1c050 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
1c060 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75  ned if these rou
1c070 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
1c080 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c   on a.** virtual
1c090 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73   machine that is
1c0a0 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65   the wrong state
1c0b0 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c   or which has al
1c0c0 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c  ready been final
1c0d0 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69  ized..** Detecti
1c0e0 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20  on of misuse is 
1c0f0 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70  unreliable.  App
1c100 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
1c110 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f   not depend.** o
1c120 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
1c130 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45  returns.  SQLITE
1c140 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e  _MISUSE is inten
1c150 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ded to indicate 
1c160 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72  a.** a logic err
1c170 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63  or in the applic
1c180 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76  ation.  Future v
1c190 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1c1a0 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63  e might.** panic
1c1b0 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74   rather than ret
1c1c0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
1c1d0 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  E..**.** See als
1c1e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1c1f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1c200 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1c210 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1c220 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
1c230 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1c240 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1c250 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1c260 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d 20 5b  s:.** [H13506] [
1c270 48 31 33 35 30 39 5d 20 5b 48 31 33 35 31 32 5d  H13509] [H13512]
1c280 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 33 35 31   [H13515] [H1351
1c290 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48 31 33  8] [H13521] [H13
1c2a0 35 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a 2a 2a  524] [H13527].**
1c2b0 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 33 35 33   [H13530] [H1353
1c2c0 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48 31 33  3] [H13536] [H13
1c2d0 35 33 39 5d 20 5b 48 31 33 35 34 32 5d 20 5b 48  539] [H13542] [H
1c2e0 31 33 35 34 35 5d 20 5b 48 31 33 35 34 38 5d 20  13545] [H13548] 
1c2f0 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69  [H13551].**.*/.i
1c300 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1c310 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
1c320 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
1c330 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
1c340 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1c350 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
1c360 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
1c370 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
1c380 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c390 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
1c3a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
1c3b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c3c0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
1c3d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
1c3e0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
1c3f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
1c400 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
1c410 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
1c420 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
1c430 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c440 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1c450 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1c460 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1c470 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
1c480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1c490 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
1c4a0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
1c4b0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1c4c0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
1c4d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c4e0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
1c4f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
1c500 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1c510 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1c520 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
1c530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1c540 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
1c550 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d  ameters {H13600}
1c560 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
1c570 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
1c580 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
1c590 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
1c5a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
1c5b0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
1c5c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
1c5d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1c5e0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1c5f0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1c600 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1c610 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1c620 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1c630 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1c640 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
1c650 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1c660 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
1c670 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1c680 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
1c690 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
1c6a0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
1c6b0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
1c6c0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
1c6d0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
1c6e0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
1c6f0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
1c700 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
1c710 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
1c720 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
1c730 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
1c740 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
1c750 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
1c760 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
1c770 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
1c780 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
1c790 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1c7a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1c7b0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1c7c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1c7d0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
1c7e0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1c7f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1c800 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  ndex()]..**.** R
1c810 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1c820 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13601].*/.int 
1c830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1c840 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
1c850 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1c860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
1c870 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
1c880 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20  ameter {H13620} 
1c890 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
1c8a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
1c8b0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c8c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1c8d0 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61   n-th.** [SQL pa
1c8e0 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70  rameter] in a [p
1c8f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c900 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  t]..** SQL param
1c910 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1c920 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
1c930 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
1c940 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
1c950 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
1c960 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
1c970 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
1c980 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
1c990 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
1c9a0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
1c9b0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
1c9c0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
1c9d0 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
1c9e0 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
1c9f0 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50  f the name..** P
1ca00 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1ca10 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
1ca20 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
1ca30 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
1ca40 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c  me.** and are al
1ca50 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  so referred to a
1ca60 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  s "anonymous par
1ca70 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
1ca80 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
1ca90 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1caa0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
1cab0 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
1cac0 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
1cad0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
1cae0 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
1caf0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
1cb00 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
1cb10 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
1cb20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
1cb30 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
1cb40 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
1cb50 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
1cb60 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
1cb70 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
1cb80 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
1cb90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1cba0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
1cbb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1cbc0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
1cbd0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1cbe0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1cbf0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1cc00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1cc10 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
1cc20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1cc30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1cc40 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  ndex()]..**.** R
1cc50 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1cc60 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f 6e 73  [H13621].*/.cons
1cc70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1cc80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1cc90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1cca0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
1ccb0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
1ccc0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
1ccd0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
1cce0 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30   {H13640} <S7030
1ccf0 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
1cd00 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
1cd10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
1cd20 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54  ven its name.  T
1cd30 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
1cd40 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
1cd50 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
1cd60 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
1cd70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1cd80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1cd90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
1cda0 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72    A zero.** is r
1cdb0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
1cdc0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
1cdd0 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20   is found.  The 
1cde0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
1cdf0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
1ce00 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
1ce10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1ce20 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
1ce30 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
1ce40 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
1ce50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ce60 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1ce70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1ce80 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1ce90 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1cea0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1ceb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1cec0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1ced0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1cee0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1cef0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1cf00 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a 69 6e  * [H13641].*/.in
1cf10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1cf20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
1cf30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
1cf40 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
1cf50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cf60 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
1cf70 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
1cf80 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
1cf90 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13660} <S70300>.
1cfa0 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74  **.** Contrary t
1cfb0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
1cfc0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
1cfd0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
1cfe0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
1cff0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1d000 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
1d010 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
1d020 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73  tatement]..** Us
1d030 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
1d040 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
1d050 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
1d060 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ULL..**.** Requi
1d070 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1d080 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  661].*/.int sqli
1d090 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1d0a0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
1d0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d0c0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
1d0d0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
1d0e0 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c  t Set {H13710} <
1d0f0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
1d100 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
1d110 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
1d120 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
1d130 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
1d140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d150 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69  ent]. This routi
1d160 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
1d170 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
1d180 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
1d190 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
1d1a0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
1d1b0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
1d1c0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1d1d0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 31 31  ents:.** [H13711
1d1e0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1d1f0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
1d200 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1d210 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1d220 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
1d230 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
1d240 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37  t {H13720} <S107
1d250 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
1d260 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1d270 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
1d280 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
1d290 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
1d2a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
1d2b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1d2c0 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
1d2d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1d2e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
1d2f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1d300 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
1d310 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1d320 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
1d330 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1d340 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1d350 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
1d360 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1d370 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
1d380 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1d390 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
1d3a0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
1d3b0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
1d3c0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
1d3d0 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e  ement. The secon
1d3e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1d3f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
1d400 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ber.  The leftmo
1d410 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
1d420 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 0..**.** The
1d430 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1d440 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
1d450 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
1d460 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1d470 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
1d480 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1d490 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1d4a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
1d4b0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
1d4c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1d4d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
1d4e0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
1d4f0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1d500 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
1d510 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
1d520 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
1d530 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
1d540 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
1d550 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
1d560 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
1d570 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
1d580 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
1d590 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1d5a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1d5b0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1d5c0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1d5d0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1d5e0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1d5f0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1d600 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1d610 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1d620 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1d630 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1d640 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1d650 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1d660 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1d670 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1d680 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1d690 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
1d6a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1d6b0 20 5b 48 31 33 37 32 31 5d 20 5b 48 31 33 37 32   [H13721] [H1372
1d6c0 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48 31 33  3] [H13724] [H13
1d6d0 37 32 35 5d 20 5b 48 31 33 37 32 36 5d 20 5b 48  725] [H13726] [H
1d6e0 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13727].*/.const 
1d6f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1d700 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
1d710 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
1d720 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1d730 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1d740 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1d750 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
1d760 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
1d770 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
1d780 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
1d790 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  740} <S10700>.**
1d7a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d7b0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
1d7c0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
1d7d0 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
1d7e0 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
1d7f0 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
1d800 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45   result of a [SE
1d810 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1d820 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54  comes from..** T
1d830 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1d840 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
1d850 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
1d860 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
1d870 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
1d880 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
1d890 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
1d8a0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1d8b0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1d8c0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
1d8d0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
1d8e0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
1d8f0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
1d900 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
1d910 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
1d920 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
1d930 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1d940 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
1d950 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1d960 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
1d970 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
1d980 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1d990 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
1d9a0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1d9b0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
1d9c0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
1d9d0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
1d9e0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
1d9f0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
1da00 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
1da10 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
1da20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
1da30 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
1da40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1da50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1da60 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
1da70 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
1da80 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
1da90 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
1daa0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
1dab0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
1dac0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
1dad0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
1dae0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
1daf0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
1db00 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
1db10 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
1db20 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1db30 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
1db40 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
1db50 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
1db60 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
1db70 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
1db80 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
1db90 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
1dba0 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
1dbb0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
1dbc0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
1dbd0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1dbe0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
1dbf0 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
1dc00 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
1dc10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
1dc20 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
1dc30 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c  table.** and col
1dc40 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
1dc50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
1dc60 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
1dc70 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
1dc80 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
1dc90 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
1dca0 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
1dcb0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
1dcc0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
1dcd0 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
1dce0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
1dcf0 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
1dd00 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
1dd10 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
1dd20 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
1dd30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
1dd40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
1dd50 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
1dd60 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
1dd70 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
1dd80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37  ned..**.** {A137
1dd90 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
1dda0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1ddb0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
1ddc0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1ddd0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
1dde0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
1ddf0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
1de00 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
1de10 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
1de20 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
1de30 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  fined..**.** Req
1de40 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1de50 31 33 37 34 31 5d 20 5b 48 31 33 37 34 32 5d 20  13741] [H13742] 
1de60 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 37 34 34  [H13743] [H13744
1de70 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 31 33 37  ] [H13745] [H137
1de80 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a 2a 0a  46] [H13748].**.
1de90 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
1dea0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
1deb0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
1dec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1ded0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
1dee0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
1def0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
1df00 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
1df10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
1df20 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
1df30 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
1df40 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
1df50 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1df60 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
1df70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1df80 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1df90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1dfa0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1dfb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1dfc0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
1dfd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1dfe0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1dff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1e000 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
1e010 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1e020 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1e030 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1e040 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1e050 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1e060 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1e070 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1e080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e090 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1e0a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1e0b0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
1e0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e0d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e0e0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
1e0f0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
1e100 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20  Result {H13760} 
1e110 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1e120 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1e130 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
1e140 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1e150 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
1e160 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
1e170 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1e180 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1e190 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
1e1a0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
1e1b0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
1e1c0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
1e1d0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
1e1e0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1e1f0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
1e200 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
1e210 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
1e220 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66  is returned.  If
1e230 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1e240 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
1e250 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
1e260 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
1e270 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
1e280 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
1e290 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  ed..** The retur
1e2a0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
1e2b0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
1e2c0 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ed. {END}.**.** 
1e2d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
1e2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e2f0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
1e300 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
1e310 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
1e320 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
1e330 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
1e340 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
1e350 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
1e360 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
1e370 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1e380 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
1e390 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
1e3a0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
1e3b0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
1e3c0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
1e3d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1e3e0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
1e3f0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
1e400 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
1e410 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
1e420 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
1e430 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
1e440 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
1e450 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
1e460 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
1e470 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
1e480 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
1e490 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
1e4a0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
1e4b0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
1e4c0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
1e4d0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
1e4e0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
1e4f0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
1e500 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
1e510 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1e520 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
1e530 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
1e540 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
1e550 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
1e560 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  e values..**.** 
1e570 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1e580 20 5b 48 31 33 37 36 31 5d 20 5b 48 31 33 37 36   [H13761] [H1376
1e590 32 5d 20 5b 48 31 33 37 36 33 5d 0a 2a 2f 0a 63  2] [H13763].*/.c
1e5a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1e5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
1e5c0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
1e5d0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1e5e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1e5f0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
1e600 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1e610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e620 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
1e630 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  L Statement {H13
1e640 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  200} <S10000>.**
1e650 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
1e660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e670 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
1e680 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
1e690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e6a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1e6b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e6c0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
1e6d0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
1e6e0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
1e6f0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1e700 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e710 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
1e720 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
1e730 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
1e740 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
1e750 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
1e760 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
1e770 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
1e780 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
1e790 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
1e7a0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
1e7b0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
1e7c0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
1e7d0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
1e7e0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
1e7f0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
1e800 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1e810 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1e820 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
1e830 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
1e840 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
1e850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e860 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1e870 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
1e880 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
1e890 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
1e8a0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
1e8b0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
1e8c0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
1e8d0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
1e8e0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
1e8f0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
1e900 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
1e910 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
1e920 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1e930 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
1e940 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
1e950 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
1e960 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
1e970 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
1e980 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
1e990 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  ]..** With the "
1e9a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
1e9b0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
1e9c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
1e9d0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
1e9e0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
1e9f0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
1ea00 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  s well..**.** [S
1ea10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
1ea20 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
1ea30 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
1ea40 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
1ea50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1ea60 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
1ea70 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
1ea80 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
1ea90 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
1eaa0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
1eab0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
1eac0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1ead0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
1eae0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
1eaf0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
1eb00 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
1eb10 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
1eb20 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
1eb30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1eb40 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
1eb50 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
1eb60 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
1eb70 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
1eb80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
1eb90 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
1eba0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
1ebb0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
1ebc0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
1ebd0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
1ebe0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
1ebf0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
1ec00 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
1ec10 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
1ec20 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
1ec30 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
1ec40 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
1ec50 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
1ec60 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
1ec70 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
1ec80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
1ec90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
1eca0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
1ecb0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
1ecc0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
1ecd0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
1ece0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
1ecf0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
1ed00 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
1ed10 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
1ed20 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
1ed30 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
1ed40 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
1ed50 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
1ed60 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
1ed70 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
1ed80 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
1ed90 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
1eda0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b  of data..**.** [
1edb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
1edc0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
1edd0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
1ede0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
1edf0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
1ee00 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
1ee10 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
1ee20 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
1ee30 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
1ee40 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
1ee50 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
1ee60 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
1ee70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1ee80 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
1ee90 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
1eea0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
1eeb0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
1eec0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
1eed0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
1eee0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
1eef0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
1ef00 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
1ef10 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
1ef20 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
1ef30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1ef40 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
1ef50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1ef60 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
1ef70 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
1ef80 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
1ef90 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
1efa0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
1efb0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
1efc0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
1efd0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
1efe0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
1eff0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
1f000 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
1f010 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
1f020 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
1f030 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f040 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
1f050 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
1f060 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
1f070 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
1f080 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
1f090 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1f0a0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
1f0b0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
1f0c0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
1f0d0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
1f0e0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
1f0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f100 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
1f110 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
1f120 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
1f130 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
1f140 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
1f150 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
1f160 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
1f170 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1f180 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
1f190 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
1f1a0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
1f1b0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
1f1c0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
1f1d0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
1f1e0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
1f1f0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
1f200 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
1f210 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
1f220 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
1f230 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
1f240 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1f250 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
1f260 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
1f270 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
1f280 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
1f290 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
1f2a0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
1f2b0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
1f2c0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
1f2d0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
1f2e0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
1f2f0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
1f300 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
1f310 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
1f320 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
1f330 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
1f340 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1f350 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1f360 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f370 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
1f380 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
1f390 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
1f3a0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
1f3b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f3c0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
1f3d0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
1f3e0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
1f3f0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
1f400 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
1f410 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
1f420 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
1f430 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
1f440 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
1f450 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1f460 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d 20  ts:.** [H13202] 
1f470 5b 48 31 35 33 30 34 5d 20 5b 48 31 35 33 30 36  [H15304] [H15306
1f480 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 33  ] [H15308] [H153
1f490 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  10].*/.int sqlit
1f4a0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
1f4b0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1f4c0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
1f4d0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
1f4e0 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37  result set {H137
1f4f0 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  70} <S10700>.**.
1f500 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e  ** Returns the n
1f510 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
1f520 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
1f530 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
1f540 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75   set..**.** Requ
1f550 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1f560 33 37 37 31 5d 20 5b 48 31 33 37 37 32 5d 0a 2a  3771] [H13772].*
1f570 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
1f580 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
1f590 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1f5a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f5b0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
1f5c0 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c  types {H10265} <
1f5d0 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a  S10110><S10120>.
1f5e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
1f5f0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b  ITE_TEXT.**.** {
1f600 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61  H10266} Every va
1f610 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
1f620 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
1f630 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
1f640 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
1f650 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
1f660 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
1f670 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
1f680 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
1f690 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
1f6a0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
1f6b0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
1f6c0 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
1f6d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
1f6e0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
1f6f0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
1f700 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
1f710 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
1f720 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
1f730 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
1f740 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
1f750 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
1f760 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
1f770 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
1f780 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
1f790 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
1f7a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
1f7b0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
1f7c0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
1f7d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
1f7e0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
1f7f0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
1f800 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
1f810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f820 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
1f830 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
1f840 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
1f850 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
1f860 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
1f870 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
1f880 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
1f890 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
1f8a0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
1f8b0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
1f8c0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
1f8d0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
1f8e0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
1f8f0 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31  ery {H13800} <S1
1f900 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0700>.** KEYWORD
1f910 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
1f920 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
1f930 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f940 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
1f950 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e  lt set query" in
1f960 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
1f970 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1f980 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
1f990 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
1f9a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
1f9b0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
1f9c0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
1f9d0 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74   In every case t
1f9e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1f9f0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
1fa00 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
1fa10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1fa20 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
1fa30 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
1fa40 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
1fa50 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
1fa60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
1fa70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
1fa80 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
1fa90 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
1faa0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1fab0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1fac0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
1fad0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
1fae0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
1faf0 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74  urned.  The left
1fb00 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
1fb10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
1fb20 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
1fb30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
1fb40 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1fb50 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
1fb60 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
1fb70 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
1fb80 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
1fb90 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
1fba0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
1fbb0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
1fbc0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
1fbd0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
1fbe0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1fbf0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
1fc00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
1fc10 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
1fc20 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
1fc30 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
1fc40 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
1fc50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1fc60 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
1fc70 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
1fc80 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
1fc90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1fca0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
1fcb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
1fcc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
1fcd0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
1fce0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
1fcf0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
1fd00 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
1fd10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1fd20 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
1fd30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
1fd40 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
1fd50 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
1fd60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
1fd70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1fd80 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
1fd90 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
1fda0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
1fdb0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
1fdc0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
1fdd0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
1fde0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
1fdf0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
1fe00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
1fe10 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
1fe20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
1fe30 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
1fe40 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
1fe50 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
1fe60 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
1fe70 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
1fe80 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
1fe90 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
1fea0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
1feb0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
1fec0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
1fed0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
1fee0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
1fef0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
1ff00 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1ff10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1ff20 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
1ff30 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
1ff40 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
1ff50 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
1ff60 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
1ff70 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
1ff80 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
1ff90 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
1ffa0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1ffb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
1ffc0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
1ffd0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
1ffe0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
1fff0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
20000 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
20010 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
20020 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
20030 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
20040 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
20050 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
20060 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
20070 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
20080 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
20090 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
200a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
200b0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
200c0 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68  string..** If th
200d0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
200e0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
200f0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
20100 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
20110 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
20120 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
20130 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
20140 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
20150 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
20160 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
20170 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
20180 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
20190 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
201a0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
201b0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
201c0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
201d0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
201e0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
201f0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
20200 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61  tring..** The va
20210 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65  lue returned doe
20220 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
20230 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
20240 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  r at the end.** 
20250 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
20260 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
20270 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
20280 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
20290 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
202a0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
202b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
202c0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72  cters..**.** Str
202d0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
202e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
202f0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
20300 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
20310 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
20320 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
20330 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
20340 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75  nated.  The retu
20350 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
20360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20370 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
20380 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
20390 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a   an arbitrary.**
203a0 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62   pointer, possib
203b0 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70  ly even a NULL p
203c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
203d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
203e0 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
203f0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
20400 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20410 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
20420 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
20430 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   in UTF-16 in na
20440 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
20450 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
20460 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65  ..** The zero te
20470 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
20480 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
20490 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68   count..**.** Th
204a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
204b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
204c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
204d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
204e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
204f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
20500 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
20510 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
20520 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
20530 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
20540 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
20550 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
20560 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
20570 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
20580 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20590 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
205a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
205b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
205c0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
205d0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
205e0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
205f0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
20600 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
20610 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
20620 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
20630 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
20640 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
20650 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20660 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
20670 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20680 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
20690 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
206a0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
206b0 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  te.  For.** exam
206c0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
206d0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
206e0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
206f0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
20700 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
20710 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
20720 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
20730 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
20740 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
20750 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
20760 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
20770 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
20780 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
20790 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
207a0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
207b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
207c0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
207d0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
207e0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
207f0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
20800 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
20810 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
20820 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20830 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
20840 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
20850 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
20860 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
20870 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
20880 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
20890 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
208a0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
208b0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
208c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
208d0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
208e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
208f0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
20900 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
20910 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
20920 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
20930 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
20940 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
20950 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
20960 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
20970 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
20980 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
20990 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
209a0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
209b0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
209c0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
209d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
209e0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
209f0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
20a00 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
20a10 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
20a20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
20a30 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20a40 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
20a50 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
20a60 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
20a70 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
20a80 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
20a90 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
20aa0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
20ab0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
20ac0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
20ad0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
20ae0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
20af0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
20b00 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20b10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
20b20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
20b30 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
20b40 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
20b50 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
20b60 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
20b70 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
20b80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
20b90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
20ba0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
20bb0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
20bc0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
20bd0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
20be0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20bf0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
20c00 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
20c10 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
20c20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
20c30 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
20c40 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
20c50 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
20c60 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
20c70 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
20c80 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
20c90 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
20ca0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
20cb0 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
20cc0 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
20cd0 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
20ce0 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
20cf0 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
20d00 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
20d10 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
20d20 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
20d30 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
20d40 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
20d50 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
20d60 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
20d70 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
20d80 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
20d90 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
20da0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
20db0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
20dc0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
20dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
20de0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
20df0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
20e00 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
20e10 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
20e20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
20e30 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
20e40 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
20e50 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
20e60 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
20e70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
20e80 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
20e90 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
20ea0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
20eb0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
20ec0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
20ed0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
20ee0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
20ef0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
20f00 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
20f10 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
20f20 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
20f30 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
20f40 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
20f50 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
20f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
20f70 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
20f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20f90 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
20fa0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
20fb0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
20fc0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
20fd0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
20fe0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
20ff0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
21000 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
21010 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
21020 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
21030 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
21040 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
21050 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
21060 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
21070 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
21080 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
21090 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74   Conversions bet
210a0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
210b0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
210c0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
210d0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
210e0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
210f0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
21100 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
21110 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
21120 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
21130 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
21140 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c  er points to wil
21150 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
21160 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
21170 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
21180 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
21190 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
211a0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
211b0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
211c0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
211d0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
211e0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
211f0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
21200 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
21210 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
21220 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
21230 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
21240 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
21250 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
21260 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
21270 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
21280 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
21290 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
212a0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
212b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
212c0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
212d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
212e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
212f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21300 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
21310 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
21320 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
21330 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
21340 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
21350 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
21360 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
21370 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
21380 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
21390 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
213a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
213b0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
213c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
213d0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
213e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
213f0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
21400 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
21410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21420 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
21430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21440 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
21450 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
21460 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
21470 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
21480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
21490 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
214a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
214b0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** 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 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
214e0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
214f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21500 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
21510 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
21520 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
21530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
21540 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
21550 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
21560 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
21570 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
21580 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
21590 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
215a0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
215b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
215c0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
215d0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
215e0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70  .  The memory sp
215f0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
21600 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
21610 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
21620 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
21630 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
21640 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
21650 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
21660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
21670 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
21680 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
21690 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
216a0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
216b0 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  * If a memory al
216c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
216d0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
216e0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
216f0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
21700 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
21710 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
21720 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
21730 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
21740 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
21750 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
21760 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
21770 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
21780 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
21790 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
217a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
217b0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
217c0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
217d0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
217e0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38 30 33  ents:.** [H13803
217f0 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48 31 33 38  ] [H13806] [H138
21800 30 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b 48 31  09] [H13812] [H1
21810 33 38 31 35 5d 20 5b 48 31 33 38 31 38 5d 20 5b  3815] [H13818] [
21820 48 31 33 38 32 31 5d 20 5b 48 31 33 38 32 34 5d  H13821] [H13824]
21830 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b 48 31  .** [H13827] [H1
21840 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76  3830].*/.const v
21850 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
21860 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
21870 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21880 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
21890 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
218a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
218b0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
218c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
218d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
218e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
218f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
21900 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
21910 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
21920 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
21930 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
21940 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21950 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
21960 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21970 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
21980 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
21990 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
219a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
219b0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
219c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
219d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
219e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
219f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
21a00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
21a10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
21a20 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
21a30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21a40 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
21a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
21a60 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
21a70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
21a80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21a90 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
21aa0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
21ab0 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37  ect {H13300} <S7
21ac0 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a  0300><S30100>.**
21ad0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21ae0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
21af0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
21b00 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
21b10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
21b20 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  ** If the statem
21b30 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64  ent was executed
21b40 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72   successfully or
21b50 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74   not executed at
21b60 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51   all, then.** SQ
21b70 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
21b80 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f  ned. If executio
21b90 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
21ba0 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61  nt failed then a
21bb0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
21bc0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
21bd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21be0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
21bf0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
21c00 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
21c10 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
21c20 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
21c30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
21c40 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74  tatement].  If t
21c50 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
21c60 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f  ne has not.** co
21c70 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
21c80 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
21c90 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
21ca0 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
21cb0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
21cc0 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  rror or an [sqli
21cd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
21ce0 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49  interrupt]..** I
21cf0 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
21d00 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
21d10 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
21d20 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a  tions canceled,.
21d30 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
21d40 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
21d50 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65  s, and the.** [e
21d60 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72  rror code] retur
21d70 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
21d80 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
21d90 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
21da0 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 31  ** [H11302] [H11
21db0 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  304].*/.int sqli
21dc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
21dd0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
21de0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21df0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
21e00 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
21e10 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c  bject {H13330} <
21e20 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
21e30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
21e40 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
21e50 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
21e60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21e70 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
21e80 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
21e90 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
21ea0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
21eb0 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74  d..** Any SQL st
21ec0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
21ed0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
21ee0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
21ef0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
21f00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
21f10 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
21f20 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
21f30 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
21f40 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
21f50 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
21f60 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
21f70 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ings..**.** {H11
21f80 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  332} The [sqlite
21f90 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
21fa0 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
21fb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21fc0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20  ment] S.**      
21fd0 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20      back to the 
21fe0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
21ff0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
22000 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20  {H11334} If the 
22010 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
22020 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
22030 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
22040 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
22050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22060 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
22070 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
22080 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
22090 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
220a0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
220b0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
220c0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
220d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
220e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
220f0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
22100 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
22110 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  H11336} If the m
22120 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
22130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
22140 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
22150 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22160 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
22170 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
22180 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  or, then.**     
22190 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
221a0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
221b0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
221c0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
221d0 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20  ** {H11338} The 
221e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
221f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
22200 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
22210 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
22220 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69      of any [sqli
22230 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
22240 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
22250 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22260 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
22270 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
22280 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
222a0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
222b0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
222c0 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32  ons {H16100} <S2
222d0 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
222e0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
222f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
22300 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
22310 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
22320 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
22330 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
22340 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
22350 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
22360 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f  .**.** These two
22370 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
22380 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
22390 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
223a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
223b0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
223c0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
223d0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
223e0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
223f0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
22400 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
22410 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
22420 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
22430 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
22440 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69  een the.** two i
22450 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
22460 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
22470 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
22480 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
22490 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20  r.** aggregate, 
224a0 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
224b0 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  F-8 for sqlite3_
224c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
224d0 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20  ) and UTF-16.** 
224e0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
224f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
22500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
22510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22520 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
22530 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
22540 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
22550 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
22560 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c  ded.  If a singl
22570 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d  e program uses m
22580 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
22590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
225a0 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  ion internally, 
225b0 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  then SQL functio
225c0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
225d0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f   individually to
225e0 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73  .** each databas
225f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
22600 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
22610 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
22620 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
22630 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
22640 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
22650 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e  efined.  The len
22660 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
22670 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
22680 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
22690 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72  ve of.** the zer
226a0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e  o-terminator.  N
226b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
226c0 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  e length limit i
226d0 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a  s in bytes, not.
226e0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ** characters.  
226f0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
22700 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
22710 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
22720 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
22730 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52  lt in [SQLITE_ER
22740 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72  ROR] being retur
22750 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ned..**.** The t
22760 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
22770 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
22780 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
22790 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
227a0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
227b0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
227c0 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
227d0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
227e0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
227f0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
22800 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
22810 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
22820 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
22830 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22840 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
22850 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
22860 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
22870 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
22880 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
22890 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
228a0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
228b0 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
228c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
228d0 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
228e0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
228f0 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
22900 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
22910 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
22920 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
22930 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
22940 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
22950 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
22960 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
22970 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
22980 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
22990 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
229a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
229b0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
229c0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
229d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
229e0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
229f0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
22a00 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
22a10 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
22a20 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
22a30 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
22a40 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
22a50 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
22a60 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
22a70 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
22a80 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
22a90 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
22aa0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
22ab0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
22ac0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
22ad0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
22ae0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
22af0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
22b00 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
22b10 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
22b20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
22b30 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
22b40 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
22b50 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
22b60 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
22b70 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
22b80 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
22b90 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
22ba0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
22bb0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
22bc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
22bd0 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
22be0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
22bf0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
22c00 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
22c10 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
22c20 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
22c30 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
22c40 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
22c50 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
22c60 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
22c70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
22c80 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
22c90 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
22ca0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
22cb0 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
22cc0 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
22cd0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
22ce0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
22cf0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
22d00 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
22d10 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
22d20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
22d30 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
22d40 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
22d50 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
22d60 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
22d70 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
22d80 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
22d90 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
22da0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
22db0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
22dc0 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
22dd0 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
22de0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
22df0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
22e00 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
22e10 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
22e20 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
22e30 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
22e40 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
22e50 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
22e60 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
22e70 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
22e80 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
22e90 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
22ea0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
22eb0 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
22ec0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
22ed0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
22ee0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
22ef0 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74  s used.  A funct
22f00 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
22f10 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
22f20 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
22f30 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
22f40 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
22f50 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
22f60 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
22f70 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
22f80 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77  g.  A function w
22f90 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
22fa0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
22fb0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
22fc0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
22fd0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
22fe0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
22ff0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
23000 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
23010 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66  ferent.  .** A f
23020 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
23030 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
23040 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
23050 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
23060 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
23070 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
23080 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
23090 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
230a0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
230b0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
230c0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c  TF16..**.** Buil
230d0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
230e0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
230f0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
23100 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
23110 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69  tions..** The fi
23120 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
23130 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
23140 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
23150 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
23160 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
23170 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
23180 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
23190 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
231a0 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
231b0 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69  Subsequent appli
231c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
231d0 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  unctions of the 
231e0 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f  same name only o
231f0 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f  verride .** prio
23200 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  r application-de
23210 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
23220 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63  that are an exac
23230 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a  t match for the.
23240 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  ** number of par
23250 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66  ameters and pref
23260 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a  erred encoding..
23270 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61  **.** An applica
23280 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
23290 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
232a0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
232b0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
232c0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
232d0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
232e0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
232f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23300 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
23310 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
23320 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
23330 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
23340 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
23350 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65  unning..**.** Re
23360 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
23370 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30 36 5d  H16103] [H16106]
23380 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 31 31   [H16109] [H1611
23390 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 31 36  2] [H16118] [H16
233a0 31 32 31 5d 20 5b 48 31 36 31 32 34 5d 20 5b 48  121] [H16124] [H
233b0 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33  16127].** [H1613
233c0 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36  0] [H16133] [H16
233d0 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48  136] [H16139] [H
233e0 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16142].*/.int sq
233f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
23400 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
23410 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
23420 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
23430 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
23440 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
23450 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
23460 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
23470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
23480 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
23490 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
234a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
234b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
234c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
234d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
234e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
234f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
23500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
23510 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
23520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
23530 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
23540 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
23550 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
23560 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
23570 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
23580 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
23590 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
235a0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
235b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
235c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
235d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
235e0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
235f0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
23600 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
23610 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36  Encodings {H1026
23620 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36  7} <S50200> <H16
23630 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
23640 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
23650 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
23660 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
23670 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
23680 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
23690 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
236a0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
236b0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
236c0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
236d0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
236e0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
236f0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
23700 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
23710 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
23720 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
23730 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
23740 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23750 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
23760 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
23770 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23780 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
23790 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
237a0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
237b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
237c0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
237d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
237e0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
237f0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
23800 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
23810 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
23820 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
23830 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
23840 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
23850 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
23860 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
23870 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
23880 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
23890 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
238a0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
238b0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
238c0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
238d0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
238e0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
238f0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
23900 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
23910 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
23920 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
23930 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
23940 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
23950 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
23960 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
23970 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
23980 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
23990 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
239a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
239b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
239c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
239d0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
239e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
239f0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
23a00 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
23a10 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
23a20 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
23a30 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23a40 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
23a50 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
23a60 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
23a70 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
23a80 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
23a90 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
23aa0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
23ab0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
23ac0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
23ad0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
23ae0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
23af0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
23b00 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
23b10 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
23b20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
23b30 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48  ameter Values {H
23b40 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15100} <S20200>.
23b50 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
23b60 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
23b70 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
23b80 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
23b90 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
23ba0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
23bb0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
23bc0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
23bd0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
23be0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
23bf0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
23c00 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
23c10 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
23c20 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
23c30 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
23c40 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
23c50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
23c60 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
23c70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
23c80 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
23c90 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
23ca0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
23cb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
23cc0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
23cd0 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
23ce0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
23cf0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
23d00 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
23d10 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
23d20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
23d30 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
23d40 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
23d50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
23d60 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
23d70 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
23d80 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
23d90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
23da0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
23db0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
23dc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
23dd0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
23de0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
23df0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
23e00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23e10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
23e20 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
23e30 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
23e40 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
23e50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23e60 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
23e70 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
23e80 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
23e90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
23ea0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
23eb0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
23ec0 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
23ed0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
23ee0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
23ef0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
23f00 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
23f10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23f20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
23f30 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
23f40 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
23f50 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
23f60 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
23f70 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
23f80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
23f90 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
23fa0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
23fb0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
23fc0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
23fd0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
23fe0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
23ff0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
24000 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
24010 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
24020 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
24030 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
24040 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
24050 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
24060 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
24070 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
24080 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24090 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
240a0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
240b0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
240c0 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
240d0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
240e0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
240f0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
24100 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
24110 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
24120 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
24130 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
24140 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
24150 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
24160 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
24170 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
24180 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
24190 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
241a0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
241b0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
241c0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
241d0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
241e0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
241f0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
24200 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
24210 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
24220 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
24230 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
24240 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
24250 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
24260 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
24270 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
24280 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
24290 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
242a0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
242b0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
242c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
242d0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
242e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
242f0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
24300 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
24310 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
24320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
24330 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
24340 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
24350 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
24360 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
24370 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
24380 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
24390 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
243a0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
243b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
243c0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
243d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
243e0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
243f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
24400 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
24410 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
24420 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b  s:.** [H15103] [
24430 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d  H15106] [H15109]
24440 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31   [H15112] [H1511
24450 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35  5] [H15118] [H15
24460 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a  121] [H15124].**
24470 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33   [H15127] [H1513
24480 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35  0] [H15133] [H15
24490 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  136].*/.const vo
244a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
244b0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
244c0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
244d0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
244e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
244f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
24500 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
24510 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
24520 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
24530 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
24540 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
24550 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
24560 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24570 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
24580 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
24590 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
245a0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
245b0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
245c0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
245d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
245e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
245f0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
24600 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
24610 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24620 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
24630 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24640 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24650 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24660 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
24670 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
24680 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
24690 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
246a0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
246b0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
246c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
246d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
246e0 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
246f0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
24700 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30   {H16210} <S2020
24710 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0>.**.** The imp
24720 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
24730 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
24740 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
24750 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
24760 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
24770 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
24780 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
24790 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
247a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
247b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
247c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
247d0 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74  ed for a.** part
247e0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
247f0 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
24800 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
24810 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
24820 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  that.** memory, 
24830 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
24840 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20  inter to it. On 
24850 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
24860 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
24870 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
24880 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
24890 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
248a0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
248b0 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  dex,.** the same
248c0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
248d0 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  ned. The impleme
248e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61  ntation of the a
248f0 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
24900 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64  .** the returned
24910 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d   buffer to accum
24920 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ulate data..**.*
24930 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  * SQLite automat
24940 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
24950 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65   allocated buffe
24960 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  r when the aggre
24970 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
24980 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
24990 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
249a0 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
249b0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
249c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
249d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
249e0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
249f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24a00 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
24a10 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
24a20 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
24a30 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
24a40 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
24a50 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
24a60 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
24a70 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
24a80 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
24a90 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
24aa0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
24ab0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
24ac0 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20  ts:.** [H16211] 
24ad0 5b 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35  [H16213] [H16215
24ae0 5d 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f  ] [H16217].*/.vo
24af0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
24b00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
24b10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
24b20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
24b30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
24b40 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
24b50 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
24b60 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
24b70 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
24b80 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
24b90 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
24ba0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
24bb0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
24bc0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
24bd0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
24be0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
24bf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
24c00 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
24c10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
24c20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
24c30 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
24c40 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
24c50 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
24c60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
24c70 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
24c80 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
24c90 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
24ca0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
24cb0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
24cc0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
24cd0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
24ce0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
24cf0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
24d00 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a  ts:.** [H16243].
24d10 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
24d20 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
24d30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
24d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
24d50 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
24d60 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
24d70 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30   {H16250} <S6060
24d80 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20200>.**.**
24d90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
24da0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
24db0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24dc0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
24dd0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
24de0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
24df0 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
24e00 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
24e10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
24e20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
24e30 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
24e40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24e50 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
24e60 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
24e70 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
24e80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
24e90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
24ea0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
24eb0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d  nts:.** [H16253]
24ec0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
24ed0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
24ee0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
24ef0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
24f00 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
24f10 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
24f20 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30  ta {H16270} <S20
24f30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  200>.**.** The f
24f40 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
24f50 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
24f60 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
24f70 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
24f80 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
24f90 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
24fa0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
24fb0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
24fc0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
24fd0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
24fe0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
24ff0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
25000 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
25010 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
25020 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
25030 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
25040 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
25050 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
25060 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
25070 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
25080 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
25090 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
250a0 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
250b0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
250c0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
250d0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
250e0 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
250f0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
25100 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
25110 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
25120 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
25130 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
25140 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
25150 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
25160 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
25170 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
25180 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
25190 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
251a0 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
251b0 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
251c0 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
251d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
251e0 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
251f0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
25200 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25210 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
25220 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25230 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25240 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
25250 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
25260 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25270 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
25280 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
25290 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
252a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
252b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
252c0 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  n. If no metadat
252d0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
252e0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
252f0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
25300 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
25310 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
25320 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
25330 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
25340 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
25350 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
25360 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
25370 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
25380 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
25390 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
253a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
253b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
253c0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
253d0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
253e0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
253f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
25400 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
25410 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
25420 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
25430 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25440 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
25450 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
25460 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
25470 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
25480 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
25490 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
254a0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
254b0 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20  ed..** If it is 
254c0 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
254d0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
254e0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
254f0 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
25500 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
25510 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
25520 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
25530 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
25540 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
25550 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
25560 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
25570 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
25580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
25590 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
255a0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
255b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
255c0 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
255d0 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
255e0 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
255f0 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
25600 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
25610 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
25620 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
25630 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
25640 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
25650 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
25660 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
25670 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
25680 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
25690 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
256a0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
256b0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
256c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
256d0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
256e0 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
256f0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
25700 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
25710 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
25720 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
25730 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
25740 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
25750 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
25760 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
25770 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
25780 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
25790 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
257a0 31 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20  16272] [H16274] 
257b0 5b 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37  [H16276] [H16277
257c0 5d 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32  ] [H16278] [H162
257d0 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  79].*/.void *sql
257e0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
257f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25800 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
25810 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25820 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
25830 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
25840 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
25850 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
25860 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
25870 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
25880 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
25890 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
258a0 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
258b0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
258c0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
258d0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
258e0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
258f0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
25900 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
25910 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
25920 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
25930 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
25940 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
25950 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
25960 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
25970 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
25980 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
25990 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
259a0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
259b0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
259c0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
259d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
259e0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
259f0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
25a00 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
25a10 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
25a20 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
25a30 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
25a40 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
25a50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
25a60 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
25a70 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
25a80 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
25a90 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
25aa0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
25ab0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
25ac0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
25ad0 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
25ae0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
25af0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
25b00 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
25b10 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
25b20 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
25b30 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
25b40 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
25b50 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
25b60 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
25b70 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
25b80 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
25b90 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
25ba0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
25bb0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
25bc0 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
25bd0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
25be0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
25bf0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
25c00 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
25c10 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
25c20 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
25c30 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
25c40 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
25c50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25c60 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
25c70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25c80 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
25c90 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
25ca0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
25cb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
25cc0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
25cd0 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
25ce0 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
25cf0 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
25d00 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
25d10 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
25d20 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
25d30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
25d40 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
25d50 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
25d60 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
25d70 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
25d80 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
25d90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
25da0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
25db0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
25dc0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
25dd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25de0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
25df0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
25e00 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
25e10 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
25e20 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
25e30 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
25e40 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
25e50 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
25e60 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
25e70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25e80 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
25e90 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
25ea0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
25eb0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
25ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
25ed0 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
25ee0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
25ef0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
25f00 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
25f10 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
25f20 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
25f30 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
25f40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25f50 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
25f60 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
25f70 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
25f80 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
25f90 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25fa0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
25fb0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
25fc0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
25fd0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
25fe0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25ff0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26000 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
26010 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
26020 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
26030 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
26040 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
26050 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
26060 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
26070 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
26080 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
26090 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
260a0 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
260b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
260c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
260d0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
260e0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
260f0 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
26100 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
26110 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
26120 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
26130 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26140 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
26150 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
26160 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
26170 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
26180 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
26190 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
261a0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
261b0 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
261c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
261d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
261e0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
261f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26200 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
26210 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
26220 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
26230 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
26240 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
26250 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
26260 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
26270 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
26280 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
26290 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
262a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
262b0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
262c0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
262d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
262e0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
262f0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
26300 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
26310 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
26320 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
26330 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26340 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
26350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26360 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
26370 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
26380 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
26390 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
263a0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
263b0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
263c0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
263d0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
263e0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
263f0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
26400 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
26410 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
26420 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26430 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
26440 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
26450 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
26460 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
26470 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
26480 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
26490 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
264a0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
264b0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
264c0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
264d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
264e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
264f0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
26500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26510 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
26520 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
26530 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
26540 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26550 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
26560 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
26570 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
26580 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
26590 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
265a0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
265b0 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
265c0 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
265d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
265e0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
265f0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
26600 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
26610 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
26620 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
26630 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
26640 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26650 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
26660 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
26670 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
26680 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
26690 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
266a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
266b0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
266c0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
266d0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
266e0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
266f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26700 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
26710 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
26720 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
26730 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26740 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26750 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
26760 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
26770 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
26780 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
26790 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
267a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
267b0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
267c0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
267d0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
267e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
267f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26800 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
26810 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26820 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
26830 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
26840 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
26850 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
26860 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
26870 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
26880 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
26890 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
268a0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
268b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
268c0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
268d0 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
268e0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
268f0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
26900 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
26910 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
26920 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
26930 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
26940 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
26950 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
26960 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
26970 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
26980 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
26990 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
269a0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
269b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
269c0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
269d0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
269e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
269f0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
26a00 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
26a10 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
26a20 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
26a30 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
26a40 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
26a50 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
26a60 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
26a70 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
26a80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26a90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26aa0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
26ab0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
26ac0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
26ad0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
26ae0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
26af0 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
26b00 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
26b10 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
26b20 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
26b30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
26b40 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
26b50 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
26b60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
26b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26b80 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
26b90 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
26ba0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
26bb0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
26bc0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
26bd0 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
26be0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
26bf0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
26c00 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
26c10 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
26c20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
26c30 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
26c40 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
26c50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
26c60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
26c70 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a  interfaces or.**
26c80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26c90 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
26ca0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
26cb0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
26cc0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
26cd0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
26ce0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
26cf0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
26d00 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
26d10 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74  t.** copy the it
26d20 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
26d30 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
26d40 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
26d50 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
26d60 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
26d70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
26d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
26d90 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
26da0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
26db0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
26dc0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
26dd0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
26de0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
26df0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
26e00 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
26e10 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
26e20 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
26e30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
26e40 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
26e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26e60 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26e70 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
26e80 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
26e90 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
26ea0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26eb0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
26ec0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
26ed0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26ee0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
26ef0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
26f00 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
26f10 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
26f20 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
26f30 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
26f40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
26f50 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
26f60 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
26f70 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
26f80 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
26f90 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
26fa0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
26fb0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
26fc0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
26fd0 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
26fe0 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
26ff0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27000 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
27010 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
27020 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
27030 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27040 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
27050 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
27060 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
27070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27080 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
27090 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
270a0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
270b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
270c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
270d0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
270e0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
270f0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
27100 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
27110 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
27120 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
27130 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
27140 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
27150 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
27160 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
27170 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
27180 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d  nts:.** [H16403]
27190 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30   [H16406] [H1640
271a0 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36  9] [H16412] [H16
271b0 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48  415] [H16418] [H
271c0 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a  16421] [H16424].
271d0 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36  ** [H16427] [H16
271e0 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48  430] [H16433] [H
271f0 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20  16436] [H16439] 
27200 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35  [H16442] [H16445
27210 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48  ] [H16448].** [H
27220 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20  16451] [H16454] 
27230 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30  [H16457] [H16460
27240 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f  ] [H16463].*/.vo
27250 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27260 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
27270 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27280 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
27290 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
272a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
272b0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
272c0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
272d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
272e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
272f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27300 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
27310 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27320 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
27330 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
27340 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
27350 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27360 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
27370 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
27380 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
27390 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
273a0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
273b0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
273c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
273d0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
273e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
273f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27400 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
27410 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
27420 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27430 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
27440 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
27450 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
27460 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27470 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
27480 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
27490 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
274a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
274b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
274c0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
274d0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
274e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
274f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27500 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
27510 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27520 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27530 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27540 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
27550 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
27560 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
27570 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
27580 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
27590 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
275a0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
275b0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
275c0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
275d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
275e0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
275f0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
27600 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
27610 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
27620 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
27630 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
27640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
27650 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
27660 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36  g Sequences {H16
27670 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  600} <S20300>.**
27680 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
27690 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
276a0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
276b0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
276c0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
276d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
276e0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
276f0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
27700 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
27710 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
27720 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
27730 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
27740 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
27750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27760 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
27770 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27780 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
27790 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
277a0 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
277b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
277c0 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
277d0 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
277e0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
277f0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
27800 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
27810 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
27820 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
27830 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
27840 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
27850 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
27860 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
27870 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
27880 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
27890 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
278a0 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
278b0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
278c0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
278d0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
278e0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
278f0 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
27900 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
27910 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
27920 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
27930 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
27940 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
27950 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
27960 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
27970 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
27980 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
27990 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
279a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
279b0 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
279c0 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
279d0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
279e0 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
279f0 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
27a00 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
27a10 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
27a20 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
27a30 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
27a40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
27a50 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
27a60 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
27a70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
27a80 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
27a90 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
27aa0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
27ab0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
27ac0 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
27ad0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
27ae0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
27af0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
27b00 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
27b10 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
27b20 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
27b30 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
27b40 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
27b50 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
27b60 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
27b70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
27b80 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
27b90 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
27ba0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
27bb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27bc0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
27bd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27be0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
27bf0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
27c00 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
27c10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
27c20 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
27c30 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
27c40 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
27c50 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
27c60 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
27c70 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
27c80 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
27c90 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
27ca0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
27cb0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
27cc0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
27cd0 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
27ce0 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c   {END}  The appl
27cf0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
27d00 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
27d10 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
27d20 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
27d30 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
27d40 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
27d50 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
27d60 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
27d70 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
27d80 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
27d90 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
27da0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
27db0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
27dc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27dd0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
27de0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
27df0 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
27e00 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
27e10 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
27e20 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
27e30 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
27e40 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
27e50 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
27e60 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
27e70 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
27e80 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
27e90 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
27ea0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
27eb0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
27ec0 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
27ed0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27ee0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
27ef0 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
27f00 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
27f10 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
27f20 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
27f30 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
27f40 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
27f50 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
27f60 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
27f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
27f80 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
27f90 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
27fa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
27fb0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
27fc0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
27fd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
27fe0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
27ff0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
28000 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36  ements:.** [H166
28010 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31  03] [H16604] [H1
28020 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b  6606] [H16609] [
28030 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d  H16612] [H16615]
28040 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32   [H16618] [H1662
28050 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b  1].** [H16624] [
28060 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d  H16627] [H16630]
28070 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28080 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
28090 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
280a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
280b0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
280c0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
280d0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
280e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
280f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28100 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
28110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28120 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
28130 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
28140 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
28150 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
28160 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
28170 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
28180 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
28190 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
281a0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
281b0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
281c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
281d0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
281e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
281f0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
28200 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
28210 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
28220 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
28230 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
28240 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
28250 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
28260 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
28270 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
28280 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30  {H16700} <S20300
28290 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  >.**.** To avoid
282a0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
282b0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
282c0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
282d0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
282e0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
282f0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
28300 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
28310 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
28320 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
28330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
28340 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
28350 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
28360 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
28370 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
28380 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
28390 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
283a0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
283b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
283c0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
283d0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
283e0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
283f0 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
28400 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
28410 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
28420 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
28430 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {H16703} If sql
28440 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
28450 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
28460 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
28470 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
28480 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
28490 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
284a0 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
284b0 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
284c0 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
284d0 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
284e0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
284f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
28500 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
28510 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
28520 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
28530 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
28540 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
28550 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
28560 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
28570 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
28580 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
28590 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
285a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
285b0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
285c0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
285d0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
285e0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
285f0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
28600 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
28610 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
28620 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
28630 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
28640 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
28650 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
28660 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
28670 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
28680 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
28690 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
286a0 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
286b0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
286c0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
286d0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
286e0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
286f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
28700 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
28710 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
28720 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
28730 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
28740 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28750 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
28760 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
28770 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37  * [H16702] [H167
28780 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a  04] [H16706].*/.
28790 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
287a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
287b0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
287c0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
287d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
287e0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
287f0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
28800 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
28810 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
28820 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
28830 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
28840 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
28850 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
28860 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
28870 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
28880 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
28890 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
288a0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
288b0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
288c0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
288d0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
288e0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
288f0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
28900 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
28910 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
28920 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
28930 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28940 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
28950 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
28960 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
28970 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
28980 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28990 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
289a0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
289b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
289c0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
289d0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
289e0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
289f0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
28a00 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
28a10 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
28a20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
28a30 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
28a40 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
28a50 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
28a60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
28a70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
28a80 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
28a90 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
28aa0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
28ab0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
28ac0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
28ad0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
28ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28af0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
28b00 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
28b10 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
28b20 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
28b30 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
28b40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
28b50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
28b60 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
28b70 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
28b80 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
28b90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
28ba0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
28bb0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
28bc0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
28bd0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
28be0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
28bf0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
28c00 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
28c10 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
28c20 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
28c30 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
28c40 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
28c50 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
28c60 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
28c70 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
28c80 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
28c90 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
28ca0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
28cb0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
28cc0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
28cd0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
28ce0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
28cf0 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
28d00 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
28d10 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
28d20 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
28d30 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
28d40 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
28d50 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
28d60 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
28d70 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
28d80 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
28d90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
28da0 74 73 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31  ts: [H10533] [H1
28db0 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  0536].*/.int sql
28dc0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
28dd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28de0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
28df0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
28e00 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31  porary Files {H1
28e10 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0310} <S20000>.*
28e20 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
28e30 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
28e40 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
28e50 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
28e60 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
28e70 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
28e80 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
28e90 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
28ea0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
28eb0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
28ec0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
28ed0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
28ee0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
28ef0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
28f00 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
28f10 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
28f20 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
28f30 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
28f40 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
28f50 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
28f60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
28f70 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
28f80 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
28f90 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
28fa0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
28fb0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
28fc0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
28fd0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
28fe0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
28ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
29000 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
29010 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
29020 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
29030 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
29040 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
29050 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
29060 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
29070 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
29080 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
29090 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
290a0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
290b0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
290c0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
290d0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
290e0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
290f0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
29100 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f  **.** The [temp_
29110 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
29120 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
29130 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
29140 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
29150 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
29160 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
29170 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
29180 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  c].  Furthermore
29190 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
291a0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
291b0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
291c0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
291d0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
291e0 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
291f0 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
29200 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
29210 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
29220 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
29230 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
29240 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
29250 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
29260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
29270 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
29280 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
29290 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
292a0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
292b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
292c0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
292d0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
292e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
292f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
29300 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
29310 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
29320 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
29330 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
29340 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
29350 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
29360 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
29370 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
29380 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
29390 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
293a0 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36  ode {H12930} <S6
293b0 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
293c0 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
293d0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ode}.**.** The s
293e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
293f0 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
29400 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
29410 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
29420 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
29430 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29440 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
29450 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
29460 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
29470 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
29480 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
29490 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  lt..** Autocommi
294a0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
294b0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
294c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
294d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
294e0 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
294f0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
29500 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
29510 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
29520 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
29530 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
29540 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
29550 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
29560 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
29570 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
29580 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
29590 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
295a0 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
295b0 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
295c0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
295d0 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
295e0 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
295f0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
29600 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
29610 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
29620 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
29630 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
29640 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
29650 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
29660 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
29670 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
29680 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
29690 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
296a0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
296b0 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
296c0 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
296d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
296e0 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
296f0 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
29700 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
29710 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
29720 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
29730 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
29740 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b  2931] [H12932] [
29750 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d  H12933] [H12934]
29760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29770 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
29780 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
29790 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
297a0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
297b0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
297c0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
297d0 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  120} <S60600>.**
297e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
297f0 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
29800 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29810 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29820 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
29830 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
29840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29850 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64  belongs.  The [d
29860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29870 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
29880 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
29890 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
298a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
298b0 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20  ction] that was 
298c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
298d0 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
298e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
298f0 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
29900 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
29910 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
29920 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
29930 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
29940 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65   place..**.** Re
29950 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33  quirements: [H13
29960 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  123].*/.sqlite3 
29970 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
29980 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
29990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
299a0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
299b0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
299c0 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53  ment {H13140} <S
299d0 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60600>.**.** Thi
299e0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
299f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29a00 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
29a10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
29a20 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
29a30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
29a40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29a50 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66  ection] pDb.  If
29a60 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
29a70 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
29a80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
29a90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
29aa0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
29ab0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
29ac0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
29ad0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29ae0 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70  on pDb.  If no p
29af0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b00 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
29b10 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
29b20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
29b30 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
29b40 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
29b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29b60 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
29b70 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
29b80 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
29b90 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
29ba0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
29bb0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
29bc0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
29bd0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
29be0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29bf0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
29c00 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31  : [H13143] [H131
29c10 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31  46] [H13149] [H1
29c20 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  3152].*/.sqlite3
29c30 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
29c40 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
29c50 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
29c60 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
29c70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
29c80 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
29c90 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
29ca0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30  allbacks {H12950
29cb0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
29cc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
29cd0 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
29ce0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
29cf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
29d00 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
29d10 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
29d20 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
29d30 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
29d40 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
29d50 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
29d60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
29d70 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
29d80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
29d90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
29da0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
29db0 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
29dc0 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
29dd0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
29de0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
29df0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
29e00 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
29e10 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
29e20 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
29e30 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
29e40 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
29e50 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
29e60 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
29e70 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
29e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
29e90 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
29ea0 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
29eb0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
29ec0 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
29ed0 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ck..** If the ca
29ee0 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
29ef0 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
29f00 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
29f10 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
29f20 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
29f30 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
29f40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
29f50 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
29f60 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
29f70 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
29f80 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
29f90 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
29fa0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
29fb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ned..**.** The c
29fc0 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
29fd0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
29fe0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
29ff0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2a000 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2a010 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2a020 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
2a030 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2a040 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2a050 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a060 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2a070 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2a080 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2a090 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2a0a0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2a0b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2a0c0 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
2a0d0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2a0e0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2a0f0 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
2a100 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a110 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2a120 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2a130 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2a140 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a150 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2a160 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2a170 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2a180 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  aph..**.** Regis
2a190 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
2a1a0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2a1b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2a1c0 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
2a1d0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2a1e0 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2a1f0 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2a200 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2a210 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2a220 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2a230 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2a240 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2a250 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2a260 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2a270 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2a280 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72   occur..** The r
2a290 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2a2a0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2a2b0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2a2c0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2a2d0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2a2e0 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
2a2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a300 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54   is closed..** T
2a310 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
2a320 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
2a330 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
2a340 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65  tion is.** rolle
2a350 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61  d back because a
2a360 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b   commit callback
2a370 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65   returned non-ze
2a380 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68  ro..** <todo> Ch
2a390 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f  eck on this </to
2a3a0 64 6f 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  do>.**.** Requir
2a3b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
2a3c0 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31  51] [H12952] [H1
2a3d0 32 39 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b  2953] [H12954] [
2a3e0 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39  H12955].** [H129
2a3f0 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31  61] [H12962] [H1
2a400 32 39 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a  2963] [H12964].*
2a410 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2a420 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
2a430 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
2a440 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
2a450 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
2a460 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
2a470 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
2a480 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
2a490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2a4a0 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
2a4b0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
2a4c0 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30  {H12970} <S60400
2a4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a4e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2a4f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2a500 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2a510 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
2a520 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2a530 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
2a540 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
2a550 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2a560 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2a570 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
2a580 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2a590 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2a5a0 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
2a5b0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2a5c0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
2a5d0 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
2a5e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2a5f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2a600 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rridden..**.** T
2a610 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2a620 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
2a630 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
2a640 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
2a650 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
2a660 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
2a670 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20  deleted..** The 
2a680 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2a690 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2a6a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a6b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
2a6c0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
2a6d0 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54  ate_hook()..** T
2a6e0 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
2a6f0 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
2a700 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2a710 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
2a720 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
2a730 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
2a740 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2a750 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
2a760 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
2a770 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
2a780 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ked..** The thir
2a790 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
2a7a0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
2a7b0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
2a7c0 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
2a7d0 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
2a7e0 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
2a7f0 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
2a800 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69  d row..** The fi
2a810 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
2a820 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72  ameter is the [r
2a830 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77  owid] of the row
2a840 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65  ..** In the case
2a850 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
2a860 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
2a870 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
2a880 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
2a890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2a8a0 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
2a8b0 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
2a8c0 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
2a8d0 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
2a8e0 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
2a8f0 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
2a900 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
2a910 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2a920 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2a930 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2a940 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2a950 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2a960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a970 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2a980 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2a990 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2a9a0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2a9b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a9c0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2a9d0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2a9e0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2a9f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2aa00 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2aa10 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2aa20 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2aa30 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2aa40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2aa50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2aa60 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2aa70 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2aa80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2aa90 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2aaa0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2aab0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2aac0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2aad0 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
2aae0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
2aaf0 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
2ab00 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
2ab10 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
2ab20 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2ab30 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2ab40 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d  nts:.** [H12971]
2ab50 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37   [H12973] [H1297
2ab60 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32  5] [H12977] [H12
2ab70 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48  979] [H12981] [H
2ab80 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a  12983] [H12986].
2ab90 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2aba0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
2abb0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2abc0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
2abd0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
2abe0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
2abf0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
2ac00 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
2ac10 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
2ac20 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
2ac30 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30  Pager Cache {H10
2ac40 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a  330} <S30900>.**
2ac50 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
2ac60 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65  ed cache} {share
2ac70 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a  d cache mode}.**
2ac80 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2ac90 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
2aca0 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
2acb0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2acc0 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
2acd0 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
2ace0 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
2acf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ad00 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
2ad10 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2ad20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
2ad30 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
2ad40 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2ad50 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
2ad60 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2ad70 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a  ment is false..*
2ad80 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69  *.** Cache shari
2ad90 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2ada0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2adb0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2adc0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2add0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2ade0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2adf0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2ae00 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2ae10 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2ae20 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2ae30 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2ae40 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2ae50 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68  .** The cache sh
2ae60 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
2ae70 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
2ae80 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
2ae90 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2aea0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2aeb0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2aec0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
2aed0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2aee0 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
2aef0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2af00 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
2af10 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
2af20 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
2af30 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
2af40 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
2af50 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ened..**.** Virt
2af60 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
2af70 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
2af80 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
2af90 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63  When shared.** c
2afa0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
2afb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2afc0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41  eate_module()] A
2afd0 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  PI used to regis
2afe0 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  ter.** virtual t
2aff0 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79  ables will alway
2b000 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
2b010 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  r..**.** This ro
2b020 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
2b030 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
2b040 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
2b050 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2b060 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
2b070 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
2b080 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
2b090 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
2b0a0 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
2b0b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
2b0c0 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d  ault. But this m
2b0d0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a  ight change in.*
2b0e0 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  * future release
2b0f0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70  s of SQLite.  Ap
2b100 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2b110 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65  care about share
2b120 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69  d.** cache setti
2b130 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74  ng should set it
2b140 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a   explicitly..**.
2b150 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53  ** See Also:  [S
2b160 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63  QLite Shared-Cac
2b170 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52  he Mode].**.** R
2b180 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2b190 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b  0331] [H10336] [
2b1a0 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d  H10337] [H10339]
2b1b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b1c0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
2b1d0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
2b1e0 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
2b1f0 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
2b200 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20  Memory {H17340} 
2b210 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
2b220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
2b230 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
2b240 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2b250 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
2b260 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
2b270 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
2b280 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2b290 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2b2a0 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
2b2b0 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
2b2c0 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79  y. {END}  Memory
2b2d0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2b2e0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2b2f0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2b300 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2b310 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2b320 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2b330 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  * sqlite3_releas
2b340 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
2b350 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2b360 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
2b370 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
2b380 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
2b390 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
2b3a0 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
2b3b0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2b3c0 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48  nts: [H17341] [H
2b3d0 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17342].*/.int sq
2b3e0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2b3f0 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
2b400 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f  * CAPI3REF: Impo
2b410 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
2b420 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d  ap Size {H17350}
2b430 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20   <S30220>.**.** 
2b440 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
2b450 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
2b460 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61  terface places a
2b470 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a   "soft" limit.**
2b480 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
2b490 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
2b4a0 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
2b4b0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2b4c0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c  * If an internal
2b4d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72   allocation is r
2b4e0 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f  equested that wo
2b4f0 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2b500 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  * soft heap limi
2b510 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  t, [sqlite3_rele
2b520 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
2b530 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a   invoked one or.
2b540 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  ** more times to
2b550 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70   free up some sp
2b560 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61  ace before the a
2b570 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72  llocation is per
2b580 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  formed..**.** Th
2b590 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65  e limit is calle
2b5a0 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73  d "soft", becaus
2b5b0 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65  e if [sqlite3_re
2b5c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a  lease_memory()].
2b5d0 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73  ** cannot free s
2b5e0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2b5f0 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
2b600 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
2b610 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68   exceeded,.** th
2b620 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  e memory is allo
2b630 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
2b640 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
2b650 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
2b660 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  .**.** A negativ
2b670 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
2b680 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
2b690 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
2b6a0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
2b6b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
2b6c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
2b6d0 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
2b6e0 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
2b6f0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
2b700 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2b710 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
2b720 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
2b730 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
2b740 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
2b750 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
2b760 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2b770 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20  ..** But if the 
2b780 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2b790 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65  cannot be honore
2b7a0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
2b7b0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
2b7c0 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
2b7d0 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68  otification.  Th
2b7e0 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69  is is why the li
2b7f0 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  mit is.** called
2b800 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
2b810 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
2b820 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
2b830 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
2b840 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
2b850 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
2b860 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
2b870 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
2b880 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
2b890 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
2b8a0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
2b8b0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
2b8c0 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
2b8d0 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
2b8e0 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
2b8f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2b900 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
2b910 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
2b920 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
2b930 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
2b940 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
2b950 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
2b960 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
2b970 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
2b980 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
2b990 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
2b9a0 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
2b9b0 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
2b9c0 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
2b9d0 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
2b9e0 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
2b9f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2ba00 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20  ts:.** [H16351] 
2ba10 5b 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33  [H16352] [H16353
2ba20 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33  ] [H16354] [H163
2ba30 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a  55] [H16358].*/.
2ba40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
2ba50 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
2ba60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ba70 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
2ba80 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2ba90 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b  umn Of A Table {
2baa0 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e  H12850} <S60300>
2bab0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2bac0 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61  ine returns meta
2bad0 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
2bae0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
2baf0 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61  a specific.** da
2bb00 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63  tabase table acc
2bb10 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
2bb20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2bb30 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
2bb40 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
2bb50 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61  first function a
2bb60 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2bb70 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
2bb80 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
2bb90 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
2bba0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2bbb0 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
2bbc0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f  nction. The seco
2bbd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2bbe0 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
2bbf0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2bc00 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
2bc10 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74   "temp" or an at
2bc20 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
2bc30 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2bc40 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
2bc50 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69  le or NULL. If i
2bc60 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2bc70 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
2bc80 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
2bc90 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
2bca0 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
2bcb0 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73  ame algorithm us
2bcc0 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ed by the databa
2bcd0 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20  se engine to.** 
2bce0 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66  resolve unqualif
2bcf0 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65  ied table refere
2bd00 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nces..**.** The 
2bd10 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
2bd20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
2bd30 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
2bd40 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
2bd50 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66  olumn.** name of
2bd60 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2bd70 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
2bd80 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
2bd90 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ese parameters.*
2bda0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
2bdb0 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73  *.** Metadata is
2bdc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
2bdd0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
2bde0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
2bdf0 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
2be00 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
2be10 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
2be20 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
2be30 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
2be40 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
2be50 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
2be60 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
2be70 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
2be80 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
2be90 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ted..**.** <bloc
2bea0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2beb0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2bec0 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65   <tr><th> Parame
2bed0 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c  ter <th> Output<
2bee0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65  br>Type <th>  De
2bef0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  scription.**.** 
2bf00 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64  <tr><td> 5th <td
2bf10 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
2bf20 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20  d> Data type.** 
2bf30 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64  <tr><td> 6th <td
2bf40 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
2bf50 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75  d> Name of defau
2bf60 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
2bf70 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  uence.** <tr><td
2bf80 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 7th <td> int  
2bf90 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
2bfa0 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61   if column has a
2bfb0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
2bfc0 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  aint.** <tr><td>
2bfd0 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   8th <td> int   
2bfe0 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2bff0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  if column is par
2c000 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
2c010 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   KEY.** <tr><td>
2c020 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   9th <td> int   
2c030 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2c040 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55  if column is [AU
2c050 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20  TOINCREMENT].** 
2c060 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2c070 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2c080 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
2c090 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
2c0a0 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
2c0b0 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
2c0c0 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
2c0d0 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
2c0e0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
2c0f0 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
2c100 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
2c110 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
2c120 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
2c130 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
2c140 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
2c150 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
2c160 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2c170 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2c180 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2c190 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
2c1a0 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
2c1b0 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
2c1c0 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
2c1d0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
2c1e0 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
2c1f0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
2c200 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
2c210 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
2c220 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
2c230 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
2c240 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20  olumn. If there 
2c250 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
2c260 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e  tly declared [IN
2c270 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
2c280 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20  Y] column, then 
2c290 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2c2a0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2c2b0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
2c2c0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
2c2d0 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
2c2e0 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
2c2f0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
2c300 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
2c310 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
2c320 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
2c330 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
2c340 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
2c350 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
2c360 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
2c370 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
2c380 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
2c390 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
2c3a0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
2c3b0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
2c3c0 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
2c3d0 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
2c3e0 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
2c3f0 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
2c400 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2c410 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
2c420 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c   error message l
2c430 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64  eft.** in the [d
2c440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c450 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69  on] (to be retri
2c460 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  eved using sqlit
2c470 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a  e3_errmsg())..**
2c480 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20  .** This API is 
2c490 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2c4a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2c4b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2c4c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2c4d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2c4e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2c4f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
2c500 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2c510 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
2c520 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
2c530 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c540 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
2c550 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
2c560 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2c570 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
2c580 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
2c590 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
2c5a0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
2c5b0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
2c5c0 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
2c5d0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
2c5e0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
2c5f0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
2c600 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
2c610 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
2c620 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
2c630 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
2c640 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
2c650 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
2c660 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
2c670 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
2c680 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
2c690 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2c6a0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
2c6b0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2c6c0 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
2c6d0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
2c6e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2c6f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2c700 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
2c710 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
2c720 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
2c730 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2c740 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
2c750 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
2c760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c770 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
2c780 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c  nsion {H12600} <
2c790 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20500>.**.** Th
2c7a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61  is interface loa
2c7b0 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74  ds an SQLite ext
2c7c0 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66  ension library f
2c7d0 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69  rom the named fi
2c7e0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  le..**.** {H1260
2c7f0 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  1} The sqlite3_l
2c800 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2c810 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2c820 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
2c830 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
2c840 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
2c850 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
2c860 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a  the file zFile..
2c870 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54  **.** {H12602} T
2c880 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
2c890 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b  s zProc..**.** {
2c8a0 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61  H12603} zProc ma
2c8b0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
2c8c0 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
2c8d0 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
2c8e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  t.**          de
2c8f0 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
2c900 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
2c910 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  t"..**.** {H1260
2c920 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  4} The sqlite3_l
2c930 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2c940 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2c950 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
2c960 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f     [SQLITE_OK] o
2c970 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
2c980 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
2c990 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
2c9a0 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rong..**.** {H12
2c9b0 36 30 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  605} If an error
2c9c0 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72   occurs and pzEr
2c9d0 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74  rMsg is not 0, t
2c9e0 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hen the.**      
2c9f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61      [sqlite3_loa
2ca00 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
2ca10 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
2ca20 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20  ttempt to.**    
2ca30 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72        fill *pzEr
2ca40 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
2ca50 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
2ca60 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
2ca70 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
2ca80 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2ca90 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44  _malloc()]. {END
2caa0 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  }  The calling f
2cab0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2cac0 20 20 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20      should free 
2cad0 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63  this memory by c
2cae0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2caf0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  free()]..**.** {
2cb00 48 31 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f  H12606} Extensio
2cb10 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
2cb20 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
2cb30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2cb40 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
2cb50 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72  _extension()] pr
2cb60 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
2cb70 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20  his API,.**     
2cb80 20 20 20 20 20 6f 74 68 65 72 77 69 73 65 20 61       otherwise a
2cb90 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
2cba0 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
2cbb0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
2cbc0 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
2cbd0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cbe0 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
2cbf0 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
2cc00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2cc10 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
2cc20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
2cc30 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
2cc40 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
2cc50 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
2cc60 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2cc70 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
2cc80 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
2cc90 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
2cca0 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
2ccb0 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
2ccc0 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
2ccd0 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
2cce0 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
2ccf0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
2cd00 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
2cd10 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2cd20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30  {H12620} <S20500
2cd30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f  >.**.** So as no
2cd40 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
2cd50 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
2cd60 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
2cd70 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
2cd80 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
2cd90 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
2cda0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
2cdb0 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
2cdc0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
2cdd0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
2cde0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
2cdf0 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
2ce00 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
2ce10 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
2ce20 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
2ce30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2ce40 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
2ce50 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78  nd off..**.** Ex
2ce60 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2ce70 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
2ce80 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  t. See ticket #1
2ce90 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  863..**.** {H126
2cea0 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c  21} Call the sql
2ceb0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
2cec0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
2ced0 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d  tine with onoff=
2cee0 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  =1.**          t
2cef0 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
2cf00 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20   loading on and 
2cf10 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f  call it with ono
2cf20 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a  ff==0 to turn.**
2cf30 20 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63            it bac
2cf40 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a  k off again..**.
2cf50 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65  ** {H12622} Exte
2cf60 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2cf70 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2cf80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2cf90 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
2cfa0 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
2cfb0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
2cfc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cfd0 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
2cfe0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73  ad An Extensions
2cff0 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30   {H12640} <S2050
2d000 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  0>.**.** This AP
2d010 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64  I can be invoked
2d020 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72   at program star
2d030 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  tup in order to 
2d040 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20  register.** one 
2d050 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c  or more statical
2d060 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73  ly linked extens
2d070 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ions that will b
2d080 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74  e available.** t
2d090 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62  o all new [datab
2d0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
2d0b0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
2d0c0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
2d0d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d0e0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
2d0f0 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
2d100 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
2d110 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2d120 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75  c()].  If you ru
2d130 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20  n a memory leak 
2d140 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f  checker.** on yo
2d150 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69  ur program and i
2d160 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b  t reports a leak
2d170 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   because of this
2d180 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a   array, invoke.*
2d190 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d1a0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2d1b0 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74  )] prior to shut
2d1c0 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65  down to free the
2d1d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
2d1e0 48 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e  H12641} This fun
2d1f0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20  ction registers 
2d200 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  an extension ent
2d210 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73  ry point that is
2d220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
2d230 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
2d240 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ed whenever a ne
2d250 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
2d260 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20  ection].**      
2d270 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73      is opened us
2d280 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
2d290 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d2a0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
2d2b0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2d2c0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
2d2d0 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70  .** {H12642} Dup
2d2e0 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
2d2f0 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
2d300 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
2d310 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20  outine.**       
2d320 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65     multiple time
2d330 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2d340 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72  extension is har
2d350 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mless..**.** {H1
2d360 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69  2643} This routi
2d370 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e  ne stores a poin
2d380 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e  ter to the exten
2d390 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79  sion in an array
2d3a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
2d3b0 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  t is obtained fr
2d3c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2d3d0 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  oc()]..**.** {H1
2d3e0 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20  2644} Automatic 
2d3f0 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79  extensions apply
2d400 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65   across all thre
2d410 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ads..*/.int sqli
2d420 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
2d430 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79  on(void (*xEntry
2d440 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a  Point)(void));..
2d450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d460 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
2d470 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2d480 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35  g {H12660} <S205
2d490 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
2d4a0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2d4b0 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20   all previously 
2d4c0 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d  registered autom
2d4d0 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  atic.** extensio
2d4e0 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e  ns. {END}  It un
2d4f0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
2d500 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20  of all prior.** 
2d510 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78  [sqlite3_auto_ex
2d520 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73  tension()] calls
2d530 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d  ..**.** {H12661}
2d540 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2d550 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76  isables all prev
2d560 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2d570 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  d.**          au
2d580 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2d590 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36  ns..**.** {H1266
2d5a0 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  2} This function
2d5b0 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61   disables automa
2d5c0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
2d5d0 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
2d5e0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2d5f0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2d600 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
2d610 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
2d620 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
2d630 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
2d640 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
2d650 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
2d660 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
2d670 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2d680 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
2d690 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
2d6a0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
2d6b0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
2d6c0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
2d6d0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
2d6e0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
2d6f0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
2d700 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
2d710 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
2d720 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
2d730 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
2d740 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2d750 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
2d760 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
2d770 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
2d780 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
2d790 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
2d7a0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
2d7b0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
2d7c0 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
2d7d0 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
2d7e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
2d7f0 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
2d800 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2d810 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
2d820 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
2d830 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2d840 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
2d850 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
2d860 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2d870 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
2d880 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2d890 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2d8a0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
2d8b0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
2d8c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d8d0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
2d8e0 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c  bject {H18000} <
2d8f0 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
2d900 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
2d910 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
2d920 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58  le module}.** EX
2d930 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2d940 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
2d950 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
2d960 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74  d a a "virtual t
2d970 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
2d980 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
2d990 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2d9a0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
2d9b0 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
2d9c0 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
2d9d0 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
2d9e0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
2d9f0 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  e..**.** A virtu
2da00 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20  al table module 
2da10 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69  is created by fi
2da20 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69  lling in a persi
2da30 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63  stent.** instanc
2da40 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
2da50 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20  ure and passing 
2da60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2da70 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f  t instance.** to
2da80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2da90 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73  _module()] or [s
2daa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2dab0 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  dule_v2()]..** T
2dac0 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
2dad0 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
2dae0 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
2daf0 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
2db00 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
2db10 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
2db20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
2db30 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
2db40 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
2db50 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
2db60 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
2db70 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
2db80 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
2db90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
2dba0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2dbb0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
2dbc0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
2dbd0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
2dbe0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
2dbf0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
2dc00 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
2dc10 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
2dc20 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
2dc30 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
2dc40 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
2dc50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
2dc60 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
2dc70 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
2dc80 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
2dc90 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
2dca0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
2dcb0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
2dcc0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
2dcd0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
2dce0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
2dcf0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2dd00 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
2dd10 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
2dd20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
2dd30 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2dd40 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
2dd50 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
2dd60 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2dd70 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
2dd80 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
2dd90 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2dda0 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
2ddb0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
2ddc0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2ddd0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2dde0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
2ddf0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2de00 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
2de10 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
2de20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de30 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
2de40 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
2de50 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
2de60 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2de70 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2de80 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
2de90 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
2dea0 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
2deb0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2dec0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
2ded0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
2dee0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
2def0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2df00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
2df10 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
2df20 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
2df30 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
2df40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
2df50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
2df60 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
2df70 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2df80 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2df90 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
2dfa0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2dfb0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
2dfc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2dfd0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
2dfe0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
2dff0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2e000 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
2e010 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
2e020 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
2e030 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
2e040 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
2e050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2e060 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
2e070 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e080 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e090 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
2e0a0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2e0b0 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
2e0c0 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
2e0d0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
2e0e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
2e0f0 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  w);.};../*.** CA
2e100 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2e110 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49  Table Indexing I
2e120 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31  nformation {H181
2e130 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20  00} <S20400>.** 
2e140 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
2e150 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20  3_index_info.** 
2e160 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
2e170 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
2e180 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
2e190 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
2e1a0 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
2e1b0 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  d to.** pass inf
2e1c0 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
2e1d0 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
2e1e0 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
2e1f0 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
2e200 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
2e210 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
2e220 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
2e230 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
2e240 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
2e250 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
2e260 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
2e270 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
2e280 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
2e290 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
2e2a0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
2e2b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  .**.** The aCons
2e2c0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
2e2d0 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
2e2e0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
2e2f0 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
2e300 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f  ** <pre>column O
2e310 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a  P expr</pre>.**.
2e320 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d  ** where OP is =
2e330 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
2e340 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20  gt;, or &gt;=.  
2e350 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f  The particular o
2e360 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74  perator is.** st
2e370 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61  ored in aConstra
2e380 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69  int[].op.  The i
2e390 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2e3a0 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a  mn is stored in.
2e3b0 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ** aConstraint[]
2e3c0 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73  .iColumn.  aCons
2e3d0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
2e3e0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
2e3f0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
2e400 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
2e410 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
2e420 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
2e430 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
2e440 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
2e450 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a  if it cannot..**
2e460 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65  .** The optimize
2e470 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
2e480 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
2e490 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
2e4a0 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
2e4b0 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
2e4c0 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
2e4d0 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
2e4e0 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
2e4f0 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
2e500 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
2e510 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
2e520 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
2e530 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54  s possible..** T
2e540 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
2e550 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f   array only repo
2e560 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rts WHERE clause
2e570 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f   terms in the co
2e580 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68  rrect.** form th
2e590 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20  at refer to the 
2e5a0 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
2e5b0 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
2e5c0 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ueried..**.** In
2e5d0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2e5e0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
2e5f0 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
2e600 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
2e610 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
2e620 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
2e630 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
2e640 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
2e650 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49  *.** The [xBestI
2e660 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73  ndex] method mus
2e670 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69  t fill aConstrai
2e680 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69  ntUsage[] with i
2e690 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
2e6a0 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74  out what paramet
2e6b0 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78  ers to pass to x
2e6c0 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76  Filter.  If argv
2e6d0 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20  Index>0 then.** 
2e6e0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
2e6f0 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65  ide of the corre
2e700 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72  sponding aConstr
2e710 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61  aint[] is evalua
2e720 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d  ted.** and becom
2e730 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78  es the argvIndex
2e740 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67  -th entry in arg
2e750 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69  v.  If aConstrai
2e760 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a  ntUsage[].omit.*
2e770 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  * is true, then 
2e780 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  the constraint i
2e790 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20  s assumed to be 
2e7a0 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79  fully handled by
2e7b0 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20   the.** virtual 
2e7c0 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74  table and is not
2e7d0 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62   checked again b
2e7e0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  y SQLite..**.** 
2e7f0 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69  The idxNum and i
2e800 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65  dxPtr values are
2e810 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61   recorded and pa
2e820 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ssed into the.**
2e830 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f   [xFilter] metho
2e840 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  d..** [sqlite3_f
2e850 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
2e860 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
2e870 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a   and only iff.**
2e880 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
2e890 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
2e8a0 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73   The orderByCons
2e8b0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
2e8c0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
2e8d0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
2e8e0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
2e8f0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
2e900 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
2e910 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
2e920 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
2e930 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
2e940 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
2e950 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d  .**.** The estim
2e960 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
2e970 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
2e980 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
2e990 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
2e9a0 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
2e9b0 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
2e9c0 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
2e9d0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
2e9e0 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
2e9f0 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
2ea00 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
2ea10 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
2ea20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
2ea30 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
2ea40 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
2ea50 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2ea60 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
2ea70 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
2ea80 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
2ea90 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
2eaa0 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
2eab0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
2eac0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2ead0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
2eae0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
2eaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2eb00 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
2eb10 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
2eb20 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
2eb30 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
2eb40 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
2eb50 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
2eb60 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
2eb70 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
2eb80 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
2eb90 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
2eba0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
2ebb0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
2ebc0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
2ebd0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
2ebe0 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
2ebf0 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
2ec00 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
2ec10 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
2ec20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
2ec30 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
2ec40 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
2ec50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
2ec60 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2ec70 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
2ec80 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
2ec90 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2eca0 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
2ecb0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
2ecc0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
2ecd0 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
2ece0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
2ecf0 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
2ed00 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
2ed10 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
2ed20 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
2ed30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ed40 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
2ed50 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74  ause */.  /* Out
2ed60 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
2ed70 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
2ed80 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
2ed90 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
2eda0 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
2edb0 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
2edc0 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
2edd0 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
2ede0 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
2edf0 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
2ee00 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
2ee10 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
2ee20 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
2ee30 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
2ee40 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
2ee50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ee60 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
2ee70 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
2ee80 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
2ee90 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
2eea0 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
2eeb0 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
2eec0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
2eed0 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
2eee0 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
2eef0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
2ef00 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
2ef10 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
2ef20 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
2ef30 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
2ef40 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
2ef50 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
2ef60 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
2ef70 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
2ef80 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
2ef90 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
2efa0 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
2efb0 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
2efc0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2efd0 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
2efe0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2eff0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
2f000 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2f010 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2f020 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
2f030 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2f040 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
2f050 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
2f060 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2f070 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
2f080 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2f090 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
2f0a0 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
2f0b0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
2f0c0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
2f0d0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b  Implementation {
2f0e0 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18200} <S20400>
2f0f0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2f100 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2f110 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ine is used to r
2f120 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76  egister a new [v
2f130 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2f140 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f  ule] name..** Mo
2f150 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20  dule names must 
2f160 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65  be registered be
2f170 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67  fore.** creating
2f180 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20   a new [virtual 
2f190 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65  table] using the
2f1a0 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f   module, or befo
2f1b0 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72  re using a.** pr
2f1c0 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75  eexisting [virtu
2f1d0 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68  al table] for th
2f1e0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
2f1f0 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  The module name 
2f200 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e  is registered on
2f210 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f220 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
2f230 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  fied.** by the f
2f240 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
2f250 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2f260 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e   module is given
2f270 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f   by the .** seco
2f280 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
2f290 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2f2a0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
2f2b0 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
2f2c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2f2d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2f2e0 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f  odule].   The fo
2f2f0 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  urth.** paramete
2f300 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
2f310 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f  y client data po
2f320 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
2f330 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
2f340 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74  into the [xCreat
2f350 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
2f360 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  ] methods of the
2f370 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
2f380 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20  odule.** when a 
2f390 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
2f3a0 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72  e is be being cr
2f3b0 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69  eated or reiniti
2f3c0 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  alized..**.** Th
2f3d0 69 73 20 69 6e 74 65 72 66 61 63 65 20 68 61 73  is interface has
2f3e0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
2f3f0 65 20 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c  e effect as call
2f400 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2f410 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
2f420 28 29 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  ()] with a NULL 
2f430 63 6c 69 65 6e 74 20 64 61 74 61 20 64 65 73 74  client data dest
2f440 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54  ructor..*/.SQLIT
2f450 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
2f460 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2f470 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
2f480 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2f490 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
2f4a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
2f4b0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
2f4c0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
2f4d0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
2f4e0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
2f4f0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
2f500 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
2f510 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
2f520 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
2f530 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
2f540 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
2f550 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
2f560 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
2f570 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f  Connect */.);../
2f580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2f590 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
2f5a0 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
2f5b0 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20  tation {H18210} 
2f5c0 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20400>.** EXPE
2f5d0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2f5e0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
2f5f0 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20  dentical to the 
2f600 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f610 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64  module()] method
2f620 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ,.** except that
2f630 20 69 74 20 68 61 73 20 61 6e 20 65 78 74 72 61   it has an extra
2f640 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70   parameter to sp
2f650 65 63 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74  ecify .** a dest
2f660 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2f670 66 6f 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64  for the client d
2f680 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51  ata pointer.  SQ
2f690 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76  Lite will.** inv
2f6a0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
2f6b0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20  or function (if 
2f6c0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  it is not NULL) 
2f6d0 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e  when SQLite.** n
2f6e0 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74  o longer needs t
2f6f0 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70  he pClientData p
2f700 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c  ointer.  .*/.SQL
2f710 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
2f720 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2f730 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
2f740 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2f750 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2f760 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
2f770 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
2f780 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
2f790 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2f7a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
2f7b0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
2f7c0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
2f7d0 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
2f7e0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
2f7f0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
2f800 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
2f810 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
2f820 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
2f830 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
2f840 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2f850 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
2f860 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
2f870 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
2f880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f890 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
2f8a0 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20  Instance Object 
2f8b0 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30  {H18010} <S20400
2f8c0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  >.** KEYWORDS: s
2f8d0 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45  qlite3_vtab.** E
2f8e0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
2f8f0 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c  * Every [virtual
2f900 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69   table module] i
2f910 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
2f920 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a  es a subclass.**
2f930 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2f940 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64  g structure to d
2f950 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
2f960 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  ular instance.**
2f970 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
2f980 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73   table].  Each s
2f990 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20  ubclass will.** 
2f9a0 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74  be tailored to t
2f9b0 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
2f9c0 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  s of the module 
2f9d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
2f9e0 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f  ** The purpose o
2f9f0 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
2fa00 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
2fa10 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
2fa20 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e  at are.** common
2fa30 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
2fa40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
2fa50 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
2fa60 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
2fa70 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
2fa80 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
2fa90 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
2faa0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2fab0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
2fac0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68   to zErrMsg.  Th
2fad0 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a  e method should.
2fae0 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61  ** take care tha
2faf0 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69  t any prior stri
2fb00 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61  ng is freed by a
2fb10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2fb20 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69  3_free()].** pri
2fb30 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
2fb40 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
2fb50 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
2fb60 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2fb70 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
2fb80 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
2fb90 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
2fba0 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
2fbb0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2fbc0 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
2fbd0 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
2fbe0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
2fbf0 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
2fc00 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
2fc10 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e  te3_vtab {.  con
2fc20 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
2fc30 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20  e *pModule;  /* 
2fc40 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74  The module for t
2fc50 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  his virtual tabl
2fc60 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b  e */.  int nRef;
2fc70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fc80 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
2fc90 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63  nternally */.  c
2fca0 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
2fcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2fcc0 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
2fcd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
2fce0 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
2fcf0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
2fd00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
2fd10 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
2fd20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
2fd30 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
2fd40 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
2fd50 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
2fd60 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c  ject  {H18020} <
2fd70 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
2fd80 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
2fd90 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
2fda0 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
2fdb0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2fdc0 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
2fdd0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2fde0 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
2fdf0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
2fe00 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
2fe10 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
2fe20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
2fe30 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
2fe40 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
2fe50 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
2fe60 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
2fe70 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
2fe80 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
2fe90 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
2fea0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
2feb0 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
2fec0 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
2fed0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
2fee0 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
2fef0 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
2ff00 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
2ff10 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
2ff20 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72   method.  Cussor
2ff30 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
2ff40 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
2ff50 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
2ff60 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
2ff70 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
2ff80 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
2ff90 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
2ffa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2ffb0 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
2ffc0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
2ffd0 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
2ffe0 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
2fff0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
30000 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
30010 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
30020 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
30030 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
30040 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
30050 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
30060 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
30070 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
30080 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
30090 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
300a0 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
300b0 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
300c0 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
300d0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
300e0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
300f0 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
30100 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
30110 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
30120 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
30130 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
30140 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32  tual Table {H182
30150 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20  80} <S20400>.** 
30160 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
30170 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d  ** The [xCreate]
30180 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
30190 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20  methods of a.** 
301a0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
301b0 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73  odule] call this
301c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
301d0 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
301e0 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
301f0 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
30200 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
30210 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
30220 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
30230 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ment..*/.SQLITE_
30240 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
30250 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
30260 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
30270 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
30280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30290 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
302a0 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
302b0 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38  rtual Table {H18
302c0 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a  300} <S20400>.**
302d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
302e0 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
302f0 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
30300 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
30310 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
30320 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
30330 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
30340 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
30350 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
30360 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
30370 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
30380 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
30390 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
303a0 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
303b0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   be overloaded..
303c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d  **.** This API m
303d0 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62  akes sure a glob
303e0 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20  al version of a 
303f0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
30400 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61  particular.** na
30410 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66  me and number of
30420 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73   parameters exis
30430 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20  ts.  If no such 
30440 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a  function exists.
30450 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41  ** before this A
30460 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20  PI is called, a 
30470 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
30480 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d  created.  The im
30490 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
304a0 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
304b0 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
304c0 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
304d0 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
304e0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
304f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
30500 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
30510 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
30520 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
30530 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
30540 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
30550 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
30560 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69  aded.** by a [vi
30570 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
30580 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
30590 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
305a0 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
305b0 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
305c0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
305d0 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
305e0 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
305f0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
30600 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
30610 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
30620 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
30630 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
30640 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
30650 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
30660 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
30670 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
30680 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
30690 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
306a0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
306b0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
306c0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
306d0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
306e0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
306f0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
30700 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
30710 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30720 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
30730 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
30740 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
30750 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
30760 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
30770 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
30780 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
30790 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  **.****** EXPERI
307a0 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
307b0 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
307c0 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
307d0 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a  ********.*/../*.
307e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
307f0 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
30800 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c   BLOB {H17800} <
30810 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S30230>.** KEYWO
30820 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
30830 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
30840 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
30850 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
30860 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
30870 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
30880 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
30890 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
308a0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
308b0 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
308c0 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f  ed..** Objects o
308d0 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20  f this type are 
308e0 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69  created by [sqli
308f0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
30900 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65  .** and destroye
30910 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
30920 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20  ob_close()]..** 
30930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
30940 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
30950 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
30960 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  e()] interfaces.
30970 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
30980 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
30990 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e  small subsection
309a0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a  s of the BLOB..*
309b0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
309c0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
309d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
309e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
309f0 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
30a00 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30a10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
30a20 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
30a30 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
30a40 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
30a50 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37  emental I/O {H17
30a60 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  810} <S30230>.**
30a70 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
30a80 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
30a90 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
30aa0 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
30ab0 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
30ac0 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
30ad0 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
30ae0 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
30af0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
30b00 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
30b10 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
30b20 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
30b30 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
30b40 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
30b50 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
30b60 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
30b70 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
30b80 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  e> {END}.**.** I
30b90 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
30ba0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
30bb0 6f 2c 20 74 68 65 20 74 68 65 20 42 4c 4f 42 20  o, the the BLOB 
30bc0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
30bd0 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20  ad.** and write 
30be0 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73  access. If it is
30bf0 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20   zero, the BLOB 
30c00 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
30c10 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ad access..**.**
30c20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64   Note that the d
30c30 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
30c40 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  not the filename
30c50 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a   that contains.*
30c60 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  * the database b
30c70 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79  ut rather the sy
30c80 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74  mbolic name of t
30c90 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
30ca0 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20  .** is assigned 
30cb0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
30cc0 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75  e is connected u
30cd0 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a  sing [ATTACH]..*
30ce0 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * For the main d
30cf0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68  atabase file, th
30d00 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
30d10 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f  is "main"..** Fo
30d20 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74  r TEMP tables, t
30d30 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
30d40 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a   is "temp"..**.*
30d50 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
30d60 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
30d70 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
30d80 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  w [BLOB handle] 
30d90 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  is written.** to
30da0 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77   *ppBlob. Otherw
30db0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
30dc0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
30dd0 61 6e 64 20 61 6e 79 20 76 61 6c 75 65 20 77 72  and any value wr
30de0 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42  itten.** to *ppB
30df0 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  lob should not b
30e00 65 20 75 73 65 64 20 62 79 20 74 68 65 20 63 61  e used by the ca
30e10 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75  ller..** This fu
30e20 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
30e30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30e40 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
30e50 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
30e60 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
30e70 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
30e80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30e90 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
30ea0 20 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74   If the row that
30eb0 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70   a BLOB handle p
30ec0 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69  oints to is modi
30ed0 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55  fied by an.** [U
30ee0 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
30ef0 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46  , or by [ON CONF
30f00 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63  LICT] side-effec
30f10 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42  ts.** then the B
30f20 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61  LOB handle is ma
30f30 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64  rked as "expired
30f40 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72  "..** This is tr
30f50 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e  ue if any column
30f60 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63   of the row is c
30f70 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63  hanged, even a c
30f80 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74  olumn.** other t
30f90 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20  han the one the 
30fa0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f  BLOB handle is o
30fb0 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73  pen on..** Calls
30fc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
30fd0 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
30fe0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
30ff0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78  e()] for.** a ex
31000 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c  pired BLOB handl
31010 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72  e fail with an r
31020 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
31030 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
31040 20 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e   Changes written
31050 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69   into a BLOB pri
31060 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65  or to the BLOB e
31070 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a  xpiring are not.
31080 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 20 74  ** rollback by t
31090 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
310a0 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
310b0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
310c0 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
310d0 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
310e0 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
310f0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
31100 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
31110 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b  s:.** [H17813] [
31120 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 36 5d  H17814] [H17816]
31130 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 38 32   [H17819] [H1782
31140 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69  1] [H17824].*/.i
31150 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
31160 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
31170 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31180 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
31190 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
311a0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
311b0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
311c0 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
311d0 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
311e0 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
311f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31200 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
31210 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c 53  ndle {H17830} <S
31220 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f  30230>.**.** Clo
31230 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  ses an open [BLO
31240 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  B handle]..**.**
31250 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20   Closing a BLOB 
31260 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
31270 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
31280 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
31290 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
312a0 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
312b0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
312c0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
312d0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
312e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
312f0 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
31300 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ode]..** If any 
31310 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
31320 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
31330 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
31340 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
31350 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
31360 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
31370 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a  ill fit. {END}.*
31380 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65  *.** Closing the
31390 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63   BLOB often forc
313a0 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a  es the changes.*
313b0 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e  * out to disk an
313c0 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20  d so if any I/O 
313d0 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68  errors occur, th
313e0 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f  ey will likely o
313f0 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74  ccur.** at the t
31400 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f  ime when the BLO
31410 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48  B is closed.  {H
31420 31 37 38 33 33 7d 20 41 6e 79 20 65 72 72 6f 72  17833} Any error
31430 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72  s that occur dur
31440 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61  ing.** closing a
31450 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61  re reported as a
31460 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
31470 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
31480 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
31490 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79   unconditionally
314a0 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20  .  Even if this 
314b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a  routine returns.
314c0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  ** an error code
314d0 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74  , the BLOB is st
314e0 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  ill closed..**.*
314f0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
31500 2a 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37  ** [H17833] [H17
31510 38 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f  836] [H17839].*/
31520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
31530 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f  b_close(sqlite3_
31540 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
31550 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
31560 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20   The Size Of An 
31570 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34  Open BLOB {H1784
31580 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
31590 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 73 69  * Returns the si
315a0 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74  ze in bytes of t
315b0 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62  he BLOB accessib
315c0 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 0a  le via the open.
315d0 2a 2a 20 5b 5d 42 4c 4f 42 20 68 61 6e 64 6c 65  ** []BLOB handle
315e0 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72  ] in its only ar
315f0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  gument..**.** Re
31600 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
31610 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20 73  H17843].*/.int s
31620 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
31630 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
31640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31650 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72  EF: Read Data Fr
31660 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
31670 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d  entally {H17850}
31680 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
31690 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
316a0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61   used to read da
316b0 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20  ta from an open 
316c0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
316d0 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  to a.** caller-s
316e0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
316f0 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
31700 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
31710 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d  buffer Z.** from
31720 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
31730 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
31740 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
31750 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
31760 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
31770 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
31780 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
31790 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
317a0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
317b0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
317c0 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69  read.  If N or i
317d0 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73  Offset is.** les
317e0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51  s than zero, [SQ
317f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
31800 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
31810 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a  ata is read..**.
31820 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f  ** An attempt to
31830 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78   read from an ex
31840 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pired [BLOB hand
31850 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61  le] fails with a
31860 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
31870 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
31880 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  ]..**.** On succ
31890 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69  ess, SQLITE_OK i
318a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f  s returned..** O
318b0 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72  therwise, an [er
318c0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
318d0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
318e0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
318f0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
31900 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 35  ments:.** [H1785
31910 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 37  3] [H17856] [H17
31920 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 48  859] [H17862] [H
31930 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d 20  17863] [H17865] 
31940 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74 20  [H17868].*/.int 
31950 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
31960 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  d(sqlite3_blob *
31970 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e  , void *Z, int N
31980 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
31990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
319a0 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
319b0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
319c0 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c  tally {H17870} <
319d0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30230>.**.** Th
319e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
319f0 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
31a00 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
31a10 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
31a20 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
31a30 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
31a40 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
31a50 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
31a60 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69  he buffer Z.** i
31a70 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  nto the open BLO
31a80 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
31a90 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
31aa0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f  *.** If the [BLO
31ab0 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
31ac0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
31ad0 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
31ae0 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
31af0 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
31b00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
31b10 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
31b20 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
31b30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
31b40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
31b50 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
31b60 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
31b70 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
31b80 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
31b90 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a  e BLOB; it is.**
31ba0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
31bb0 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
31bc0 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69  ze of a BLOB usi
31bd0 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20  ng this API..** 
31be0 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
31bf0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
31c00 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
31c10 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
31c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
31c30 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
31c40 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
31c50 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a  itten.  If N is.
31c60 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
31c70 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
31c80 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
31c90 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
31ca0 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74  ten..**.** An at
31cb0 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74  tempt to write t
31cc0 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  o an expired [BL
31cd0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
31ce0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
31cf0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
31d00 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 74 65  E_ABORT].  Write
31d10 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68  s to the BLOB th
31d20 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62  at occurred.** b
31d30 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20  efore the [BLOB 
31d40 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20  handle] expired 
31d50 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62  are not rolled b
31d60 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78  ack by the.** ex
31d70 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  piration of the 
31d80 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f  handle, though o
31d90 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63  f course those c
31da0 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20  hanges might.** 
31db0 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72  have been overwr
31dc0 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61  itten by the sta
31dd0 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69  tement that expi
31de0 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  red the BLOB han
31df0 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68  dle.** or by oth
31e00 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73  er independent s
31e10 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
31e20 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
31e30 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
31e40 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  ed..** Otherwise
31e50 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64  , an  [error cod
31e60 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
31e70 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
31e80 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
31e90 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
31ea0 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37  ** [H17873] [H17
31eb0 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48  874] [H17875] [H
31ec0 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20  17876] [H17877] 
31ed0 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32  [H17879] [H17882
31ee0 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48  ] [H17885].** [H
31ef0 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17888].*/.int sq
31f00 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
31f10 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
31f20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
31f30 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
31f40 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
31f50 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
31f60 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
31f70 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31  s {H11200} <S201
31f80 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  00>.**.** A virt
31f90 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28  ual filesystem (
31fa0 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69  VFS) is an [sqli
31fb0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a  te3_vfs] object.
31fc0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75  ** that SQLite u
31fd0 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a  ses to interact.
31fe0 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  ** with the unde
31ff0 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
32000 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53   system.  Most S
32010 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d  QLite builds com
32020 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67  e with a.** sing
32030 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74  le default VFS t
32040 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61  hat is appropria
32050 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20  te for the host 
32060 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77  computer..** New
32070 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65   VFSes can be re
32080 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69  gistered and exi
32090 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20  sting VFSes can 
320a0 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e  be unregistered.
320b0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
320c0 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  g interfaces are
320d0 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a   provided..**.**
320e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
320f0 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
32100 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
32110 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
32120 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
32130 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
32140 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d  ensitive..** Nam
32150 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  es are zero-term
32160 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
32170 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72  ings..** If ther
32180 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
32190 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
321a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
321b0 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
321c0 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
321d0 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e  lt VFS is return
321e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46  ed..**.** New VF
321f0 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
32200 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
32210 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
32220 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20  ** Each new VFS 
32230 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
32240 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
32250 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
32260 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
32270 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
32280 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
32290 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
322a0 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
322b0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
322c0 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
322d0 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
322e0 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
322f0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
32300 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
32310 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
32320 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
32330 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
32340 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
32350 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
32360 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
32370 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
32380 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
32390 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
323a0 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
323b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
323c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
323d0 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56  * Unregister a V
323e0 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
323f0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
32400 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
32410 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c  ** If the defaul
32420 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
32430 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
32440 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
32450 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
32460 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
32470 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
32480 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
32490 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
324a0 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30   [H11203] [H1120
324b0 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31  6] [H11209] [H11
324c0 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48  212] [H11215] [H
324d0 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65  11218].*/.sqlite
324e0 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
324f0 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
32500 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
32510 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
32520 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
32530 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
32540 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
32550 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
32560 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
32570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32580 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d  Mutexes {H17000}
32590 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
325a0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
325b0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
325c0 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
325d0 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
325e0 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  n. Though they a
325f0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
32600 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
32610 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
32620 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
32630 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
32640 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
32650 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
32660 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
32670 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
32680 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
32690 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
326a0 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65  ations.** of the
326b0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
326c0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
326d0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
326e0 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
326f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
32700 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
32710 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   The following.*
32720 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32730 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
32740 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
32750 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
32760 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
32770 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
32780 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
32790 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
327a0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
327b0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
327c0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
327d0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
327e0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
327f0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
32800 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
32810 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
32820 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
32830 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
32840 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
32850 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
32860 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
32870 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54  tion.  The SQLIT
32880 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
32890 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
328a0 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
328b0 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
328c0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
328d0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
328e0 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55  r use on OS/2, U
328f0 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73  nix, and Windows
32900 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ..**.** If SQLit
32910 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
32920 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
32930 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
32940 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
32950 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
32960 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
32970 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
32980 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
32990 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
329a0 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
329b0 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
329c0 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
329d0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
329e0 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
329f0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
32a00 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
32a10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
32a20 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
32a30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
32a40 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
32a50 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
32a60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
32a70 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
32a80 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
32a90 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
32aa0 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
32ab0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
32ac0 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68  *.** {H17011} Th
32ad0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
32ae0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
32af0 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
32b00 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
32b10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32b20 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49  o it. {H17012} I
32b30 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  f it returns NUL
32b40 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20  L.** that means 
32b50 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75  that a mutex cou
32b60 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  ld not be alloca
32b70 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51  ted. {H17013} SQ
32b80 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
32b90 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
32ba0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
32bb0 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20  r. {H17014} The 
32bc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
32bd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
32be0 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
32bf0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
32c00 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
32c10 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
32c20 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
32c30 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
32c40 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
32c50 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
32c60 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
32c70 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
32c80 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
32c90 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
32ca0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
32cb0 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
32cc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
32cd0 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
32ce0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
32cf0 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
32d00 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
32d10 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
32d20 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35  l>.**.** {H17015
32d30 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  } The first two 
32d40 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
32d50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
32d60 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
32d70 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
32d80 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
32d90 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
32da0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
32db0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
32dc0 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
32dd0 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
32de0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
32df0 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a   is used. {END}.
32e00 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
32e10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
32e20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
32e30 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
32e40 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
32e50 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
32e60 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
32e70 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
32e80 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
32e90 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74  o.  {H17016} But
32ea0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
32eb0 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
32ec0 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
32ed0 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
32ee0 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
32ef0 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66  e.  {END} If a f
32f00 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
32f10 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
32f20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
32f30 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
32f40 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
32f50 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
32f60 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
32f70 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
32f80 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
32f90 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
32fa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d  ..**.** {H17017}
32fb0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
32fc0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
32fd0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
32fe0 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
32ff0 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
33000 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
33010 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b  xisting mutex. {
33020 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69  END}  Four stati
33030 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
33040 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
33050 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
33060 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
33070 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
33080 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
33090 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
330a0 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
330b0 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
330c0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
330d0 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
330e0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
330f0 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
33100 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
33110 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
33120 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
33130 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
33140 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
33150 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
33160 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
33170 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68  {H17018} Note th
33180 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
33190 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
331a0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
331b0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
331c0 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
331d0 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
331e0 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
331f0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
33200 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
33210 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
33220 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30  ery call.  {H170
33230 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20  34} But for the 
33240 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
33250 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
33260 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
33270 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
33280 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
33290 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
332a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d  ..**.** {H17019}
332b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
332c0 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
332d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
332e0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
332f0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
33300 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20  mutex. {H17020} 
33310 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
33320 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
33330 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
33340 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
33350 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32  llocates. {A1702
33360 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  1} The dynamic m
33370 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
33380 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65  be in.** use whe
33390 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c  n they are deall
333a0 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d  ocated. {A17022}
333b0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
333c0 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
333d0 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
333e0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
333f0 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30   behavior. {H170
33400 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72  23} SQLite never
33410 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
33420 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20  a static mutex. 
33430 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
33440 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
33450 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ter() and sqlite
33460 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f  3_mutex_try() ro
33470 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a  utines attempt.*
33480 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74  * to enter a mut
33490 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20  ex. {H17024} If 
334a0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69  another thread i
334b0 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e  s already within
334c0 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73   the mutex,.** s
334d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
334e0 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20  er() will block 
334f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
33500 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74  x_try() will ret
33510 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55  urn.** SQLITE_BU
33520 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68  SY. {H17025}  Th
33530 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
33540 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  try() interface 
33550 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
33560 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  OK].** upon succ
33570 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b  essful entry.  {
33580 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20  H17026} Mutexes 
33590 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
335a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
335b0 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65  CURSIVE can be e
335c0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
335d0 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
335e0 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31  e thread..** {H1
335f0 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61  7027} In such ca
33600 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
33610 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
33620 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
33630 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
33640 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
33650 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b  ** can enter.  {
33660 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73  A17028} If the s
33670 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
33680 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
33690 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
336a0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
336b0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
336c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
336d0 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69  ** {H17029} SQLi
336e0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
336f0 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
33700 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
33710 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
33720 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73  ..**.** Some sys
33730 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
33740 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
33750 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
33760 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
33770 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
33780 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
33790 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
337a0 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
337b0 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
337c0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
337d0 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48  SQLITE_BUSY.  {H
337e0 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74  17030} The SQLit
337f0 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72  e core only ever
33800 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33   uses.** sqlite3
33810 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20  _mutex_try() as 
33820 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  an optimization 
33830 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70  so this is accep
33840 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  table behavior..
33850 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54  **.** {H17031} T
33860 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
33870 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
33880 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
33890 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
338a0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
338b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
338c0 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20  .  {A17032} The 
338d0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
338e0 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
338f0 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
33900 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
33910 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
33920 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
33930 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
33940 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d  cated.  {H17033}
33950 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
33960 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e  never do either.
33970 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
33980 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
33990 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
339a0 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d  ter(), sqlite3_m
339b0 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a  utex_try(), or.*
339c0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
339d0 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c  leave() is a NUL
339e0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
339f0 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e  all three routin
33a00 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20  es.** behave as 
33a10 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  no-ops..**.** Se
33a20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33a30 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61  _mutex_held()] a
33a40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  nd [sqlite3_mute
33a50 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f  x_notheld()]..*/
33a60 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
33a70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
33a80 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73  loc(int);.void s
33a90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
33aa0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
33ab0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33ac0 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69  mutex_enter(sqli
33ad0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
33ae0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
33af0 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ry(sqlite3_mutex
33b00 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
33b10 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c  _mutex_leave(sql
33b20 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f  ite3_mutex*);../
33b30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
33b40 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a  utex Methods Obj
33b50 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32  ect {H17120} <S2
33b60 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0130>.** EXPERIM
33b70 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ENTAL.**.** An i
33b80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
33b90 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65  structure define
33ba0 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  s the low-level 
33bb0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
33bc0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64   to allocate and
33bd0 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a   use mutexes..**
33be0 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65  .** Usually, the
33bf0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69   default mutex i
33c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70  mplementations p
33c10 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74  rovided by SQLit
33c20 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69  e are.** suffici
33c30 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65  ent, however the
33c40 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70   user has the op
33c50 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75  tion of substitu
33c60 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a  ting a custom.**
33c70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33c80 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20  for specialized 
33c90 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73  deployments or s
33ca0 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68  ystems for which
33cb0 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20   SQLite.** does 
33cc0 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75  not provide a su
33cd0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
33ce0 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63  ation. In this c
33cf0 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a  ase, the user.**
33d00 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70   creates and pop
33d10 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e  ulates an instan
33d20 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
33d30 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20  ture to pass.** 
33d40 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
33d50 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74  g() along with t
33d60 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
33d70 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  G_MUTEX] option.
33d80 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  .** Additionally
33d90 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  , an instance of
33da0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
33db0 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61  can be used as a
33dc0 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69  n.** output vari
33dd0 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69  able when queryi
33de0 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f  ng the system fo
33df0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75  r the current mu
33e00 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
33e10 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65  ation, using the
33e20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
33e30 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  GETMUTEX] option
33e40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
33e50 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
33e60 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
33e70 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
33e80 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
33e90 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
33ea0 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
33eb0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
33ec0 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
33ed0 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75  {H17001} The xMu
33ee0 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
33ef0 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20  shall be called 
33f00 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66  by SQLite once f
33f10 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63  or each.** effec
33f20 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71  tive call to [sq
33f30 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
33f40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ()]..**.** The x
33f50 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20  MutexEnd method 
33f60 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
33f70 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
33f80 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
33f90 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f  of system shutdo
33fa0 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  wn by the sqlite
33fb0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e  3_shutdown() fun
33fc0 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d  ction. The.** im
33fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33fe0 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65  this method is e
33ff0 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61  xpected to relea
34000 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69  se all outstandi
34010 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ng.** resources 
34020 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
34030 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d  mutex methods im
34040 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73  plementation, es
34050 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73  pecially.** thos
34060 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  e obtained by th
34070 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
34080 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68  hod. {H17003} Th
34090 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a  e xMutexEnd().**
340a0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
340b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   be invoked once
340c0 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74   for each call t
340d0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  o [sqlite3_shutd
340e0 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  own()]..**.** Th
340f0 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65  e remaining seve
34100 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  n methods define
34110 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
34120 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63  ure (xMutexAlloc
34130 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c  ,.** xMutexFree,
34140 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d   xMutexEnter, xM
34150 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c  utexTry, xMutexL
34160 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64  eave, xMutexHeld
34170 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f   and.** xMutexNo
34180 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74  theld) implement
34190 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
341a0 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65  nterfaces (respe
341b0 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20  ctively):.**.** 
341c0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  <ul>.**   <li>  
341d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
341e0 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  lloc()] </li>.**
341f0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
34200 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20  3_mutex_free()] 
34210 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
34220 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
34230 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  enter()] </li>.*
34240 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
34250 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20  e3_mutex_try()] 
34260 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
34270 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
34280 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  leave()] </li>.*
34290 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
342a0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
342b0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
342c0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
342d0 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  _notheld()] </li
342e0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
342f0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
34300 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65  ence is that the
34310 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
34320 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e  XXX functions en
34330 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76  umerated.** abov
34340 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  e silently ignor
34350 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e  e any invocation
34360 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55  s that pass a NU
34370 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
34380 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64  ad.** of a valid
34390 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54   mutex handle. T
343a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
343b0 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64  ns of the method
343c0 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
343d0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
343e0 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  re not required 
343f0 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63  to handle this c
34400 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ase, the results
34410 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61  .** of passing a
34420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
34430 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64  stead of a valid
34440 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72   mutex handle ar
34450 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28  e undefined.** (
34460 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70  i.e. it is accep
34470 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65  table to provide
34480 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
34490 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74  on that segfault
344a0 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61  s if.** it is pa
344b0 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ssed a NULL poin
344c0 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ter)..*/.typedef
344d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
344e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71  mutex_methods sq
344f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
34500 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
34510 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
34520 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  s {.  int (*xMut
34530 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20  exInit)(void);. 
34540 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64   int (*xMutexEnd
34550 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74  )(void);.  sqlit
34560 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74  e3_mutex *(*xMut
34570 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20  exAlloc)(int);. 
34580 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72   void (*xMutexFr
34590 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ee)(sqlite3_mute
345a0 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
345b0 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69  MutexEnter)(sqli
345c0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
345d0 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29  int (*xMutexTry)
345e0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
345f0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
34600 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33  exLeave)(sqlite3
34610 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
34620 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73   (*xMutexHeld)(s
34630 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
34640 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e  .  int (*xMutexN
34650 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  otheld)(sqlite3_
34660 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a  mutex *);.};../*
34670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
34680 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e  tex Verification
34690 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 38   Routines {H1708
346a0 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 30  0} <S20130> <S30
346b0 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  800>.**.** The s
346c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
346d0 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
346e0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
346f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
34700 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
34710 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
34720 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31   statements. {H1
34730 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 65  7081} The SQLite
34740 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75   core.** never u
34750 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
34760 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65  es except inside
34770 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64   an assert() and
34780 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
34790 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
347a0 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20  follow the lead 
347b0 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b 48  of the core.  {H
347c0 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 20  17082} The core 
347d0 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
347e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
347f0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
34800 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
34810 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
34820 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
34830 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 7d   flag.  {A17087}
34840 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   External mutex 
34850 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
34860 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75  ** are only requ
34870 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20  ired to provide 
34880 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
34890 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69  f SQLITE_DEBUG i
348a0 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64  s.** defined and
348b0 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f   if NDEBUG is no
348c0 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  t defined..**.**
348d0 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 20   {H17083} These 
348e0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
348f0 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
34900 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
34910 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
34920 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
34930 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
34940 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
34950 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58  thread..**.** {X
34960 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c 65  17084} The imple
34970 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74  mentation is not
34980 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
34990 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f  vided versions o
349a0 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  f these.** routi
349b0 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c  nes that actuall
349c0 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69  y work. If the i
349d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
349e0 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
349f0 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
34a00 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
34a10 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
34a20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
34a30 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 61   stubs that alwa
34a40 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75  ys.** return tru
34a50 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
34a60 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
34a70 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61  ous assertion fa
34a80 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ilures..**.** {H
34a90 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 72  17085} If the ar
34aa0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
34ab0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
34ac0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
34ad0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
34ae0 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
34af0 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69  rn 1.  {END} Thi
34b00 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
34b10 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
34b20 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
34b30 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
34b40 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
34b50 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
34b60 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
34b70 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
34b80 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
34b90 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69  ause the build i
34ba0 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d  s not.** using m
34bb0 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20  utexes.  And we 
34bc0 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  do not want the 
34bd0 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e  assert() contain
34be0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20  ing the.** call 
34bf0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
34c00 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c  _held() to fail,
34c10 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   so a non-zero r
34c20 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20  eturn is.** the 
34c30 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e  appropriate thin
34c40 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38  g to do.  {H1708
34c50 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  6} The sqlite3_m
34c60 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a  utex_notheld().*
34c70 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  * interface shou
34c80 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31  ld also return 1
34c90 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55   when given a NU
34ca0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69  LL pointer..*/.i
34cb0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
34cc0 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
34cd0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
34ce0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
34cf0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
34d00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34d10 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b  F: Mutex Types {
34d20 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 3e  H17001} <H17000>
34d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
34d40 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
34d50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b  )] interface tak
34d60 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
34d70 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73  ment.** which is
34d80 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
34d90 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e  teger constants.
34da0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f  .**.** The set o
34db0 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  f static mutexes
34dc0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
34dd0 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65   one SQLite rele
34de0 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  ase to the.** ne
34df0 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
34e00 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20  s that override 
34e10 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74  the built-in mut
34e20 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65  ex logic must be
34e30 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20  .** prepared to 
34e40 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69  accommodate addi
34e50 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
34e60 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  texes..*/.#defin
34e70 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  e SQLITE_MUTEX_F
34e80 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  AST             
34e90 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
34ea0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
34eb0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
34ec0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
34ed0 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20  TATIC_MASTER    
34ee0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
34ef0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
34f00 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71  M       3  /* sq
34f10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
34f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34f30 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
34f40 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f  M2      4  /* NO
34f50 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e  T USED */.#defin
34f60 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
34f70 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20  TATIC_OPEN      
34f80 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72  4  /* sqlite3Btr
34f90 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66  eeOpen() */.#def
34fa0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
34fb0 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20  _STATIC_PRNG    
34fc0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
34fd0 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66  random() */.#def
34fe0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
34ff0 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20  _STATIC_LRU     
35000 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    6  /* lru page
35010 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   list */.#define
35020 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
35030 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37  ATIC_LRU2      7
35040 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
35050 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
35060 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20  I3REF: Retrieve 
35070 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20  the mutex for a 
35080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35090 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 31  ion {H17002} <H1
350a0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7000>.**.** This
350b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
350c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65  ns a pointer the
350d0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
350e0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a   object that .**
350f0 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65   serializes acce
35100 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  ss to the [datab
35110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35120 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67  given in the arg
35130 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68  ument.** when th
35140 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
35150 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64  e] is Serialized
35160 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 72  ..** If the [thr
35170 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
35180 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72  Single-thread or
35190 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68   Multi-thread th
351a0 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  en this.** routi
351b0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
351c0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
351d0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
351e0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71  ite3_db_mutex(sq
351f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
35200 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65  CAPI3REF: Low-Le
35210 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44  vel Control Of D
35220 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48  atabase Files {H
35230 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11300} <S30800>.
35240 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54  **.** {H11301} T
35250 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
35260 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
35270 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69  rface makes a di
35280 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  rect call to the
35290 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
352a0 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20   method for the 
352b0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
352c0 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ods] object asso
352d0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61  ciated.** with a
352e0 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
352f0 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20  base identified 
35300 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  by the second ar
35310 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d  gument. {H11302}
35320 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   The.** name of 
35330 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
35340 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
35350 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
35360 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68  e by the.** <a h
35370 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68  ref="lang_attach
35380 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61  .html">ATTACH</a
35390 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68  > SQL command th
353a0 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a  at opened the.**
353b0 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33   database. {H113
353c0 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74  03} To control t
353d0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
353e0 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e   file, use the n
353f0 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72  ame "main".** or
35400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35410 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 68   {H11304} The th
35420 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
35430 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
35440 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65  s routine.** are
35450 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79   passed directly
35460 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
35470 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
35480 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a   parameters of.*
35490 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * the xFileContr
354a0 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31  ol method.  {H11
354b0 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20  305} The return 
354c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69  value of the xFi
354d0 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74  leControl.** met
354e0 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  hod becomes the 
354f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35500 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
35510 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20  .** {H11306} If 
35520 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
35530 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64  eter (zDbName) d
35540 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68  oes not match th
35550 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a  e name of any.**
35560 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66   open database f
35570 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ile, then SQLITE
35580 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e  _ERROR is return
35590 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69  ed. {H11307} Thi
355a0 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
355b0 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
355c0 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
355d0 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
355e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
355f0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
35600 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31  _errmsg()]. {A11
35610 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79  308} The underly
35620 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  ing xFileControl
35630 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a   method might.**
35640 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c   also return SQL
35650 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31  ITE_ERROR.  {A11
35660 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f  309} There is no
35670 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75   way to distingu
35680 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61  ish between.** a
35690 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e  n incorrect zDbN
356a0 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54  ame and an SQLIT
356b0 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66  E_ERROR return f
356c0 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69  rom the underlyi
356d0 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  ng.** xFileContr
356e0 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d  ol method. {END}
356f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
35700 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
35710 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
35720 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
35730 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
35740 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
35750 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
35760 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
35770 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e  3REF: Testing In
35780 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d  terface {H11400}
35790 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
357a0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74  The sqlite3_test
357b0 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72  _control() inter
357c0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
357d0 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61  read out interna
357e0 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51  l.** state of SQ
357f0 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65  Lite and to inje
35800 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53  ct faults into S
35810 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e  QLite for testin
35820 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20  g.** purposes.  
35830 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
35840 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74  ter is an operat
35850 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65  ion code that de
35860 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20  termines.** the 
35870 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c  number, meaning,
35880 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f   and operation o
35890 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  f all subsequent
358a0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
358b0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
358c0 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65  e is not for use
358d0 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   by applications
358e0 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c  .  It exists sol
358f0 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66  ely.** for verif
35900 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74  ying the correct
35910 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
35920 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
35930 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  .  Depending.** 
35940 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74  on how the SQLit
35950 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d  e library is com
35960 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65  piled, this inte
35970 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20  rface might not 
35980 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  exist..**.** The
35990 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
359a0 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c  operation codes,
359b0 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c   their meanings,
359c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a   the parameters.
359d0 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e  ** they take, an
359e0 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 61  d what they do a
359f0 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74  re all subject t
35a00 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
35a10 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69   notice..** Unli
35a20 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53  ke most of the S
35a30 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 20  QLite API, this 
35a40 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
35a50 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a  guaranteed to.**
35a60 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74   operate consist
35a70 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72  ently from one r
35a80 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
35a90 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  xt..*/.int sqlit
35aa0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
35ab0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
35ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
35ad0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
35ae0 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73   Operation Codes
35af0 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30   {H11410} <H1140
35b00 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
35b10 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
35b20 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e   valid operation
35b30 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73   code parameters
35b40 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20   used.** as the 
35b50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
35b60 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  o [sqlite3_test_
35b70 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a  control()]..**.*
35b80 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65  * These paramete
35b90 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61  rs and their mea
35ba0 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63  nings are subjec
35bb0 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77  t to change.** w
35bc0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20  ithout notice.  
35bd0 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65  These values are
35be0 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72   for testing pur
35bf0 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41  poses only..** A
35c00 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
35c10 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f  ld not use any o
35c20 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
35c30 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  rs or the.** [sq
35c40 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
35c50 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
35c60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
35c70 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47  TE_TESTCTRL_PRNG
35c80 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20  _SAVE           
35c90 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
35ca0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
35cb0 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20  RNG_RESTORE     
35cc0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
35cd0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
35ce0 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20  L_PRNG_RESET    
35cf0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
35d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
35d10 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54  CTRL_BITVEC_TEST
35d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a                8.
35d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
35d40 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e  ESTCTRL_FAULT_IN
35d50 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20  STALL           
35d60 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
35d70 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47  E_TESTCTRL_BENIG
35d80 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20  N_MALLOC_HOOKS  
35d90 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
35da0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45  LITE_TESTCTRL_PE
35db0 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20  NDING_BYTE      
35dc0 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20        11../*.** 
35dd0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65  CAPI3REF: SQLite
35de0 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 20   Runtime Status 
35df0 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30 30  {H17200} <S60200
35e00 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
35e10 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  L.**.** This int
35e20 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
35e30 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69  o retrieve runti
35e40 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d  me status inform
35e50 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74  ation.** about t
35e60 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f  he preformance o
35e70 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70  f SQLite, and op
35e80 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65  tionally to rese
35e90 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67  t various.** hig
35ea0 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 54  hwater marks.  T
35eb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35ec0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
35ed0 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
35ee0 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74  specific paramet
35ef0 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20  er to measure.  
35f00 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67  Recognized integ
35f10 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20  er codes.** are 
35f20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c  of the form [SQL
35f30 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52  ITE_STATUS_MEMOR
35f40 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f  Y_USED | SQLITE_
35f50 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20  STATUS_...]..** 
35f60 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  The current valu
35f70 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  e of the paramet
35f80 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  er is returned i
35f90 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a  nto *pCurrent..*
35fa0 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 72 65  * The highest re
35fb0 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 20  corded value is 
35fc0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69  returned in *pHi
35fd0 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 65  ghwater.  If the
35fe0 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73  .** resetFlag is
35ff0 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
36000 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 76  highest record v
36010 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 66  alue is reset af
36020 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  ter.** *pHighwat
36030 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 53  er is written. S
36040 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 64  ome parameters d
36050 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 65  o not record the
36060 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75   highest.** valu
36070 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 61  e.  For those pa
36080 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68  rameters.** noth
36090 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69  ing is written i
360a0 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 20  nto *pHighwater 
360b0 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c 61  and the resetFla
360c0 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  g is ignored..**
360d0 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72   Other parameter
360e0 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68  s record only th
360f0 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  e highwater mark
36100 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72   and not the cur
36110 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20  rent.** value.  
36120 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 72  For these latter
36130 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68   parameters noth
36140 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69  ing is written i
36150 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a  nto *pCurrent..*
36160 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
36170 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
36180 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
36190 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  nd a non-zero.**
361a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
361b0 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
361c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
361d0 74 68 72 65 61 64 73 61 66 65 20 62 75 74 20 69  threadsafe but i
361e0 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54  s not atomic.  T
361f0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 0a  his routine can.
36200 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20  ** called while 
36210 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72  other threads ar
36220 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61  e running the sa
36230 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20  me or different 
36240 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66  SQLite.** interf
36250 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74  aces.  However t
36260 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
36270 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20  ed in *pCurrent 
36280 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  and.** *pHighwat
36290 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73  er reflect the s
362a0 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20  tatus of SQLite 
362b0 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69  at different poi
362c0 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61  nts in time.** a
362d0 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  nd it is possibl
362e0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
362f0 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e  hread might chan
36300 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ge the parameter
36310 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74  .** in between t
36320 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70  he times when *p
36330 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69  Current and *pHi
36340 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74  ghwater are writ
36350 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ten..**.** See a
36360 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62  lso: [sqlite3_db
36370 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51  _status()].*/.SQ
36380 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
36390 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  L int sqlite3_st
363a0 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74  atus(int op, int
363b0 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20   *pCurrent, int 
363c0 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74  *pHighwater, int
363d0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f   resetFlag);.../
363e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
363f0 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73  tatus Parameters
36400 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30   {H17250} <H1720
36410 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
36420 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  AL.**.** These i
36430 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
36440 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f   designate vario
36450 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74  us run-time stat
36460 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  us parameters.**
36470 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74   that can be ret
36480 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
36490 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a  3_status()]..**.
364a0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
364b0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d  QLITE_STATUS_MEM
364c0 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a  ORY_USED</dt>.**
364d0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
364e0 74 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65  ter is the curre
364f0 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  nt amount of mem
36500 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a  ory checked out.
36510 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
36520 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74  3_malloc()], eit
36530 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20  her directly or 
36540 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  indirectly.  The
36550 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75  .** figure inclu
36560 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74  des calls made t
36570 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
36580 63 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c  c()] by the appl
36590 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69  ication.** and i
365a0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75  nternal memory u
365b0 73 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69  sage by the SQLi
365c0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72  te library.  Scr
365d0 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  atch memory.** c
365e0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51  ontrolled by [SQ
365f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
36600 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61  TCH] and auxilia
36610 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a  ry page-cache.**
36620 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c   memory controll
36630 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  ed by [SQLITE_CO
36640 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20  NFIG_PAGECACHE] 
36650 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
36660 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d  in.** this param
36670 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e  eter.  The amoun
36680 74 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  t returned is th
36690 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c  e sum of the all
366a0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73  ocation.** sizes
366b0 20 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20   as reported by 
366c0 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64  the xSize method
366d0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   in [sqlite3_mem
366e0 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a  _methods].</dd>.
366f0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
36700 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53  _STATUS_MALLOC_S
36710 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IZE</dt>.** <dd>
36720 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72  This parameter r
36730 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65  ecords the large
36740 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  st memory alloca
36750 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20  tion request.** 
36760 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
36770 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
36780 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
36790 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a  ()] (or their.**
367a0 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61   internal equiva
367b0 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68  lents).  Only th
367c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
367d0 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67   in the.** *pHig
367e0 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72  hwater parameter
367f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61   to [sqlite3_sta
36800 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74  tus()] is of int
36810 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20  erest.  .** The 
36820 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e  value written in
36830 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74  to the *pCurrent
36840 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e   parameter is un
36850 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
36860 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
36870 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f  TATUS_PAGECACHE_
36880 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  USED</dt>.** <dd
36890 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  >This parameter 
368a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
368b0 65 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64  er of pages used
368c0 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   out of the.** [
368d0 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79  pagecache memory
368e0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74   allocator] that
368f0 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   was configured 
36900 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54  using .** [SQLIT
36910 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
36920 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c  HE].  The.** val
36930 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69  ue returned is i
36940 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20  n pages, not in 
36950 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bytes.</dd>.**.*
36960 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41  * <dt>SQLITE_STA
36970 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56  TUS_PAGECACHE_OV
36980 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  ERFLOW</dt>.** <
36990 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
369a0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
369b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
369c0 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61   page cache.** a
369d0 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20  llocation which 
369e0 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61  could not be sta
369f0 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b  tisfied by the [
36a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
36a10 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66  GECACHE].** buff
36a20 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72  er and where for
36a30 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20  ced to overflow 
36a40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
36a50 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72  oc()].  The.** r
36a60 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e  eturned value in
36a70 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f  cludes allocatio
36a80 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77  ns that overflow
36a90 65 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a  ed because they.
36aa0 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72  ** where too lar
36ab0 67 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61  ge (they were la
36ac0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73  rger than the "s
36ad0 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  z" parameter to.
36ae0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
36af0 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e  G_PAGECACHE]) an
36b00 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68  d allocations th
36b10 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65  at overflowed be
36b20 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63  cause.** no spac
36b30 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68  e was left in th
36b40 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64  e page cache.</d
36b50 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
36b60 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43  ITE_STATUS_PAGEC
36b70 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a  ACHE_SIZE</dt>.*
36b80 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
36b90 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
36ba0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20   largest memory 
36bb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
36bc0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20  st.** handed to 
36bd0 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72  [pagecache memor
36be0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f  y allocator].  O
36bf0 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65  nly the value re
36c00 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a  turned in the.**
36c10 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72   *pHighwater par
36c20 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
36c30 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20  e3_status()] is 
36c40 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a  of interest.  .*
36c50 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74  * The value writ
36c60 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43  ten into the *pC
36c70 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  urrent parameter
36c80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
36c90 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
36ca0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
36cb0 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a  TCH_USED</dt>.**
36cc0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
36cd0 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20  ter returns the 
36ce0 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61  number of alloca
36cf0 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f  tions used out o
36d00 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63  f the.** [scratc
36d10 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  h memory allocat
36d20 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75  or] configured u
36d30 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  sing.** [SQLITE_
36d40 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e  CONFIG_SCRATCH].
36d50 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
36d60 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63  rned is in alloc
36d70 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69  ations, not.** i
36d80 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20  n bytes.  Since 
36d90 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
36da0 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e  may only have on
36db0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
36dc0 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64  tion.** outstand
36dd0 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69  ing at time, thi
36de0 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f  s parameter also
36df0 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d   reports the num
36e00 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a  ber of threads.*
36e10 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20  * using scratch 
36e20 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61  memory at the sa
36e30 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a  me time.</dd>.**
36e40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
36e50 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56  TATUS_SCRATCH_OV
36e60 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  ERFLOW</dt>.** <
36e70 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
36e80 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
36e90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
36ea0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a   scratch memory.
36eb0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68  ** allocation wh
36ec0 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  ich could not be
36ed0 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74   statisfied by t
36ee0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
36ef0 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75  G_SCRATCH].** bu
36f00 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66  ffer and where f
36f10 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f  orced to overflo
36f20 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  w to [sqlite3_ma
36f30 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61  lloc()].  The va
36f40 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lues.** returned
36f50 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f   include overflo
36f60 77 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72  ws because the r
36f70 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74  equested allocat
36f80 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c  ion was too.** l
36f90 61 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20  arger (that is, 
36fa0 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75  because the requ
36fb0 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e  ested allocation
36fc0 20 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e   was larger than
36fd0 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72   the.** "sz" par
36fe0 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54  ameter to [SQLIT
36ff0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
37000 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e  ]) and because n
37010 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
37020 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61  .** slots were a
37030 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64  vailable..** </d
37040 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
37050 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
37060 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  CH_SIZE</dt>.** 
37070 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
37080 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  er records the l
37090 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c  argest memory al
370a0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
370b0 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73  .** handed to [s
370c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c  cratch memory al
370d0 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20  locator].  Only 
370e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
370f0 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48  ed in the.** *pH
37100 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74  ighwater paramet
37110 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  er to [sqlite3_s
37120 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69  tatus()] is of i
37130 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68  nterest.  .** Th
37140 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20  e value written 
37150 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65  into the *pCurre
37160 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nt parameter is 
37170 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
37180 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
37190 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53  _STATUS_PARSER_S
371a0 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  TACK</dt>.** <dd
371b0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  >This parameter 
371c0 72 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70  records the deep
371d0 65 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b  est parser stack
371e0 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a  .  It is only.**
371f0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53   meaningful if S
37200 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
37210 64 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d  d with [YYTRACKM
37220 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f  AXSTACKDEPTH].</
37230 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  dd>.** </dl>.**.
37240 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61  ** New status pa
37250 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20  rameters may be 
37260 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20  added from time 
37270 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66  to time..*/.#def
37280 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
37290 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20  S_MEMORY_USED   
372a0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
372b0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50   SQLITE_STATUS_P
372c0 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20  AGECACHE_USED   
372d0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
372e0 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45  LITE_STATUS_PAGE
372f0 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20  CACHE_OVERFLOW  
37300 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
37310 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48  E_STATUS_SCRATCH
37320 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a  _USED         3.
37330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
37340 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56  TATUS_SCRATCH_OV
37350 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65  ERFLOW     4.#de
37360 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
37370 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20  US_MALLOC_SIZE  
37380 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
37390 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
373a0 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20  PARSER_STACK    
373b0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
373c0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47  QLITE_STATUS_PAG
373d0 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20  ECACHE_SIZE     
373e0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
373f0 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43  TE_STATUS_SCRATC
37400 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38  H_SIZE         8
37410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37420 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
37430 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31  ction Status {H1
37440 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a  7500} <S60200>.*
37450 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
37460 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
37470 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ace is used to r
37480 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20  etrieve runtime 
37490 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69  status informati
374a0 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73  on .** about a s
374b0 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20  ingle [database 
374c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
374d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
374e0 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   is the.** datab
374f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
37500 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65  bject to be inte
37510 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73  rrogated.  The s
37520 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a  econd argument.*
37530 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  * is the paramet
37540 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74  er to interrogat
37550 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74  e.  Currently, t
37560 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20  he only allowed 
37570 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65  value.** for the
37580 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37590 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53  r is [SQLITE_DBS
375a0 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f  TATUS_LOOKASIDE_
375b0 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69  USED]..** Additi
375c0 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c  onal options wil
375d0 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20  l likely appear 
375e0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
375f0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
37600 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20  .** The current 
37610 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71  value of the req
37620 75 65 73 74 65 64 20 70 61 72 61 6d 65 74 65 72  uested parameter
37630 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37640 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68   *pCur.** and th
37650 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e  e highest instan
37660 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73  taneous value is
37670 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
37680 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68  Hiwtr.  If.** th
37690 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72  e resetFlg is tr
376a0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67  ue, then the hig
376b0 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f  hest instantaneo
376c0 75 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72  us value is.** r
376d0 65 73 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74  eset back down t
376e0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
376f0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  lue..**.** See a
37700 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74  lso: [sqlite3_st
37710 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  atus()] and [sql
37720 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73  ite3_stmt_status
37730 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
37740 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
37750 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
37760 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
37770 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c 20 69  op, int *pCur, i
37780 6e 74 20 2a 70 48 69 77 74 72 2c 20 69 6e 74 20  nt *pHiwtr, int 
37790 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a  resetFlg);../*.*
377a0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74  * CAPI3REF: Stat
377b0 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f  us Parameters fo
377c0 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
377d0 63 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 7d 20  ctions {H17520} 
377e0 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 50 45  <H17500>.** EXPE
377f0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 53  RIMENTAL.**.** S
37800 74 61 74 75 73 20 76 65 72 62 73 20 66 6f 72 20  tatus verbs for 
37810 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
37820 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  us()]..**.** <dl
37830 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
37840 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49  DBSTATUS_LOOKASI
37850 44 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20  DE_USED</dt>.** 
37860 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
37870 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  er returns the n
37880 75 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61 73 69  umber of lookasi
37890 64 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74 73 20  de memory slots 
378a0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63 68 65  currently.** che
378b0 63 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e 0a 2a  cked out.</dd>.*
378c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
378d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54  ne SQLITE_DBSTAT
378e0 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45  US_LOOKASIDE_USE
378f0 44 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a 2a 20  D     0.../*.** 
37900 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
37910 65 64 20 53 74 61 74 65 6d 65 6e 74 20 53 74 61  ed Statement Sta
37920 74 75 73 20 7b 48 31 37 35 35 30 7d 20 3c 53 36  tus {H17550} <S6
37930 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
37940 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 63 68  ENTAL.**.** Each
37950 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37960 65 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20 76 61  ent maintains va
37970 72 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  rious.** [SQLITE
37980 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54  _STMTSTATUS_SORT
37990 20 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74 68 61   | counters] tha
379a0 74 20 6d 65 61 73 75 72 65 20 74 68 65 20 6e 75  t measure the nu
379b0 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d 65 73  mber.** of times
379c0 20 69 74 20 68 61 73 20 70 65 72 66 6f 72 6d 65   it has performe
379d0 64 20 73 70 65 63 69 66 69 63 20 6f 70 65 72 61  d specific opera
379e0 74 69 6f 6e 73 2e 20 20 54 68 65 73 65 20 63 6f  tions.  These co
379f0 75 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20 62 65  unters can.** be
37a00 20 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74 6f 72   used to monitor
37a10 20 74 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65   the performance
37a20 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
37a30 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
37a40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  .** statements. 
37a50 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66   For example, if
37a60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
37a70 61 62 6c 65 20 73 74 65 70 73 20 67 72 65 61 74  able steps great
37a80 6c 79 20 65 78 63 65 65 64 73 0a 2a 2a 20 74 68  ly exceeds.** th
37a90 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 62 6c  e number of tabl
37aa0 65 20 73 65 61 72 63 68 65 73 20 6f 72 20 72 65  e searches or re
37ab0 73 75 6c 74 20 72 6f 77 73 2c 20 74 68 61 74 20  sult rows, that 
37ac0 77 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20 69 6e  would tend to in
37ad0 64 69 63 61 74 65 0a 2a 2a 20 74 68 61 74 20 74  dicate.** that t
37ae0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
37af0 65 6d 65 6e 74 20 69 73 20 75 73 69 6e 67 20 61  ement is using a
37b00 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
37b10 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20   rather than.** 
37b20 61 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a 0a 2a  an index.  .**.*
37b30 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
37b40 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72   is used to retr
37b50 69 65 76 65 20 61 6e 64 20 72 65 73 65 74 20 63  ieve and reset c
37b60 6f 75 6e 74 65 72 20 76 61 6c 75 65 73 20 66 72  ounter values fr
37b70 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61 72 65  om.** a [prepare
37b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 54  d statement].  T
37b90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37ba0 74 20 69 73 20 74 68 65 20 70 72 65 70 61 72 65  t is the prepare
37bb0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  d statement.** o
37bc0 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65  bject to be inte
37bd0 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73  rrogated.  The s
37be0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a  econd argument.*
37bf0 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  * is an integer 
37c00 63 6f 64 65 20 66 6f 72 20 61 20 73 70 65 63 69  code for a speci
37c10 66 69 63 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  fic [SQLITE_STMT
37c20 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f  STATUS_SORT | co
37c30 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 65 20  unter].** to be 
37c40 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 0a 2a  interrogated. .*
37c50 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61  * The current va
37c60 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 65  lue of the reque
37c70 73 74 65 64 20 63 6f 75 6e 74 65 72 20 69 73 20  sted counter is 
37c80 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
37c90 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 73 20  the resetFlg is 
37ca0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
37cb0 6f 75 6e 74 65 72 20 69 73 20 72 65 73 65 74 20  ounter is reset 
37cc0 74 6f 20 7a 65 72 6f 20 61 66 74 65 72 20 74 68  to zero after th
37cd0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
37ce0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
37cf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
37d00 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
37d10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 64 62   and [sqlite3_db
37d20 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53  _status()]..*/.S
37d30 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
37d40 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  AL int sqlite3_s
37d50 74 6d 74 5f 73 74 61 74 75 73 28 73 71 6c 69 74  tmt_status(sqlit
37d60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 6f 70  e3_stmt*, int op
37d70 2c 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a  ,int resetFlg);.
37d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37d90 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65   Status Paramete
37da0 72 73 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  rs for prepared 
37db0 73 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 37 35  statements {H175
37dc0 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 2a 20  70} <H17550>.** 
37dd0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
37de0 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72 6f 63  ** These preproc
37df0 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 65 66  essor macros def
37e00 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
37e10 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f 75 6e  s that name coun
37e20 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 61 73  ter.** values as
37e30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
37e40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  e [sqlite3_stmt_
37e50 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66  status()] interf
37e60 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e  ace..** The mean
37e70 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
37e80 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61 72 65  ous counters are
37e90 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
37ea0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
37eb0 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53  QLITE_STMTSTATUS
37ec0 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 3c 2f  _FULLSCAN_STEP</
37ed0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
37ee0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
37ef0 20 74 69 6d 65 73 20 74 68 61 74 20 53 51 4c 69   times that SQLi
37f00 74 65 20 68 61 73 20 73 74 65 70 70 65 64 20 66  te has stepped f
37f10 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 20 74  orward in.** a t
37f20 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f 66 20  able as part of 
37f30 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  a full table sca
37f40 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 65 72  n.  Large number
37f50 73 20 66 6f 72 20 74 68 69 73 20 63 6f 75 6e 74  s for this count
37f60 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 63 61  er.** may indica
37f70 74 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 65 73  te opportunities
37f80 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
37f90 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 68 72   improvement thr
37fa0 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 75 6c  ough .** careful
37fb0 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e   use of indices.
37fc0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
37fd0 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55  SQLITE_STMTSTATU
37fe0 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  S_SORT</dt>.** <
37ff0 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e  dd>This is the n
38000 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 6f 70  umber of sort op
38010 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 68 61  erations that ha
38020 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a 2a 20  ve occurred..** 
38030 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  A non-zero value
38040 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 65 72   in this counter
38050 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 61 6e   may indicate an
38060 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 0a   opportunity to.
38070 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 70  ** improvement p
38080 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 6f 75  erformance throu
38090 67 68 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f  gh careful use o
380a0 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a  f indices.</dd>.
380b0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
380c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
380d0 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41  MTSTATUS_FULLSCA
380e0 4e 5f 53 54 45 50 20 20 20 20 20 31 0a 23 64 65  N_STEP     1.#de
380f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d 54  fine SQLITE_STMT
38100 53 54 41 54 55 53 5f 53 4f 52 54 20 20 20 20 20  STATUS_SORT     
38110 20 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a           2../*.*
38120 2a 20 43 41 50 49 33 52 45 46 3a 20 43 75 73 74  * CAPI3REF: Cust
38130 6f 6d 20 50 61 67 65 20 43 61 63 68 65 20 4f 62  om Page Cache Ob
38140 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45  ject.** EXPERIME
38150 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
38160 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 74 79  qlite3_pcache ty
38170 70 65 20 69 73 20 6f 70 61 71 75 65 2e 20 20 49  pe is opaque.  I
38180 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  t is implemented
38190 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75 67 67   by.** the plugg
381a0 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20 54 68  able module.  Th
381b0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 68 61  e SQLite core ha
381c0 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65 20 6f  s no knowledge o
381d0 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20 6f 72  f.** its size or
381e0 20 69 6e 74 65 72 6e 61 6c 20 73 74 72 75 63 74   internal struct
381f0 75 72 65 20 61 6e 64 20 6e 65 76 65 72 20 64 65  ure and never de
38200 61 6c 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  als with the.** 
38210 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 6f  sqlite3_pcache o
38220 62 6a 65 63 74 20 65 78 63 65 70 74 20 62 79 20  bject except by 
38230 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61 73 73  holding and pass
38240 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20  ing pointers.** 
38250 74 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  to the object..*
38260 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69 74 65  *.** See [sqlite
38270 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
38280 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
38290 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
382a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
382b0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 73  sqlite3_pcache s
382c0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 3b 0a 0a  qlite3_pcache;..
382d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
382e0 41 70 70 6c 69 63 61 74 69 6f 6e 20 44 65 66 69  Application Defi
382f0 6e 65 64 20 50 61 67 65 20 43 61 63 68 65 2e 0a  ned Page Cache..
38300 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
38310 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
38320 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
38330 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
38340 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63  ], ...) interfac
38350 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73 74 65  e can.** registe
38360 72 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  r an alternative
38370 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
38380 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20 70 61  ementation by pa
38390 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a 2a 20  ssing in an .** 
383a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
383b0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
383c0 65 74 68 6f 64 73 20 73 74 72 75 63 74 75 72 65  ethods structure
383d0 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74 79 20 6f  . The majority o
383e0 66 20 74 68 65 20 0a 2a 2a 20 68 65 61 70 20 6d  f the .** heap m
383f0 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 73 71  emory used by sq
38400 6c 69 74 65 20 69 73 20 75 73 65 64 20 62 79 20  lite is used by 
38410 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20 74  the page cache t
38420 6f 20 63 61 63 68 65 20 64 61 74 61 20 72 65 61  o cache data rea
38430 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72 20 72  d .** from, or r
38440 65 61 64 79 20 74 6f 20 62 65 20 77 72 69 74 74  eady to be writt
38450 65 6e 20 74 6f 2c 20 74 68 65 20 64 61 74 61 62  en to, the datab
38460 61 73 65 20 66 69 6c 65 2e 20 42 79 20 69 6d 70  ase file. By imp
38470 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a 2a 20  lementing a .** 
38480 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
38490 65 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  e using this API
384a0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
384b0 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d 6f 72   can control mor
384c0 65 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c 79 20  e .** precisely 
384d0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  the amount of me
384e0 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20 62 79  mory consumed by
384f0 20 73 71 6c 69 74 65 2c 20 74 68 65 20 77 61 79   sqlite, the way
38500 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 73 61   in which .** sa
38510 69 64 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  id memory is all
38520 6f 63 61 74 65 64 20 61 6e 64 20 72 65 6c 65 61  ocated and relea
38530 73 65 64 2c 20 61 6e 64 20 74 68 65 20 70 6f 6c  sed, and the pol
38540 69 63 69 65 73 20 75 73 65 64 20 74 6f 20 0a 2a  icies used to .*
38550 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 78 61 63  * determine exac
38560 74 6c 79 20 77 68 69 63 68 20 70 61 72 74 73 20  tly which parts 
38570 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  of a database fi
38580 6c 65 20 61 72 65 20 63 61 63 68 65 64 20 61 6e  le are cached an
38590 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20 6c 6f  d for .** how lo
385a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ng..**.** The co
385b0 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 73 74  ntents of the st
385c0 72 75 63 74 75 72 65 20 61 72 65 20 63 6f 70 69  ructure are copi
385d0 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 72 6e 61  ed to an interna
385e0 6c 20 62 75 66 66 65 72 20 62 79 20 73 71 6c 69  l buffer by sqli
385f0 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  te.** within the
38600 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
38610 33 5f 63 6f 6e 66 69 67 5d 2e 0a 2a 2a 0a 2a 2a  3_config]..**.**
38620 20 54 68 65 20 78 49 6e 69 74 28 29 20 6d 65 74   The xInit() met
38630 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  hod is called on
38640 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c  ce for each call
38650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69   to [sqlite3_ini
38660 74 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 28 75  tialize()].** (u
38670 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e 63 65  sually only once
38680 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
38690 74 69 6d 65 20 6f 66 20 74 68 65 20 70 72 6f 63  time of the proc
386a0 65 73 73 29 2e 20 49 74 20 69 73 20 70 61 73 73  ess). It is pass
386b0 65 64 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20  ed.** a copy of 
386c0 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63  the sqlite3_pcac
386d0 68 65 5f 6d 65 74 68 6f 64 73 2e 70 41 72 67 20  he_methods.pArg 
386e0 76 61 6c 75 65 2e 20 49 74 20 63 61 6e 20 62 65  value. It can be
386f0 20 75 73 65 64 20 74 6f 20 73 65 74 0a 2a 2a 20   used to set.** 
38700 75 70 20 67 6c 6f 62 61 6c 20 73 74 72 75 63 74  up global struct
38710 75 72 65 73 20 61 6e 64 20 6d 75 74 65 78 65 73  ures and mutexes
38720 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65   required by the
38730 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
38740 68 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  he .** implement
38750 61 74 69 6f 6e 2e 20 54 68 65 20 78 53 68 75 74  ation. The xShut
38760 64 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20 69 73  down() method is
38770 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
38780 68 69 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hin .** [sqlite3
38790 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20 69 66  _shutdown()], if
387a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
387b0 20 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 41 50   invokes this AP
387c0 49 2e 20 49 74 20 63 61 6e 20 62 65 20 75 73 65  I. It can be use
387d0 64 0a 2a 2a 20 74 6f 20 63 6c 65