/ Hex Artifact Content
Login

Artifact e23556112022f04c9c49a4fc9871be16223250c3:


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 35 36 20 32 30 30 39 2f 30  n,v 1.456 2009/0
05f0: 36 2f 30 39 20 31 38 3a 30 32 3a 31 30 20 64 72  6/09 18:02:10 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 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
4190: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
41a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
41b0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41c0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41d0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
41e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
41f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4200: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
4210: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4220: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
4230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4260: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4270: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
4280: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
42a0: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
42b0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
42c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
42d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
42e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42f0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4320: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4330: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
4340: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4350: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
4360: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
4370: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
4380: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4390: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
43a0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
43b0: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
43c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
43e0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
43f0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
4400: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4410: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4420: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4430: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4460: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4470: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
4480: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4490: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
44a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
44b0: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
44c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
44d0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
44e0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
44f0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
4500: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
4510: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4520: 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ) */../*.** CAPI
4530: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4540: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4550: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4560: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4570: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4580: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4590: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
45a0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
45b0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
45c0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
45d0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
45e0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
45f0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
4600: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
4610: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
4620: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4630: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4640: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4650: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4660: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4680: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4690: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
46a0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
46b0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
46c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
46d0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
46e0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
46f0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4700: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4710: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4720: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4730: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4740: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4750: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4760: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4770: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4780: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4790: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
47a0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
47b0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
47c0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
47d0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
47e0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
47f0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
4800: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
4810: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
4820: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4830: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4840: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4850: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4860: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4870: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4880: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4890: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
48a0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
48b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48c0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
48d0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
48e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48f0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
4900: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4910: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4920: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4930: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4950: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4960: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4980: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4990: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
49a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
49b0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
49c0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
49d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
49e0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
49f0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
4a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4a10: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
4a20: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4a30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4a40: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4a50: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4a60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4a70: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4a80: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4aa0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4ab0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4ac0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
4ad0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
4ae0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
4af0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
4b00: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
4b10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4b20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4b30: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4b40: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4b50: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4b60: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4b70: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4b80: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4b90: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4bb0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4bc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4bd0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4be0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4c00: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4c10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4c20: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4c40: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4c50: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4c60: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4c70: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4c80: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4eb0: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4ec0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4ed0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4ee0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4ef0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4f00: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4f20: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4f30: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4f40: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4f50: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4f60: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4f70: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4f80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4f90: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4fa0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4fb0: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4fc0: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4fd0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4fe0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ff0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
5000: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
5010: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
5020: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
5030: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
5040: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
5050: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
5060: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
5070: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
5080: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5090: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
50a0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
50b0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
50c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
50d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
50e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
50f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
5100: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
5110: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
5120: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5130: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5140: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5150: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5160: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5170: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5180: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5190: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
51a0: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
51b0: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
51c0: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
51d0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
51e0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
51f0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
5200: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5210: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
5220: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5230: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5240: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5250: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5260: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5270: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5280: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5290: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
52a0: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
52b0: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
52c0: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
52d0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
52e0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
52f0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
5300: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5310: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
5320: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
5330: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
5340: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
5350: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
5360: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5370: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5380: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5390: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
53a0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
53b0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
53c0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
53d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
53e0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
53f0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5400: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
5410: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
5420: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
5430: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5440: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
5450: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
5460: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5470: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5480: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5490: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
54a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
54b0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
54c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
54d0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
54e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
54f0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5500: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5510: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
5520: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5530: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5540: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5550: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5560: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5570: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5580: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5590: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
55a0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
55b0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
55c0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
55d0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
55e0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
55f0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
5600: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
5610: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
5620: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5630: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5640: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5650: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5660: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5670: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5680: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5690: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
56a0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
56b0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
56c0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
56d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
56e0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
56f0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
5700: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
5710: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
5720: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5730: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5740: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5750: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5760: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5770: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5780: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5790: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
57a0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
57b0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
57c0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
57d0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
57e0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
57f0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
5800: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
5810: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
5820: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5830: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5840: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5850: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5860: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5870: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5880: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5890: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
58a0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
58b0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
58c0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
58d0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
58e0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
58f0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
5900: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
5910: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
5920: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5930: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5940: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5950: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5960: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5970: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5980: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5990: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
59a0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
59b0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
59c0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
59d0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
59e0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
59f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
5a00: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
5a10: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
5a20: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5a30: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5a40: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5a50: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5a60: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5a70: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
5a80: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
5a90: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
5aa0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
5ab0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
5ac0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
5ad0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
5ae0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
5af0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
5b00: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
5b10: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
5b20: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
5b30: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5b40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b50: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
5b60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5b70: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
5b80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b90: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
5ba0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5bb0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5bc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5bd0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5be0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5bf0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
5c00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5c10: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
5c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c30: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
5c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5c50: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
5c60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c70: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
5c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5c90: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
5ca0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
5cb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5cc0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
5cd0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
5ce0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
5cf0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5d00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5d10: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
5d20: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
5d30: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
5d40: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
5d50: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
5d60: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
5d70: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
5d80: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
5d90: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
5da0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5db0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5dc0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
5dd0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
5de0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
5df0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5e00: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5e10: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5e20: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5e30: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5e40: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5e50: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5e60: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5e70: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5e80: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5e90: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
5ea0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5eb0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5ec0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5ed0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5ee0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
5ef0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
5f00: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5f10: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
5f20: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
5f30: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
5f40: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
5f50: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
5f60: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
5f70: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5f80: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
5f90: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
5fa0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
5fb0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
5fc0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
5fd0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
5fe0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
5ff0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
6000: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6010: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
6020: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6030: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
6040: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
6050: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
6060: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
6070: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6080: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
6090: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
60a0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
60b0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
60c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
60d0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
60e0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
60f0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6100: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6110: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
6120: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6130: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
6140: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
6150: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
6160: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6170: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6180: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6190: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
61a0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
61b0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
61c0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
61d0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
61e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
61f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
6200: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
6210: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6220: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
6230: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
6240: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
6250: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
6260: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
6270: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6280: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6290: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
62a0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
62b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
62c0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
62d0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
62e0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
62f0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
6310: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
6320: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
6330: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
6340: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6350: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
6360: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
6370: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6380: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6390: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
63a0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
63b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
63c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
63d0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
63e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
63f0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
6400: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
6410: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
6420: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
6430: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
6440: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
6450: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
6460: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
6470: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6480: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6490: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
64a0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
64b0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
64c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
64d0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
64e0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
64f0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
6500: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
6510: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
6520: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6530: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6540: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6550: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6560: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6570: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6580: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6590: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
65a0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
65b0: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
65c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
65d0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
65e0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
65f0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
6600: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
6610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
6620: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6630: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6640: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6650: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6660: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6670: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6680: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6690: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
66a0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
66b0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
66c0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
66d0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
66e0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
66f0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
6700: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
6710: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
6720: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6730: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6740: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6750: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6760: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6770: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6780: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6790: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
67a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
67b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
67c0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
67d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
67e0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
67f0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
6800: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
6810: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
6820: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6830: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6840: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6850: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6860: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6870: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6880: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6890: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
68a0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
68b0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
68c0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
68d0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
68e0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
68f0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
6900: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
6910: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
6920: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6930: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6940: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6950: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6960: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6970: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6980: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6990: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
69a0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
69b0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
69c0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
69d0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
69e0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
69f0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
6a00: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
6a10: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
6a20: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6a30: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6a40: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6a50: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6a60: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6a70: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6a80: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6a90: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6aa0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6ab0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6ac0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
6ad0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
6ae0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
6af0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
6b00: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
6b10: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
6b20: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6b30: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6b40: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6b50: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6b60: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6b70: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6b80: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6b90: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6ba0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6bb0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6bc0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
6bd0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6be0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6bf0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
6c00: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
6c10: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
6c20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
6c30: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
6c40: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
6c50: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
6c60: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
6c70: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
6c80: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
6c90: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
6ca0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
6cb0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6cc0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6cd0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6ce0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6cf0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6d00: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6d10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6d20: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6d30: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6d40: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6d50: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
6d60: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
6d70: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
6d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
6d90: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
6da0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
6db0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6dc0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6dd0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6de0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6df0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6e00: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6e10: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6e20: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
6e30: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
6e40: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
6e50: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
6e60: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
6e70: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
6e80: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
6e90: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
6ea0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
6eb0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
6ec0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
6ed0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
6ee0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
6ef0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
6f00: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
6f10: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
6f20: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6f30: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6f40: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6f50: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6f60: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6f70: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
6f80: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
6f90: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
6fa0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6fb0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
6fc0: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
6fd0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
6fe0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
6ff0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
7000: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
7010: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
7020: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
7030: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
7040: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
7050: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
7060: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
7070: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
7080: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7090: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
70a0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
70b0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
70c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
70d0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
70e0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
70f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7100: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
7110: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
7120: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7130: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7140: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7150: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7170: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7180: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7190: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
71a0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
71b0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
71c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
71d0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
71e0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
71f0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
7200: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7210: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
7220: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7230: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7240: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7250: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7260: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7270: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7280: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7290: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
72a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
72b0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
72c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
72d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
72e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
72f0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
7300: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7310: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
7320: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7340: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7350: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7360: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7370: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7380: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7390: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
73a0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
73b0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
73c0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
73d0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
73e0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
73f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
7400: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
7410: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
7420: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7430: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7440: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7450: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7460: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7470: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7480: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7490: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
74a0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
74b0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
74c0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
74d0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
74e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
74f0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
7500: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
7510: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
7520: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7530: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7540: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7550: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7560: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7570: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7580: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7590: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
75a0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
75b0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
75c0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
75d0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
75e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
75f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7600: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7610: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7620: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7630: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7640: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7650: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7660: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7670: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7680: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7690: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
76a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
76b0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
76c0: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
76d0: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
76e0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
76f0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
7700: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7710: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
7720: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
7730: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
7740: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
7750: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
7760: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
7770: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
7780: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
7790: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
77a0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
77b0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
77c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
77d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
77e0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
77f0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
7800: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
7810: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
7820: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
7830: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
7840: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
7850: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
7860: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
7870: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
7880: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
7890: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
78a0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
78b0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
78c0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
78d0: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
78e0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
78f0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
7900: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
7910: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
7920: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
7930: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
7940: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
7950: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
7960: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
7970: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
7980: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
7990: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
79a0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
79b0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a  t fill it in..**
79c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
79d0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
79e0: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
79f0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
7a00: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
7a10: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
7a20: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
7a30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7a40: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
7a50: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
7a60: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
7a70: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
7a80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
7a90: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
7aa0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
7ab0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
7ac0: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
7ad0: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
7ae0: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ory..**.** SQLit
7af0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
7b00: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
7b10: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
7b20: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
7b30: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
7b40: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
7b50: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
7b60: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
7b70: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
7b80: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
7b90: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
7ba0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
7bb0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
7bc0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
7bd0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
7be0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
7bf0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
7c00: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
7c10: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
7c20: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
7c30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7c40: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
7c50: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
7c60: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
7c70: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
7c80: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
7c90: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
7ca0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
7cb0: 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43  xSleep(), and xC
7cc0: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74  urrentTime() int
7cd0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
7ce0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
7cf0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
7d00: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
7d10: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
7d20: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
7d30: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
7d40: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
7d50: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
7d60: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
7d70: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
7d80: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
7d90: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
7da0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
7db0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
7dc0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
7dd0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
7de0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
7df0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
7e00: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
7e10: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
7e20: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
7e30: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
7e40: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
7e50: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
7e60: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
7e70: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
7e80: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
7e90: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
7ea0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
7eb0: 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a  te and time..**.
7ec0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7ed0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
7ee0: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
7ef0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
7f00: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
7f10: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
7f20: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
7f30: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
7f40: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
7f50: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
7f60: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
7f70: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
7f80: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
7f90: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
7fa0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
7fb0: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
7fc0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
7fd0: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
7fe0: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
7ff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8000: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
8010: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
8020: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
8030: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
8040: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
8050: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
8060: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
8070: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
8080: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8090: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
80a0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
80b0: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
80c0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
80d0: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
80e0: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
80f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8100: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8110: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
8120: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
8130: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8140: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8150: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
8160: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8170: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
8180: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8190: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
81a0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
81b0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
81c0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
81d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
81e0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
81f0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
8200: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8210: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8220: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
8230: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
8240: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
8250: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
8260: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
8270: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
8280: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
8290: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
82a0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
82b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
82c0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
82d0: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
82e0: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
82f0: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
8300: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
8310: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
8320: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
8330: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
8340: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
8350: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
8360: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e   char *);.  /* N
8370: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
8380: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
8390: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
83a0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
83b0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
83c0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
83d0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
83e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
83f0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
8400: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
8410: 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48  thod {H11190} <H
8420: 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11140>.**.** The
8430: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8440: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
8450: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
8460: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
8470: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8480: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
8490: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e  vfs] object. {EN
84a0: 44 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  D}  They determi
84b0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
84c0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
84d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
84e0: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
84f0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8500: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
8510: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8520: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
8530: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8540: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
8550: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
8560: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
8570: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8580: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
8590: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  er the file is b
85a0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
85b0: 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69   writable..** Wi
85c0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
85d0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
85e0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
85f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8600: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
8610: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8620: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8630: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8640: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8650: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8660: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8670: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8680: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
8690: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
86a0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33  e Library {H1013
86b0: 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31  0} <S20000><S301
86c0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
86d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
86e0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
86f0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
8700: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
8710: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
8720: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
8730: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
8740: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
8750: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
8760: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
8770: 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20  lize()..**.** A 
8780: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8790: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
87a0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
87b0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
87c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
87d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
87e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
87f0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
8800: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
8810: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
8820: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
8830: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8840: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
8850: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
8860: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8870: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c  shutdown().  Onl
8880: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
8890: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
88a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
88b0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
88c0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
88d0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
88e0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
88f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8900: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8910: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
8920: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
8930: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
8940: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
8950: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
8960: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
8970: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8980: 20 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66    Only.** an eff
8990: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
89a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
89b0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
89c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
89d0: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20  All other calls 
89e0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
89f0: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
8a00: 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  ss no-ops..**.**
8a10: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
8a20: 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  ngs, sqlite3_ini
8a30: 74 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20  tialize() shall 
8a40: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
8a50: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
8a60: 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33  milarly, sqlite3
8a70: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73  _shutdown().** s
8a80: 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  hall invoke sqli
8a90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
8aa0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
8ab0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
8ac0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
8ad0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
8ae0: 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73  ess..** If for s
8af0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
8b00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8b10: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
8b20: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
8b30: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
8b40: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
8b50: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
8b60: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
8b70: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
8b80: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
8b90: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
8ba0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
8bb0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ]..**.** The sql
8bc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8bd0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
8be0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
8bf0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
8c00: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
8c10: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
8c20: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
8c30: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
8c40: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
8c50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8c60: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
8c70: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
8c80: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
8c90: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
8ca0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
8cb0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
8cc0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
8cd0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
8ce0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
8cf0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
8d00: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
8d10: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
8d20: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77  ** already.  How
8d30: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
8d40: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
8d50: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
8d60: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
8d70: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8d80: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
8d90: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
8da0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8db0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
8dc0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
8dd0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
8de0: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
8df0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
8e00: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
8e10: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
8e20: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
8e30: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
8e40: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
8e50: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
8e60: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
8e70: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
8e80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8e90: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
8ea0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
8eb0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
8ec0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
8ed0: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
8ee0: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
8ef0: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
8f00: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
8f10: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
8f20: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
8f30: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
8f40: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
8f50: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
8f60: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
8f70: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
8f80: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
8f90: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
8fa0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
8fb0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
8fc0: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
8fd0: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
8fe0: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
8ff0: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
9000: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
9010: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9020: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
9030: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
9040: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9050: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
9060: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
9070: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
9080: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
9090: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
90a0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
90b0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
90c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
90d0: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
90e0: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
90f0: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
9100: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
9110: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
9120: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
9130: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
9140: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
9150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
9160: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
9170: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
9180: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
9190: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
91a0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
91b0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
91c0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
91d0: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
91e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
91f0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
9200: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
9210: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9220: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
9230: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
9240: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
9250: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
9260: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
9270: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
9280: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
9290: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
92a0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
92b0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
92c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
92d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
92e0: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
92f0: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
9300: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
9310: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73  or unix, windows
9320: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68  , or os/2..** Wh
9330: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68  en built for oth
9340: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73  er platforms (us
9350: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
9360: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
9370: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
9380: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
9390: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
93a0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
93b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
93c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
93d0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
93e0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
93f0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
9400: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
9410: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
9420: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
9430: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
9440: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
9450: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
9460: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
9470: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
9480: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
9490: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
94a0: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
94b0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
94c0: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
94d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
94e0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
94f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
9500: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9510: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
9520: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9530: 79 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30  y {H14100} <S200
9540: 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45  00><S30200>.** E
9550: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
9560: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
9570: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
9580: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
9590: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
95a0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
95b0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
95c0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
95d0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
95e0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
95f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
9600: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
9610: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
9620: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
9630: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
9640: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
9650: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
9660: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
9670: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
9680: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
9690: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
96a0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
96b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
96c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
96d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
96e0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
96f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
9700: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
9710: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
9720: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
9730: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
9740: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
9750: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
9760: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
9770: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
9780: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
9790: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
97a0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
97b0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
97c0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
97d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
97e0: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
97f0: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
9800: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
9810: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
9820: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  r, that sqlite3_
9830: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
9840: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
9850: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
9860: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
9870: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
9880: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
9890: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
98a0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
98b0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
98c0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
98d0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
98e0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
98f0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
9900: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
9910: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
9920: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
9930: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
9940: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
9950: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
9960: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
9970: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
9980: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
9990: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
99a0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
99b0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
99c0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
99d0: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
99e0: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
99f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9a00: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9a10: 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  _OK]..** If the 
9a20: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
9a30: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
9a40: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
9a50: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
9a60: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
9a70: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
9a80: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
9a90: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
9aa0: 3a 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48  :.** [H14103] [H
9ab0: 31 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20  14106] [H14120] 
9ac0: 5b 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36  [H14123] [H14126
9ad0: 5d 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31  ] [H14129] [H141
9ae0: 33 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20  32] [H14135].** 
9af0: 5b 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31  [H14138] [H14141
9b00: 5d 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31  ] [H14144] [H141
9b10: 34 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31  47] [H14150] [H1
9b20: 34 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b  4153] [H14156] [
9b30: 48 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31  H14159].** [H141
9b40: 36 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31  62] [H14165] [H1
9b50: 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  4168].*/.SQLITE_
9b60: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
9b70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
9b80: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
9b90: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
9ba0: 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
9bb0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34  onnections  {H14
9bc0: 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  200} <S20000>.**
9bd0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
9be0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9bf0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
9c00: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
9c10: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
9c20: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
9c30: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
9c40: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
9c50: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
9c60: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
9c70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
9c80: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
9c90: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
9ca0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
9cb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
9cc0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
9cd0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
9ce0: 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  t).  The.** sqli
9cf0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
9d00: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e  interface can on
9d10: 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64  ly be used immed
9d20: 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20  iately after.** 
9d30: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
9d40: 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  nection is creat
9d50: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
9d60: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  3_open()],.** [s
9d70: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
9d80: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  , or [sqlite3_op
9d90: 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a  en_v2()].  .**.*
9da0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
9db0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
9dc0: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
9dd0: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63  ..)  is the.** c
9de0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
9df0: 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  b - an integer c
9e00: 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74  ode that indicat
9e10: 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63  es what.** aspec
9e20: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
9e30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
9e40: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
9e50: 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20  ed..** The only 
9e60: 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20  choice for this 
9e70: 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45  value is [SQLITE
9e80: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
9e90: 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72  IDE]..** New ver
9ea0: 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f  bs are likely to
9eb0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
9ec0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
9ed0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74  SQLite..** Addit
9ee0: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
9ef0: 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65  depend on the ve
9f00: 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  rb..**.** Requir
9f10: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32  ements:.** [H142
9f20: 30 33 5d 20 5b 48 31 34 32 30 36 5d 20 5b 48 31  03] [H14206] [H1
9f30: 34 32 30 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b  4209] [H14212] [
9f40: 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54  H14215].*/.SQLIT
9f50: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
9f60: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
9f70: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
9f80: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
9f90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
9fa0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
9fb0: 52 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35  Routines {H10155
9fc0: 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58  } <S20120>.** EX
9fd0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
9fe0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
9ff0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
a000: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
a010: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
a020: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
a030: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
a040: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
a050: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
a060: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
a070: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
a080: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a090: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
a0a0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
a0b0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
a0c0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
a0d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
a0e0: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
a0f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a100: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
a110: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
a120: 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20  ].  By creating 
a130: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a140: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
a150: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
a160: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a170: 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  )] during config
a180: 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61  uration, an.** a
a190: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
a1a0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
a1b0: 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  ative memory all
a1c0: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
a1d0: 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20  m.** for SQLite 
a1e0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
a1f0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
a200: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
a210: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
a220: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20  te comes with a 
a230: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
a240: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69  allocator that i
a250: 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61  s.** perfectly a
a260: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
a270: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
a280: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
a290: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
a2a0: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
a2b0: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
a2c0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
a2d0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
a2e0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
a2f0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
a300: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
a310: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
a320: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
a330: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
a340: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
a350: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
a360: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
a370: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a380: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
a390: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
a3a0: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
a3b0: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
a3c0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
a3d0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
a3e0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
a3f0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
a400: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
a410: 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65  , xFree, and xRe
a420: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75  alloc methods mu
a430: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
a440: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72  .** malloc(), fr
a450: 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f  ee(), and reallo
a460: 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  c() functions fr
a470: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
a480: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78  library..**.** x
a490: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
a4a0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
a4b0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
a4c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
a4d0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
a4e0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
a4f0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
a500: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
a510: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
a520: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
a530: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
a540: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
a550: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
a560: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
a570: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
a580: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
a590: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
a5a0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
a5b0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
a5c0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
a5d0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
a5e0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
a5f0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
a600: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
a610: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
a620: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
a630: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
a640: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a650: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
a660: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
a670: 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54  er of 2..**.** T
a680: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
a690: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
a6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a6b0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
a6c0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
a6d0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
a6e0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
a6f0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
a700: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
a710: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
a720: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
a730: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
a740: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
a750: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
a760: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
a770: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
a780: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
a790: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
a7a0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
a7b0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
a7c0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
a7d0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
a7e0: 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  tdown..*/.typede
a7f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
a800: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
a810: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
a820: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
a830: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
a840: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
a850: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
a860: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
a870: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
a880: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
a890: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
a8a0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
a8b0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
a8c0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
a8d0: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
a8e0: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
a8f0: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
a900: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
a910: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
a920: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
a930: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
a940: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
a950: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
a960: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
a970: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
a980: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
a990: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
a9a0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
a9b0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
a9c0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
a9d0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
a9e0: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
a9f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
aa00: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
aa10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
aa20: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
aa30: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
aa40: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
aa50: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
aa60: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
aa70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
aa80: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
aa90: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30   Options {H10160
aaa0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
aab0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
aac0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
aad0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
aae0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
aaf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ab00: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ab10: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
ab20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ab30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
ab40: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ab50: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
ab60: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ab70: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
ab80: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
ab90: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
aba0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
abb0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
abc0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
abd0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
abe0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
abf0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
ac00: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ac10: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
ac20: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
ac30: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
ac40: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ac50: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ac60: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
ac70: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ac80: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
ac90: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
aca0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
acb0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
acc0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
acd0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
ace0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
acf0: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
ad00: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
ad10: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
ad20: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
ad30: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73   This option dis
ad40: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
ad50: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
ad60: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
ad70: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
ad80: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
ad90: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
ada0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
adb0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
adc0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
add0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ade0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
adf0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
ae00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
ae10: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
ae20: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
ae30: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
ae40: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
ae50: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
ae60: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
ae70: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
ae80: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
ae90: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
aea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
aeb0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
aec0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
aed0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
aee0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
aef0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
af00: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
af10: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
af20: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
af30: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
af40: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
af50: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
af60: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
af70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
af80: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
af90: 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  .  See the [thre
afa0: 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64  ading mode].** d
afb0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
afc0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
afd0: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  rmation.</dd>.**
afe0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
aff0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
b000: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
b010: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
b020: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
b030: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
b040: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
b050: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
b060: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
b070: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
b080: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b090: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
b0a0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
b0b0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
b0c0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
b0d0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
b0e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b0f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
b100: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
b110: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
b120: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
b130: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
b140: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
b150: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
b160: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
b170: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
b180: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
b190: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
b1a0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
b1b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b1c0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
b1d0: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
b1e0: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
b1f0: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
b200: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
b210: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
b220: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
b230: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
b240: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
b250: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
b260: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b270: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
b280: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b290: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
b2a0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
b2b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b2c0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
b2d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
b2e0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
b2f0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
b300: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
b310: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
b320: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
b330: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
b340: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
b350: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
b360: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b370: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
b380: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
b390: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b3a0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
b3b0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
b3c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
b3d0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
b3e0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
b3f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
b400: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
b410: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
b420: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
b430: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
b440: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
b450: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
b460: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
b470: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
b480: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b490: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69  routines..** Thi
b4a0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
b4b0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
b4c0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
b4d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
b4e0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
b4f0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
b500: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
b510: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
b520: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
b530: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
b540: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
b550: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b560: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b570: 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
b580: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
b590: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
b5a0: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
b5b0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
b5c0: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
b5d0: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
b5e0: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
b5f0: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
b600: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
b610: 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20  tatistics. When 
b620: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
b630: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
b640: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
b650: 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69   .** non-operati
b660: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
b670: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
b680: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
b690: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
b6a0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
b6b0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
b6c0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
b6d0: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
b6e0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b6f0: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
b700: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a   </ul>.** </dd>.
b710: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b720: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
b730: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b740: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
b750: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
b760: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
b770: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
b780: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
b790: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
b7a0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
b7b0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
b7c0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a  e memory, the.**
b7d0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
b7e0: 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a  ratch buffer (sz
b7f0: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
b800: 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29  r of buffers (N)
b810: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
b820: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
b830: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
b840: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
b850: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
b860: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
b870: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
b880: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
b890: 65 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65  equired due inte
b8a0: 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a  rnal overhead..*
b8b0: 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61  * The first.** a
b8c0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
b8d0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
b8e0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
b8f0: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
b900: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
b910: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
b920: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
b930: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e  tch buffer at on
b940: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73  ce per thread, s
b950: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
b960: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65   set to the expe
b970: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
b980: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20  ber of threads. 
b990: 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d   The sz.** param
b9a0: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36  eter should be 6
b9b0: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20   times the size 
b9c0: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
b9d0: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
b9e0: 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75  e..** Scratch bu
b9f0: 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61  ffers are used a
ba00: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74  s part of the bt
ba10: 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72  ree balance oper
ba20: 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68  ation.  If.** Th
ba30: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72  e btree balancer
ba40: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
ba50: 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  l memory beyond 
ba60: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ba70: 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62   by.** scratch b
ba80: 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20  uffers or if no 
ba90: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73  scratch buffer s
baa0: 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65  pace is specifie
bab0: 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  d, then SQLite.*
bac0: 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  * goes to [sqlit
bad0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20  e3_malloc()] to 
bae0: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
baf0: 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e  y it needs.</dd>
bb00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bb10: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
bb20: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
bb30: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bb40: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
bb50: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
bb60: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
bb70: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
bb80: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
bb90: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
bba0: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
bbb0: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  menation.  .** T
bbc0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
bbd0: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
bbe0: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
bbf0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
bc00: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
bc10: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
bc20: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
bc30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
bc40: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
bc50: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
bc60: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
bc70: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
bc80: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d  er to the.** mem
bc90: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
bca0: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
bcb0: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
bcc0: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
bcd0: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
bce0: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
bcf0: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
bd00: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
bd10: 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74  2768.  The first
bd20: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
bd30: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
bd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
bd50: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
bd60: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
bd70: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
bd80: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
bd90: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
bda0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
bdb0: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
bdc0: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
bdd0: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
bde0: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
bdf0: 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69  ache.  If additi
be00: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
be10: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
be20: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
be30: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
be40: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
be50: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
be60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
be70: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
be80: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
be90: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69   space..** The i
bea0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
beb0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
bec0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
bed0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
bee0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
bef0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
bf00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bf10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
bf20: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AP</dt>.** <dd>T
bf30: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bf40: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
bf50: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
bf60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
bf70: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
bf80: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
bf90: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
bfa0: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
bfb0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
bfc0: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
bfd0: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
bfe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
bff0: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
c000: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c010: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
c020: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
c030: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
c040: 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  * bytes in the m
c050: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
c060: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
c070: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20  location size.  
c080: 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  If.** the first 
c090: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
c0a0: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
c0b0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
c0c0: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
c0d0: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
c0e0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
c0f0: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
c100: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
c110: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
c120: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
c130: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
c140: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
c150: 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d  C].  If the.** m
c160: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
c170: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
c180: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
c190: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
c1a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
c1b0: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
c1c0: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
c1d0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
c1e0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
c1f0: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
c200: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
c210: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
c220: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
c230: 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
c240: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
c250: 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
c260: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
c270: 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
c280: 20 6f 72 20 74 68 65 20 62 65 68 61 76 69 6f 72   or the behavior
c290: 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
c2a0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c2b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
c2c0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
c2d0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c2e0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c2f0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c300: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c310: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c320: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c330: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
c340: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
c350: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
c360: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
c370: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
c380: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
c390: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
c3a0: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
c3b0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
c3c0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c3d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
c3e0: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
c3f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
c400: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
c410: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
c420: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
c430: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
c440: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
c450: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c460: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
c470: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
c480: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
c490: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
c4a0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
c4b0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
c4c0: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
c4d0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
c4e0: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
c4f0: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
c500: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
c510: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
c520: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
c530: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
c540: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
c550: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
c560: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
c570: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
c580: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c590: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
c5a0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c5b0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
c5c0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
c5d0: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
c5e0: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63  t.** memory allc
c5f0: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
c600: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
c610: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c620: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
c630: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
c640: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
c650: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
c660: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
c670: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
c680: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
c690: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f  se connection.</
c6a0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c6b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
c6c0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
c6d0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c6e0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c6f0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c700: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
c710: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
c720: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
c730: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
c740: 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
c750: 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
c760: 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
c770: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
c780: 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
c790: 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
c7a0: 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
c7b0: 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
c7c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c7d0: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ns.</dd>.**.** <
c7e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c7f0: 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a  _GETPCACHE</dt>.
c800: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c810: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
c820: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
c830: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
c840: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
c850: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
c860: 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
c870: 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
c880: 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
c890: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
c8a0: 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
c8b0: 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
c8c0: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
c8d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
c8e0: 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
c8f0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
c900: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c910: 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
c920: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
c930: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c940: 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
c950: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
c960: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c970: 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
c980: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
c990: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
c9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c9b0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
c9c0: 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
c9d0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
c9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c9f0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
ca00: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
ca10: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
ca20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ca30: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
ca40: 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
ca50: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
ca60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ca70: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
ca80: 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
ca90: 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
caa0: 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
cab0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cac0: 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
cad0: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
cae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
caf0: 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
cb00: 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
cb10: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
cb20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cb30: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
cb40: 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
cb50: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
cb60: 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
cb70: 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
cb80: 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
cb90: 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
cba0: 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
cbb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cbc0: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
cbd0: 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
cbe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cbf0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
cc00: 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
cc10: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
cc20: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
cc30: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
cc40: 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
cc50: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
cc60: 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  thods* */../*.**
cc70: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
cc80: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
cc90: 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30   {H10170} <S2000
cca0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
ccb0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
ccc0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
ccd0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
cce0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
ccf0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
cd00: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
cd10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
cd20: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
cd30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cd40: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
cd50: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
cd60: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
cd70: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
cd80: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
cd90: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
cda0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
cdb0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
cdc0: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
cdd0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
cde0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
cdf0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
ce00: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
ce10: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
ce20: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
ce30: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
ce40: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    The [sqlite3_d
ce50: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
ce60: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
ce70: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
ce80: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
ce90: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
cea0: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
ceb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
cec0: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
ced0: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
cee0: 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
cef0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
cf00: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
cf10: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
cf20: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
cf30: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
cf40: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
cf50: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
cf60: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
cf70: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
cf80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
cf90: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
cfa0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
cfb0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
cfc0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
cfd0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
cfe0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
cff0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
d000: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
d010: 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  ide memory.  The
d020: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
d030: 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  nt may be NULL i
d040: 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
d050: 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
d060: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
d070: 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  ** buffer itself
d080: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
d090: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
d0a0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
d0b0: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
d0c0: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
d0d0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
d0e0: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
d0f0: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
d100: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
d110: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
d120: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
d130: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
d140: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
d150: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
d160: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
d170: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
d180: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c  hird arguments.<
d190: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
d1a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d1b0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
d1c0: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f  ASIDE    1001  /
d1d0: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
d1e0: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
d1f0: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
d200: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
d210: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
d220: 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  2200} <S10700>.*
d230: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
d240: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
d250: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
d260: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
d270: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
d280: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
d290: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
d2a0: 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e  QLite. The exten
d2b0: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
d2c0: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
d2d0: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
d2e0: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
d2f0: 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65  tibility conside
d300: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52  rations..**.** R
d310: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
d320: 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32  [H12201] [H12202
d330: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
d340: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
d350: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
d360: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
d370: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
d380: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
d390: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30  {H12220} <S10700
d3a0: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  >.**.** Each ent
d3b0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
d3c0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
d3d0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
d3e0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
d3f0: 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
d400: 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68  D | "rowid"]. Th
d410: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
d420: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
d430: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
d440: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
d450: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
d460: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
d470: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
d480: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
d490: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
d4a0: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
d4b0: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
d4c0: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
d4d0: 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
d4e0: 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
d4f0: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
d500: 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
d510: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
d520: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
d530: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
d540: 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
d550: 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
d560: 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
d570: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
d580: 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
d590: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d5a0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
d5b0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e   argument.  If n
d5c0: 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
d5d0: 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
d5e0: 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
d5f0: 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
d600: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
d610: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
d620: 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  * If an [INSERT]
d630: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
d640: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
d650: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
d660: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
d670: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
d680: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
d690: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
d6a0: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
d6b0: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
d6c0: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
d6d0: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
d6e0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
d6f0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
d700: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
d710: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
d720: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
d730: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e   fired..**.** An
d740: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
d750: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
d760: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
d770: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
d780: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
d790: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
d7a0: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
d7b0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
d7c0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
d7d0: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
d7e0: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
d7f0: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
d800: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
d810: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
d820: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
d830: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
d840: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
d850: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
d860: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
d870: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
d880: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
d890: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
d8a0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
d8b0: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
d8c0: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
d8d0: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
d8e0: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
d8f0: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
d900: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
d910: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
d920: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
d930: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
d940: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
d950: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
d960: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
d970: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ce..**.** For th
d980: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
d990: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
d9a0: 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
d9b0: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
d9c0: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
d9d0: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
d9e0: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
d9f0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
da00: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31  ents:.** [H12221
da10: 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a  ] [H12223].**.**
da20: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
da30: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
da40: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
da50: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
da60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
da70: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
da80: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
da90: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
daa0: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
dab0: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
dac0: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
dad0: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
dae0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
daf0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
db00: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
db10: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
db20: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
db30: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
db40: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
db50: 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
db60: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
db70: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
db80: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
db90: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
dba0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
dbb0: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
dbc0: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
dbd0: 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30  Modified {H12240
dbe0: 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
dbf0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
dc00: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
dc10: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
dc20: 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
dc30: 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
dc40: 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
dc50: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
dc60: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
dc70: 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
dc80: 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
dc90: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
dca0: 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
dcb0: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
dcc0: 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68   Only changes th
dcd0: 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
dce0: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
dcf0: 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
dd00: 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
dd10: 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
dd20: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
dd30: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
dd40: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
dd50: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
dd60: 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
dd70: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
dd80: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a  ges()] function.
dd90: 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  ** to find the t
dda0: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
ddb0: 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67  hanges including
ddc0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
ddd0: 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a  by triggers..**.
dde0: 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
ddf0: 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
de00: 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
de10: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
de20: 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
de30: 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
de40: 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
de50: 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
de60: 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65  ** A "row change
de70: 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
de80: 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
de90: 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
dea0: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
deb0: 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
dec0: 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
ded0: 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
dee0: 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
def0: 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
df00: 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
df10: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
df20: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
df30: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
df40: 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
df50: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
df60: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
df70: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
df80: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
df90: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
dfa0: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
dfb0: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
dfc0: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
dfd0: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
dfe0: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
dff0: 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
e000: 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
e010: 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
e020: 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
e030: 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
e040: 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
e050: 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
e060: 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
e070: 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
e080: 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
e090: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
e0a0: 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
e0b0: 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
e0c0: 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
e0d0: 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
e0e0: 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
e0f0: 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
e100: 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
e110: 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
e120: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  on..**.** Callin
e130: 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
e140: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
e150: 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
e160: 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
e170: 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
e180: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
e190: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e1a0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
e1b0: 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
e1c0: 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
e1d0: 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
e1e0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
e1f0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
e200: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
e210: 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
e220: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ontext..**.** Th
e230: 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
e240: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
e250: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
e260: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
e270: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
e280: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
e290: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
e2a0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
e2b0: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
e2c0: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
e2d0: 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20   level.  Within 
e2e0: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
e2f0: 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
e300: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
e310: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
e320: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
e330: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
e340: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
e350: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
e360: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
e370: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
e380: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
e390: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
e3a0: 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
e3b0: 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
e3c0: 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
e3d0: 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
e3e0: 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
e3f0: 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
e400: 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
e410: 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
e420: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
e430: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
e440: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
e450: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
e460: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75   and the.** [cou
e470: 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
e480: 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  a]..**.** Requir
e490: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32  ements:.** [H122
e4a0: 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a  41] [H12243].**.
e4b0: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
e4c0: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
e4d0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
e4e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
e4f0: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
e500: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
e510: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
e520: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
e530: 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
e540: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
e550: 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
e560: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
e570: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
e580: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e590: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
e5a0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
e5b0: 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e  H12260} <S10600>
e5c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
e5d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
e5e0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
e5f0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
e600: 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
e610: 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
e620: 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
e630: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
e640: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
e650: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65  s opened..** The
e660: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
e670: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
e680: 20 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45   all .** [CREATE
e690: 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
e6a0: 65 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48  er] contexts.  H
e6b0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
e6c0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
e6d0: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
e6e0: 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
e6f0: 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
e700: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
e710: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
e720: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
e730: 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
e740: 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
e750: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
e760: 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
e770: 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
e780: 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
e790: 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
e7a0: 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
e7b0: 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
e7c0: 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
e7d0: 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
e7e0: 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
e7f0: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e  ted..** The chan
e800: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20  ges are counted 
e810: 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73  as soon as the s
e820: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
e830: 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63  kes them is.** c
e840: 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
e850: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
e860: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  dle is passed to
e870: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
e880: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
e890: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
e8a0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
e8b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
e8c0: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
e8d0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75   and the.** [cou
e8e0: 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
e8f0: 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  a]..**.** Requir
e900: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32  ements:.** [H122
e910: 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a  61] [H12263].**.
e920: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
e930: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
e940: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
e950: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
e960: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
e970: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
e980: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
e990: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
e9a0: 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
e9b0: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
e9c0: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
e9d0: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
e9e0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e9f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ea00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
ea10: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
ea20: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32  nning Query {H12
ea30: 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a  270} <S30500>.**
ea40: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
ea50: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
ea60: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
ea70: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
ea80: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
ea90: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
eaa0: 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
eab0: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
eac0: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
ead0: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
eae0: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
eaf0: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
eb00: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
eb10: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
eb20: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
eb30: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
eb40: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
eb50: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  iately..**.** It
eb60: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
eb70: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
eb80: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
eb90: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
eba0: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
ebb0: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
ebc0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
ebd0: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
ebe0: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
ebf0: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
ec00: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
ec10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ec20: 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
ec30: 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
ec40: 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
ec50: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
ec60: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
ec70: 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
ec80: 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
ec90: 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
eca0: 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
ecb0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ecc0: 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
ecd0: 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
ece0: 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
ecf0: 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
ed00: 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
ed10: 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
ed20: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
ed30: 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   An SQL operatio
ed40: 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
ed50: 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
ed60: 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
ed70: 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  UPT]..** If the 
ed80: 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
ed90: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
eda0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
edb0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
edc0: 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
edd0: 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
ede0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
edf0: 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
ee00: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
ee10: 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
ee20: 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cally..**.** The
ee30: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
ee40: 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
ee50: 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
ee60: 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
ee70: 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
ee80: 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
ee90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
eea0: 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20   complete.  Any 
eeb0: 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
eec0: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
eed0: 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
eee0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
eef0: 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
ef00: 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
ef10: 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
ef20: 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
ef30: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
ef40: 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
ef50: 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
ef60: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
ef70: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
ef80: 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74  l.  New SQL stat
ef90: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
efa0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
efb0: 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
efc0: 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
efd0: 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
efe0: 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
eff0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
f000: 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63  errupt()..** A c
f010: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
f020: 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
f030: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
f040: 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
f050: 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
f060: 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
f070: 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
f080: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
f090: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
f0a0: 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
f0b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
f0c0: 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
f0d0: 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
f0e0: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37  ments:.** [H1227
f0f0: 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a  1] [H12272].**.*
f100: 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
f110: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
f120: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
f130: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
f140: 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
f150: 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
f160: 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
f170: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
f180: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
f190: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
f1a0: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
f1b0: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
f1c0: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
f1d0: 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32  e {H10510} <S702
f1e0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
f1f0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
f200: 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
f210: 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
f220: 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
f230: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
f240: 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
f250: 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
f260: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
f270: 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
f280: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
f290: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
f2a0: 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
f2b0: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
f2c0: 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73  r parsing.  Thes
f2d0: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
f2e0: 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
f2f0: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
f300: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
f310: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
f320: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
f330: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
f340: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
f350: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
f360: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
f370: 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
f380: 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
f390: 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
f3a0: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
f3b0: 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74   Semicolons that
f3c0: 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
f3d0: 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
f3e0: 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
f3f0: 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
f400: 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
f410: 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
f420: 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
f430: 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
f440: 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
f450: 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
f460: 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
f470: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
f480: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
f490: 6d 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73  minator.  Whites
f4a0: 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
f4b0: 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
f4c0: 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
f4d0: 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
f4e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
f4f0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
f500: 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
f510: 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
f520: 20 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20   If a.** memory 
f530: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
f540: 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
f550: 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
f560: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f570: 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
f580: 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
f590: 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
f5a0: 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
f5b0: 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
f5c0: 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
f5d0: 20 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e   If SQLite has n
f5e0: 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
f5f0: 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
f600: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
f610: 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
f620: 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
f630: 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
f640: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f650: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f660: 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
f670: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
f680: 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
f690: 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
f6a0: 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
f6b0: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
f6c0: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
f6d0: 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
f6e0: 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
f6f0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
f700: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
f710: 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
f720: 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52  omplete..**.** R
f730: 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
f740: 30 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a  0511] [H10512].*
f750: 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
f760: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
f770: 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
f780: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
f790: 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
f7a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
f7b0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
f7c0: 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
f7d0: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
f7e0: 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
f7f0: 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
f800: 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
f810: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
f820: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
f830: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
f840: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
f850: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
f860: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f870: 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
f880: 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
f890: 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
f8a0: 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
f8b0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
f8c0: 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
f8d0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
f8e0: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
f8f0: 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
f900: 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
f910: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
f920: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
f930: 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
f940: 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
f950: 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
f960: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
f970: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
f980: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
f990: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
f9a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
f9b0: 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
f9c0: 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
f9d0: 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
f9e0: 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
f9f0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
fa00: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
fa10: 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
fa20: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
fa30: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
fa40: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
fa50: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
fa60: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
fa70: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
fa80: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
fa90: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
faa0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
fab0: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
fac0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
fad0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
fae0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
faf0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
fb00: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
fb10: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
fb20: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
fb30: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
fb40: 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
fb50: 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
fb60: 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
fb70: 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
fb80: 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
fb90: 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
fba0: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
fbb0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
fbc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
fbd0: 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
fbe0: 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
fbf0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
fc00: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
fc10: 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
fc20: 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
fc30: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
fc40: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
fc50: 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
fc60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
fc70: 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
fc80: 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
fc90: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
fca0: 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
fcb0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
fcc0: 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
fcd0: 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
fce0: 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
fcf0: 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
fd00: 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
fd10: 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
fd20: 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
fd30: 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
fd40: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
fd50: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
fd60: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
fd70: 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
fd80: 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
fd90: 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
fda0: 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
fdb0: 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
fdc0: 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
fdd0: 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
fde0: 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
fdf0: 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
fe00: 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
fe10: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
fe20: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
fe30: 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
fe40: 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
fe50: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
fe60: 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
fe70: 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
fe80: 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
fe90: 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
fea0: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
feb0: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
fec0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
fed0: 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
fee0: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
fef0: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
ff00: 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
ff10: 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
ff20: 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
ff30: 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
ff40: 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
ff50: 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
ff60: 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
ff70: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
ff80: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
ff90: 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
ffa0: 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
ffb0: 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
ffc0: 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
ffd0: 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
ffe0: 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
fff0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
10000 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
10010 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
10020 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
10030 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
10040 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
10050 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
10060 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
10070 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
10080 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
10090 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
100a0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
100b0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
100c0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
100d0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
100e0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
100f0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
10100 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
10110 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
10120 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
10130 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
10140 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
10150 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
10160 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
10170 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
10180 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
10190 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
101a0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
101b0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
101c0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
101d0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
101e0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
101f0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
10200 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
10210 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
10220 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
10230 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
10240 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
10250 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
10260 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
10270 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
10280 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
10290 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
102a0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
102b0 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
102c0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
102d0 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
102e0 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
102f0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
10300 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
10310 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
10320 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
10330 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
10340 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
10350 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
10360 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
10370 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
10380 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
10390 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
103a0 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
103b0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
103c0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
103d0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
103e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
103f0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
10400 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
10410 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
10420 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
10430 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
10440 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
10450 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10460 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
10470 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
10480 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
10490 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
104a0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
104b0 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
104c0 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
104d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
104e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
104f0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
10500 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
10510 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
10520 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
10530 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
10540 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
10550 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31  .** [H12311] [H1
10560 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b  2312] [H12314] [
10570 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d  H12316] [H12318]
10580 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  .**.** A busy ha
10590 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
105a0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
105b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
105c0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
105d0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
105e0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
105f0 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
10600 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10610 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
10620 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
10630 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
10640 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
10650 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32  usy Timeout {H12
10660 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a  340} <S40410>.**
10670 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
10680 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
10690 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
106a0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
106b0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
106c0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
106d0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
106e0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
106f0 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
10700 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
10710 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
10720 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
10730 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
10740 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
10750 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
10760 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22  {H12343} After "
10770 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
10780 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
10790 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
107a0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
107b0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
107c0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
107d0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
107e0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
107f0 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
10800 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
10810 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
10820 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
10830 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
10840 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
10850 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
10860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
10870 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
10880 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
10890 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
108a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
108b0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
108c0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
108d0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
108e0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
108f0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
10900 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10910 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
10920 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
10930 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
10940 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
10950 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
10960 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
10970 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20  ts:.** [H12341] 
10980 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34  [H12343] [H12344
10990 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
109a0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
109b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
109c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
109d0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
109e0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
109f0 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33  ng Queries {H123
10a00 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a  70} <S10000>.**.
10a10 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
10a20 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
10a30 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
10a40 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
10a50 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
10a60 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
10a70 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
10a80 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
10a90 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
10aa0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
10ab0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
10ac0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
10ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
10ae0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
10af0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
10b00 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
10b10 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
10b20 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
10b30 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
10b40 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
10b50 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
10b60 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
10b70 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
10b80 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
10b90 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
10ba0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
10bb0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
10bc0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
10bd0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
10be0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
10bf0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
10c00 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
10c10 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
10c20 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
10c30 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
10c40 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
10c50 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
10c60 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
10c70 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
10c80 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
10c90 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
10ca0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
10cb0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
10cc0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
10cd0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
10ce0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
10cf0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
10d00 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
10d10 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
10d20 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
10d30 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
10d40 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
10d50 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
10d60 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
10d70 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10d80 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
10d90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
10da0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
10db0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
10dc0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
10dd0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
10de0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
10df0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
10e00 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
10e10 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
10e20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
10e30 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
10e40 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c  .** As an exampl
10e50 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
10e60 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
10e70 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
10e80 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
10e90 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
10ea0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
10eb0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
10ec0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
10ed0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
10ee0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
10ef0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
10f00 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
10f10 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
10f20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
10f30 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
10f40 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
10f50 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
10f60 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
10f70 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
10f80 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
10f90 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
10fa0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
10fb0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
10fc0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
10fd0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
10fe0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
10ff0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
11000 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
11010 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
11020 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11030 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
11040 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
11050 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
11060 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11070 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
11080 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11090 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
110a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
110b0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
110c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
110d0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
110e0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
110f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
11100 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
11110 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
11120 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
11130 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11140 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
11150 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
11160 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
11170 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11180 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
11190 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
111a0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
111b0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
111c0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
111d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
111e0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
111f0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
11200 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e  eter.  It return
11210 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
11220 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
11230 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
11240 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
11250 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
11260 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
11270 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
11280 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
11290 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73  t should.** pass
112a0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
112b0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
112c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
112d0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
112e0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
112f0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
11300 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
11310 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
11320 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
11330 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
11340 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
11350 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
11360 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
11370 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
11380 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
11390 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
113a0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
113b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
113c0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
113d0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
113e0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
113f0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
11400 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
11410 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
11420 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
11430 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
11440 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
11450 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
11460 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11470 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
11480 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
11490 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
114a0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
114b0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
114c0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
114d0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
114e0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
114f0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
11500 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
11510 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
11520 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
11530 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
11540 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
11550 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
11560 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
11570 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
11580 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
11590 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
115a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
115b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
115c0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
115d0 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48  371] [H12373] [H
115e0 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20  12374] [H12376] 
115f0 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32  [H12379] [H12382
11600 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
11610 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
11620 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
11630 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
11640 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
11650 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
11660 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
11670 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
11680 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
11690 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
116a0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
116b0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
116c0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
116d0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
116e0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
116f0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
11700 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
11710 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
11720 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
11730 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
11740 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
11750 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
11760 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
11770 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
11780 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
11790 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
117a0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
117b0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
117c0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30  Functions {H1740
117d0 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30  0} <S70000><S200
117e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
117f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
11800 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
11810 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
11820 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
11830 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
11840 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
11850 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11860 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
11870 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
11880 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
11890 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
118a0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
118b0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
118c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
118d0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
118e0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
118f0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
11900 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
11910 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
11920 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
11930 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
11940 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
11950 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
11960 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
11970 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
11980 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
11990 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
119a0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
119b0 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
119c0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
119d0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
119e0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
119f0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
11a00 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
11a10 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
11a20 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
11a30 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
11a40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
11a50 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
11a60 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
11a70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
11a80 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
11a90 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
11aa0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
11ab0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
11ac0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
11ad0 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
11ae0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
11af0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
11b00 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
11b10 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
11b20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
11b30 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
11b40 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
11b50 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
11b60 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
11b70 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
11b80 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
11b90 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
11ba0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
11bb0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
11bc0 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
11bd0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
11be0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
11bf0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
11c00 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
11c10 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
11c20 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
11c30 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
11c40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
11c50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
11c60 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
11c70 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
11c80 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
11c90 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
11ca0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
11cb0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
11cc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
11cd0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
11ce0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
11cf0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
11d00 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
11d10 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
11d20 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
11d30 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
11d40 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
11d50 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
11d60 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
11d70 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
11d80 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
11d90 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
11da0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
11db0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
11dc0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
11dd0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
11de0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
11df0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
11e00 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
11e10 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
11e20 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
11e30 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
11e40 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
11e50 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
11e60 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
11e70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
11e80 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
11e90 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
11ea0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
11eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
11ec0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
11ed0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
11ee0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
11ef0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
11f00 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
11f10 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
11f20 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
11f30 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
11f40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
11f50 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
11f60 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
11f70 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
11f80 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
11f90 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
11fa0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
11fb0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
11fc0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
11fd0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
11fe0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
11ff0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
12000 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
12010 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
12020 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
12030 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
12040 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12050 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
12060 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
12070 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
12080 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12090 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
120a0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
120b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
120c0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
120d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
120e0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
120f0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
12100 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
12110 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
12120 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
12130 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
12140 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
12150 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
12160 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
12170 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12180 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
12190 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
121a0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
121b0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
121c0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
121d0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
121e0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
121f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
12200 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
12210 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
12220 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
12230 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
12240 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
12250 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
12260 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
12270 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
12280 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
12290 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
122a0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
122b0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
122c0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
122d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
122e0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
122f0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
12300 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
12310 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
12320 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12330 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
12340 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
12350 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
12360 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
12370 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
12380 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
12390 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
123a0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
123b0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
123c0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
123d0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
123e0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
123f0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
12400 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
12410 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
12420 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
12430 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
12440 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
12450 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
12460 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
12470 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
12480 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
12490 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
124a0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
124b0 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
124c0 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
124d0 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
124e0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
124f0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
12500 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12510 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
12520 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
12530 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12540 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
12550 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
12560 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
12570 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
12580 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
12590 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
125a0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
125b0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
125c0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
125d0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
125e0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
125f0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
12600 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
12610 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
12620 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
12630 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
12640 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
12650 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
12660 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
12670 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
12680 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
12690 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
126a0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
126b0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
126c0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
126d0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
126e0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
126f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
12700 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20  ts:.** [H17403] 
12710 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37  [H17406] [H17407
12720 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ].*/.char *sqlit
12730 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
12740 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
12750 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
12760 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
12770 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
12780 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
12790 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
127a0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
127b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
127c0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
127d0 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37  n Subsystem {H17
127e0 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  300} <S20000>.**
127f0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
12800 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20  ore  uses these 
12810 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
12820 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
12830 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
12840 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12850 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
12860 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
12870 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
12880 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
12890 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
128a0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
128b0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
128c0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
128d0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
128e0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
128f0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
12900 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12910 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
12920 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
12930 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
12940 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
12950 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
12960 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
12970 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
12980 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ter..** If sqlit
12990 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
129a0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
129b0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
129c0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
129d0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
129e0 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61  nter.  If the pa
129f0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
12a00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12a10 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
12a20 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
12a30 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
12a40 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
12a50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  nter..**.** Call
12a60 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
12a70 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
12a80 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
12a90 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
12aa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
12ab0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12ac0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
12ad0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
12ae0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
12af0 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  used.  The sqlit
12b00 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
12b10 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
12b20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
12b30 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
12b40 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
12b50 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
12b60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
12b70 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
12b80 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
12b90 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
12ba0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
12bb0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
12bc0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
12bd0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
12be0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
12bf0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
12c00 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
12c10 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
12c20 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
12c30 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
12c40 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
12c50 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
12c60 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
12c70 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
12c80 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
12c90 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
12ca0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
12cb0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
12cc0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
12cd0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
12ce0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
12cf0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12d00 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
12d10 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
12d20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
12d30 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
12d40 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
12d50 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
12d60 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
12d70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
12d80 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
12d90 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
12da0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
12db0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
12dc0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
12dd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
12de0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
12df0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
12e00 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
12e10 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
12e20 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
12e30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
12e40 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
12e50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12e60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
12e70 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
12e80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12e90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
12ea0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
12eb0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
12ec0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
12ed0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
12ee0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
12ef0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
12f00 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
12f10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12f20 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
12f30 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
12f40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
12f50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12f60 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12f70 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
12f80 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
12f90 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
12fa0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
12fb0 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
12fc0 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
12fd0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
12fe0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
12ff0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
13000 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
13010 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
13020 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
13030 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
13040 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
13050 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
13060 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
13070 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
13080 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
13090 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
130a0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
130b0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
130c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
130d0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
130e0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
130f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
13100 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
13110 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
13120 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
13130 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
13140 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
13150 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
13160 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
13170 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13190 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
131a0 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
131b0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
131c0 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
131d0 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
131e0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
131f0 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  H17382} However,
13200 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
13210 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
13220 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
13230 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
13240 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
13250 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
13260 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
13270 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
13280 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
13290 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
132a0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
132b0 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
132c0 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
132d0 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
132e0 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
132f0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13300 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
13310 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
13320 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
13330 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
13340 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
13350 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
13360 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
13370 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
13380 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
13390 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
133a0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
133b0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
133c0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
133d0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
133e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
133f0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
13400 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
13410 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
13420 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
13430 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
13440 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
13450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
13460 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
13470 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
13480 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
13490 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
134a0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
134b0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
134c0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
134d0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
134e0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
134f0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
13500 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
13510 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
13520 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
13530 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
13540 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
13550 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
13560 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
13570 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
13580 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
13590 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
135a0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
135b0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
135c0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
135d0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
135e0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
135f0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
13600 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37  ** [H17303] [H17
13610 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48  304] [H17305] [H
13620 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20  17306] [H17310] 
13630 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35  [H17312] [H17315
13640 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48  ] [H17318].** [H
13650 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20  17321] [H17322] 
13660 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54  [H17323].**.** T
13670 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
13680 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
13690 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
136a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
136b0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
136c0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
136d0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
136e0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
136f0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
13700 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13710 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
13720 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
13730 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
13740 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
13750 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
13760 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
13770 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
13780 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
13790 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
137a0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
137b0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
137c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
137d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
137e0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
137f0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
13800 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
13810 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
13820 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
13830 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
13840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13850 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
13860 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
13870 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
13880 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
13890 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
138a0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
138b0 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
138c0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
138d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
138e0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
138f0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
13900 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13910 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
13920 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
13930 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
13940 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
13950 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  em..**.** Requir
13960 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33  ements:.** [H173
13970 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31  71] [H17373] [H1
13980 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a  7374] [H17375].*
13990 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
139a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
139b0 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
139c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
139d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
139e0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
139f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13a00 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
13a10 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
13a20 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
13a30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
13a40 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
13a50 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
13a60 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
13a70 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
13a80 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
13a90 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
13aa0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
13ab0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
13ac0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
13ad0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
13ae0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
13af0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
13b00 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
13b10 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
13b20 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
13b30 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
13b40 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
13b50 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
13b60 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
13b70 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
13b80 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
13b90 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
13ba0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
13bb0 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
13bc0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
13bd0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
13be0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
13bf0 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
13c00 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
13c10 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
13c20 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
13c30 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
13c40 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
13c50 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
13c60 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
13c70 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
13c80 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
13c90 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
13ca0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
13cb0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
13cc0 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
13cd0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
13ce0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
13cf0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
13d00 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
13d10 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
13d20 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
13d30 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
13d40 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
13d50 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
13d60 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39  ments:.** [H1739
13d70 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  2].*/.void sqlit
13d80 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
13d90 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
13da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13db0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
13dc0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
13dd0 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53  acks {H12500} <S
13de0 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70100>.**.** Thi
13df0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
13e00 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
13e10 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
13e20 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
13e30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13e40 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
13e50 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
13e60 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
13e70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13e80 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
13e90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
13ea0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
13eb0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
13ec0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
13ed0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
13ee0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
13ef0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
13f00 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
13f10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13f20 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
13f30 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
13f40 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
13f50 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
13f60 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
13f70 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
13f80 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
13f90 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
13fa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13fb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
13fc0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
13fd0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
13fe0 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
13ff0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
14000 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
14010 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
14020 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
14030 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
14040 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
14050 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
14060 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
14070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
14080 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
14090 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
140a0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
140b0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
140c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
140d0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
140e0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
140f0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
14100 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
14110 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
14120 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
14130 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
14140 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
14150 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
14160 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
14170 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
14180 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
14190 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
141a0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
141b0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
141c0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
141d0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
141e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
141f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
14200 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
14210 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
14220 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57  uested is ok.  W
14230 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
14240 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
14250 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
14260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14270 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
14280 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
14290 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
142a0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
142b0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
142c0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
142d0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
142e0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
142f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
14300 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
14320 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
14330 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
14340 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14350 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
14360 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
14370 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
14380 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
14390 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
143a0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
143b0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
143c0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
143d0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
143e0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
143f0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
14400 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
14410 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
14420 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
14430 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
14440 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
14450 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
14460 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
14470 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
14480 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
14490 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  orized..**.** If
144a0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
144b0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
144c0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
144d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
144e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
144f0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
14500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
14510 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
14520 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
14530 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
14540 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
14550 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
14560 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
14570 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
14580 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
14590 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
145a0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
145b0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
145c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
145d0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
145e0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
145f0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
14600 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
14610 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74  e..** If the act
14620 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
14630 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
14640 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
14650 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
14660 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
14670 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
14680 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
14690 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
146a0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
146b0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
146c0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
146d0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
146e0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
146f0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
14700 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
14710 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
14720 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
14730 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
14740 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
14750 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
14760 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
14770 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
14780 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
14790 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
147a0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
147b0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
147c0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
147d0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
147e0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
147f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
14800 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
14810 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
14820 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
14830 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
14840 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
14850 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
14860 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
14870 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
14880 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
14890 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
148a0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
148b0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
148c0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
148d0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
148e0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
148f0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
14900 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
14910 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
14920 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
14930 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
14940 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
14950 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
14960 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
14970 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
14980 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
14990 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
149a0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
149b0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
149c0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
149d0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
149e0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
149f0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
14a00 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
14a10 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
14a20 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
14a30 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
14a40 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
14a50 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
14a60 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
14a70 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
14a80 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
14a90 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
14aa0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
14ab0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
14ac0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
14ad0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
14ae0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
14af0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
14b00 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
14b10 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
14b20 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
14b30 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
14b40 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
14b50 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
14b60 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
14b70 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
14b80 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
14b90 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
14ba0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
14bb0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
14bc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
14bd0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
14be0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14bf0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
14c00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14c10 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
14c20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
14c30 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
14c40 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
14c50 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
14c60 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
14c70 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
14c80 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  raph..**.** When
14c90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14ca0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
14cb0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
14cc0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
14cd0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
14ce0 65 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72  e reprepared dur
14cf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
14d00 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
14d10 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
14d20 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
14d30 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
14d40 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
14d50 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
14d60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
14d70 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
14d80 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
14d90 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
14da0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
14db0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
14dc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
14dd0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
14de0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
14df0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
14e00 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
14e10 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
14e20 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
14e30 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
14e40 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
14e50 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
14e60 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
14e70 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
14e80 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
14e90 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
14ea0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
14eb0 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
14ec0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
14ed0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
14ee0 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ange..**.** Requ
14ef0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
14f00 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b  2501] [H12502] [
14f10 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d  H12503] [H12504]
14f20 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30   [H12505] [H1250
14f30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32  6] [H12507] [H12
14f40 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d  510].** [H12511]
14f50 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32   [H12512] [H1252
14f60 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32  0] [H12521] [H12
14f70 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  522].*/.int sqli
14f80 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
14f90 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
14fa0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
14fb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14fc0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
14fd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
14fe0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
14ff0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
15000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15010 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
15020 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
15030 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
15040 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
15050 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
15060 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15070 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
15080 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
15090 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
150a0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
150b0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
150c0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
150d0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
150e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
150f0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
15100 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
15110 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
15120 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
15130 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
15140 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
15150 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
15160 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15170 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
15180 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
15190 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
151a0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
151b0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
151c0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
151d0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
151e0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
151f0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
15200 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
15210 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
15220 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
15230 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
15240 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
15250 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
15260 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
15270 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15280 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
15290 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
152a0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
152b0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
152c0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
152d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
152e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
152f0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
15300 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
15310 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
15320 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
15330 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
15340 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
15350 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
15360 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15370 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
15380 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
15390 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
153a0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
153b0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
153c0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
153d0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
153e0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
153f0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
15400 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
15410 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
15420 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
15430 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
15440 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
15450 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
15460 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
15470 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
15480 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
15490 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
154a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
154b0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
154c0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
154d0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
154e0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
154f0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
15500 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15510 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15520 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
15530 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
15540 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
15550 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
15560 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
15570 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
15580 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
15590 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
155a0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
155b0 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
155c0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
155d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
155e0 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35   [H12551] [H1255
155f0 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32  2] [H12553] [H12
15600 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  554].*/./*******
15610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15630 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
15640 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
15650 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
15660 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
15670 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
15680 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
15690 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
156a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
156b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
156c0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
156d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
156e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
156f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15700 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
15710 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
15720 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
15730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15750 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
15760 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
15770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15780 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157a0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
157b0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
157c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
157d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
157e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
157f0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
15800 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
15810 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
15820 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15840 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
15850 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
15860 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
15870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
15880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15890 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
158a0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
158b0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
158c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
158d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
158e0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
158f0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
15900 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
15910 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
15930 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
15940 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
15950 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
15960 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15970 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
15980 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
15990 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
159a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
159b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
159c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
159d0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
159e0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
159f0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
15a00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15a10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15a20 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
15a30 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
15a40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15a50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15a60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
15a70 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
15a80 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
15a90 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
15aa0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15ab0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
15ac0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
15ad0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
15ae0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15af0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15b00 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
15b10 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
15b20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
15b30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15b40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15b50 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
15b60 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
15b70 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
15b80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
15b90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15ba0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
15bb0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
15bc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
15bd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15be0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15bf0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
15c00 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
15c10 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
15c20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
15c30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15c40 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
15c50 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
15c60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15c70 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
15c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15c90 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
15ca0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
15cb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
15cc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15cd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15ce0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
15cf0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
15d00 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
15d10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15d20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15d30 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
15d40 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
15d50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
15d60 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
15d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
15d80 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
15d90 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
15da0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
15db0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
15dd0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
15de0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
15df0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
15e00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
15e20 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
15e30 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
15e40 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
15e50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
15e70 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
15e80 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
15e90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
15ea0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15eb0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
15ec0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
15ed0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
15ee0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15ef0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15f00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
15f10 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
15f20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
15f30 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
15f40 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
15f50 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
15f60 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
15f70 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15f80 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
15f90 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15fa0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
15fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
15fc0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
15fd0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
15fe0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
15ff0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
16000 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
16010 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
16020 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
16030 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
16040 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
16050 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
16060 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
16070 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
16080 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
16090 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
160a0 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c  tions {H12280} <
160b0 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60400>.** EXPER
160c0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
160d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
160e0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
160f0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
16100 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
16110 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
16120 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
16130 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
16140 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
16150 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
16160 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
16170 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
16180 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
16190 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
161a0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
161b0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
161c0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
161d0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
161e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
161f0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
16200 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
16210 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
16220 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
16230 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
16240 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
16250 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
16260 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
16270 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
16280 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
16290 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
162a0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
162b0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
162c0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
162d0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
162e0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  trigger..**.** T
162f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
16300 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
16310 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
16320 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
16330 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
16340 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
16350 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
16360 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
16370 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
16380 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
16390 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
163a0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
163b0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
163c0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
163d0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
163e0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
163f0 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b  s:.** [H12281] [
16400 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d  H12282] [H12283]
16410 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38   [H12284] [H1228
16420 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32  5] [H12287] [H12
16430 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a  288] [H12289].**
16440 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c   [H12290].*/.SQL
16450 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
16460 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
16470 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
16480 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
16490 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
164a0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
164b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
164c0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
164d0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
164e0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
164f0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
16500 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
16510 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
16520 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
16530 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
16540 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53  acks {H12910} <S
16550 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60400>.**.** Thi
16560 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
16570 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
16580 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a  function - the.*
16590 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  * progress callb
165a0 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e  ack - that is in
165b0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
165c0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a  ly during long.*
165d0 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  * running calls 
165e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
165f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
16600 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ep()] and.** [sq
16610 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16620 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  )].  An example 
16630 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
16640 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
16650 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
16660 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
16670 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
16680 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
16690 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
166a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
166b0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
166c0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
166d0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
166e0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
166f0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
16700 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
16710 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
16720 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
16730 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
16740 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
16750 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
16760 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
16770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16780 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
16790 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
167a0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
167b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
167c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
167d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
167e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
167f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16800 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
16810 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
16820 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
16830 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  raph..**.** Requ
16840 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
16850 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b  2911] [H12912] [
16860 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d  H12913] [H12914]
16870 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31   [H12915] [H1291
16880 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32  6] [H12917] [H12
16890 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  918].**.*/.void 
168a0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
168b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
168c0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
168d0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
168e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
168f0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
16900 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
16910 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32  n {H12700} <S402
16920 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
16930 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
16940 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
16950 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
16960 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
16970 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
16980 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e  ument. The filen
16990 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
169a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
169b0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
169c0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
169d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
169e0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
169f0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
16a00 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
16a10 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
16a20 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   A [database con
16a30 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
16a40 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
16a50 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
16a60 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
16a70 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
16a80 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
16a90 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
16aa0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
16ab0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
16ac0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
16ad0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
16ae0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
16af0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
16b00 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
16b10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
16b20 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
16b30 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62  ct. If the datab
16b40 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
16b50 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
16b60 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
16b70 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
16b80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
16b90 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
16ba0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
16bb0 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  rned.  The.** [s
16bc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
16bd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
16be0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
16bf0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
16c00 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
16c10 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
16c20 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
16c30 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
16c40 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
16c50 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
16c60 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
16c70 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
16c80 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
16c90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
16ca0 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
16cb0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
16cc0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
16cd0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
16ce0 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
16cf0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
16d00 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
16d10 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
16d20 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
16d30 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
16d40 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
16d50 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
16d60 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
16d70 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
16d80 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
16d90 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
16da0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
16db0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
16dc0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
16dd0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
16de0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
16df0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
16e00 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
16e10 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
16e20 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
16e30 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
16e40 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
16e50 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
16e60 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c  nection.  The fl
16e70 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61  ags parameter ca
16e80 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
16e90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
16ea0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
16eb0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
16ec0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
16ed0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
16ee0 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
16ef0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
16f00 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  lags:.**.** <dl>
16f10 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
16f20 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
16f30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
16f40 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
16f50 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
16f60 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
16f70 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
16f80 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
16f90 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
16fa0 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  urned.</dd>.**.*
16fb0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
16fc0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
16fd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
16fe0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16ff0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
17000 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
17010 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
17020 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
17030 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
17040 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
17050 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
17060 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
17070 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
17080 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
17090 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
170a0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
170b0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
170c0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
170d0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
170e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
170f0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
17100 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
17110 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
17120 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
17130 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74  nd is creates it
17140 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
17150 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
17160 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
17170 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
17180 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
17190 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
171a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
171b0 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  n16().</dd>.** <
171c0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
171d0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
171e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
171f0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
17200 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
17210 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
17220 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
17230 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
17240 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
17250 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
17260 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
17270 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  TEX] or [SQLITE_
17280 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
17290 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
172a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
172b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
172c0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
172d0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
172e0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
172f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17300 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
17310 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
17320 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
17330 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
17340 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
17350 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
17360 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
17370 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
17380 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68  art-time.  If th
17390 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
173a0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
173b0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
173c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
173d0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
173e0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
173f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17400 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
17410 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
17420 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
17430 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
17440 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
17450 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
17460 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
17470 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
17480 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
17490 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
174a0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
174b0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
174c0 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
174d0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
174e0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
174f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
17500 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
17510 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
17520 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
17530 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
17540 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
17550 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
17560 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
17570 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
17580 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
17590 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
175a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
175b0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
175c0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
175d0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
175e0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
175f0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
17600 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
17610 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
17620 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
17630 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  guity..**.** If 
17640 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
17650 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
17660 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
17670 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
17680 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
17690 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
176a0 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
176b0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
176c0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
176d0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
176e0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
176f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
17700 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
17710 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17720 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
17730 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
17740 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
17750 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
17760 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
17770 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
17780 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
17790 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
177a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
177b0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
177c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
177d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
177e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
177f0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
17800 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
17810 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
17820 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
17830 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
17840 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
17850 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
17860 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
17870 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
17880 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
17890 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
178a0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
178b0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
178c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
178d0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
178e0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
178f0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
17900 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
17910 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
17920 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
17930 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
17940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
17950 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
17960 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ()..**.** Requir
17970 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37  ements:.** [H127
17980 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31  01] [H12702] [H1
17990 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b  2703] [H12704] [
179a0 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d  H12706] [H12707]
179b0 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31   [H12709] [H1271
179c0 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b  1].** [H12712] [
179d0 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d  H12713] [H12714]
179e0 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31   [H12717] [H1271
179f0 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32  9] [H12721] [H12
17a00 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  723].*/.int sqli
17a10 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
17a20 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
17a30 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
17a40 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
17a50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
17a60 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
17a70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
17a80 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
17a90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
17aa0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
17ab0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
17ac0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
17ad0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
17ae0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
17af0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
17b00 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
17b10 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
17b20 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
17b30 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
17b40 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
17b50 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
17b60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
17b70 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
17b80 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
17b90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
17ba0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
17bb0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
17bc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
17bd0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
17be0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
17bf0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
17c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
17c10 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
17c20 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20  ssages {H12800} 
17c30 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60200>.**.** T
17c40 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
17c50 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
17c60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
17c70 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
17c80 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
17c90 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
17ca0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
17cb0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
17cc0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
17cd0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
17ce0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17cf0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
17d00 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
17d10 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
17d20 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
17d30 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
17d40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
17d50 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
17d60 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
17d70 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69  fined.  The sqli
17d80 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
17d90 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
17da0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
17db0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
17dc0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
17dd0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
17de0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
17df0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
17e00 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
17e10 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
17e20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
17e30 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
17e40 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
17e50 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
17e60 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
17e70 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
17e80 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
17e90 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
17ea0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
17eb0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
17ec0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
17ed0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
17ee0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
17ef0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
17f00 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
17f10 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
17f20 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
17f30 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
17f40 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
17f50 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
17f60 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
17f70 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
17f80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
17f90 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
17fa0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
17fb0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ons..**.** When 
17fc0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
17fd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
17fe0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
17ff0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
18000 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
18010 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
18020 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18030 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
18040 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
18050 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
18060 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
18070 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
18080 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
18090 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
180a0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
180b0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
180c0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
180d0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
180e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
180f0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
18100 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
18110 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
18120 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
18130 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
18140 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
18150 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
18160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
18170 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
18180 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
18190 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
181a0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
181b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
181c0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
181d0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
181e0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
181f0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
18200 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
18210 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
18220 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
18230 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
18240 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
18250 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
18260 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
18270 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
18280 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
18290 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
182a0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
182b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
182c0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
182d0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   not be set..**.
182e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
182f0 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31  .** [H12801] [H1
18300 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b  2802] [H12803] [
18310 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d  H12807] [H12808]
18320 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74   [H12809].*/.int
18330 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
18340 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
18350 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
18360 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
18370 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
18380 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
18390 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
183a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
183b0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
183c0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
183d0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
183e0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48  tement Object {H
183f0 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a  13000} <H13010>.
18400 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
18410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
18420 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
18430 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
18440 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
18450 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
18460 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
18470 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
18480 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
18490 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
184a0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
184b0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
184c0 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
184d0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
184e0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
184f0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
18500 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
18510 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
18520 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
18530 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
18540 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
18550 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
18560 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18570 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
18580 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
18590 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
185a0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
185b0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
185c0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
185d0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
185e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
185f0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
18600 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
18610 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
18620 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
18630 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
18640 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
18650 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
18660 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
18670 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
18680 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
18690 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
186a0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
186b0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
186c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
186d0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
186e0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
186f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
18700 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
18710 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
18720 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
18730 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
18740 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
18750 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
18760 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
18770 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
18780 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20  Limits {H12760} 
18790 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20600>.**.** T
187a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
187b0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
187c0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
187d0 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
187e0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
187f0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
18800 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
18810 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
18820 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
18830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
18840 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
18850 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
18860 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
18870 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18880 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
18890 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
188a0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
188b0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
188c0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
188d0 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
188e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
188f0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
18900 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
18910 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f  ct.  The functio
18920 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c  n returns the ol
18930 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49  d limit..**.** I
18940 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
18950 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
18960 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
18970 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
18980 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63   For the limit c
18990 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54  ategory of SQLIT
189a0 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72  E_LIMIT_XYZ ther
189b0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
189c0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
189d0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79  bound].** set by
189e0 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
189f0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
18a00 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b  acro named .** [
18a10 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
18a20 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68  MAX_XYZ]..** (Th
18a30 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
18a40 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
18a50 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a  ed to "_MAX_".).
18a60 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69  ** Attempts to i
18a70 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
18a80 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
18a90 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
18aa0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
18ab0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
18ac0 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a   upper limit..**
18ad0 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d  .** Run time lim
18ae0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
18af0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
18b00 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
18b10 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
18b20 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
18b30 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
18b40 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
18b50 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
18b60 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
18b70 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
18b80 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
18b90 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
18ba0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
18bb0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
18bc0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
18bd0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
18be0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
18bf0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
18c00 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
18c10 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
18c20 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
18c30 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
18c40 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
18c50 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
18c60 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
18c70 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
18c80 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
18c90 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
18ca0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
18cb0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
18cc0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
18cd0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
18ce0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
18cf0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
18d00 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
18d10 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
18d20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
18d30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18d40 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
18d50 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
18d60 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
18d70 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
18d80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
18d90 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
18da0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
18db0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
18dc0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
18dd0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
18de0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
18df0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
18e00 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
18e10 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
18e20 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
18e30 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
18e40 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b  s:.** [H12762] [
18e50 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d  H12766] [H12769]
18e60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18e70 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
18e80 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
18e90 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
18ea0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
18eb0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
18ec0 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30  {H12790} <H12760
18ed0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
18ee0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
18ef0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
18f00 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
18f10 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
18f20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
18f30 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
18f40 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
18f50 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
18f60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
18f70 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
18f80 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
18f90 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
18fa0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
18fb0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
18fc0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
18fd0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
18fe0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
18ff0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
19000 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
19010 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
19020 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
19030 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
19040 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
19050 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
19060 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
19070 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
19080 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
19090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
190a0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
190b0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
190c0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
190d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
190e0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
190f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
19100 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
19110 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
19120 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
19130 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
19140 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
19150 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
19160 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
19170 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
19180 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
19190 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
191a0 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  se.</dd>.**.** <
191b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
191c0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
191d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
191e0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
191f0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
19200 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
19210 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19220 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
19230 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
19240 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
19250 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
19260 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
19270 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
19280 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19290 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
192a0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
192b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
192c0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
192d0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
192e0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
192f0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
19300 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
19310 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
19320 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
19330 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
19340 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
19350 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
19360 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
19370 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
19380 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19390 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
193a0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
193b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
193c0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
193d0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
193e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
193f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
19400 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
19410 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
19420 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
19430 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
19440 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
19450 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
19460 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
19470 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
19480 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
19490 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
194a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
194b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  mum number of va
194c0 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51  riables in an SQ
194d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
194e0 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64   can.** be bound
194f0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
19500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19510 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
19520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19530 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
19540 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
19550 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
19560 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
19570 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
19580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19590 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
195a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
195b0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
195c0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
195d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
195e0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
195f0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
19600 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
19610 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
19620 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
19630 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
19640 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
19650 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
19660 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
19670 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
19680 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
19690 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
196a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
196b0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
196c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
196d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
196e0 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a             9../*
196f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
19700 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
19710 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30  tatement {H13010
19720 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45  } <S10000>.** KE
19730 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
19740 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
19750 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
19760 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
19770 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
19780 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
19790 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
197a0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
197b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
197c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
197d0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
197e0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
197f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
19800 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
19810 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
19820 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
19830 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
19840 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19850 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
19860 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
19870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19880 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
19890 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
198a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
198b0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
198c0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
198d0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
198e0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
198f0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
19900 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
19910 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
19920 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
19930 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
19940 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
19950 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
19960 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
19970 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
19980 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
19990 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
199a0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
199b0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
199c0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
199d0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
199e0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
199f0 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
19a00 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
19a10 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
19a20 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
19a30 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
19a40 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
19a50 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
19a60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
19a70 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
19a80 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
19a90 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
19aa0 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
19ab0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
19ac0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
19ad0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
19ae0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
19af0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
19b00 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
19b10 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
19b20 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
19b30 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
19b40 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
19b50 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
19b60 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
19b70 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
19b80 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
19b90 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
19ba0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
19bb0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
19bc0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
19bd0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
19be0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
19bf0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
19c00 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
19c10 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
19c20 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
19c30 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
19c40 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
19c50 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
19c60 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
19c70 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
19c80 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
19c90 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
19ca0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
19cb0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
19cc0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
19cd0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
19ce0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
19cf0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
19d00 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
19d10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
19d20 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
19d30 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
19d40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
19d50 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
19d60 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
19d70 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
19d80 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
19d90 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
19da0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
19db0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
19dc0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
19dd0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
19de0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
19df0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
19e00 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
19e10 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
19e20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
19e30 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
19e40 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
19e50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
19e60 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
19e70 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
19e80 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
19e90 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
19ea0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
19eb0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
19ec0 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
19ed0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
19ee0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
19ef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19f00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19f10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
19f20 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
19f30 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
19f40 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
19f50 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
19f60 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
19f70 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
19f80 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
19f90 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19fa0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
19fb0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
19fc0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
19fd0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
19fe0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
19ff0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1a000 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1a010 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1a020 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1a030 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1a040 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1a050 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1a060 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1a070 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1a080 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
1a090 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
1a0a0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1a0b0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
1a0c0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1a0d0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1a0e0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1a0f0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1a100 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1a110 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1a120 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1a130 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1a140 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1a150 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1a160 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1a170 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
1a180 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1a190 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1a1a0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1a1b0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1a1c0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1a1d0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1a1e0 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1a1f0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1a200 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1a210 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1a220 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1a230 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1a240 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1a250 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1a260 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1a270 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1a280 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1a290 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1a2a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1a2b0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1a2c0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1a2d0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1a2e0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1a2f0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1a300 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1a310 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
1a320 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1a330 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1a340 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1a350 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1a360 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1a370 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1a380 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1a390 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
1a3a0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
1a3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1a3c0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
1a3d0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
1a3e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
1a3f0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
1a400 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
1a410 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
1a420 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1a430 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
1a440 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
1a450 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
1a460 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
1a470 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
1a480 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
1a490 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
1a4a0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
1a4b0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
1a4c0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1a4d0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1a4e0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1a4f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1a500 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d  H13011] [H13012]
1a510 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31   [H13013] [H1301
1a520 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33  4] [H13015] [H13
1a530 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48  016] [H13019] [H
1a540 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74  13021].**.*/.int
1a550 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1a560 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1a570 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1a580 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1a590 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a5a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1a5b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1a5c0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1a5d0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a5e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a5f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a600 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a610 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a620 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a630 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a640 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1a650 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1a660 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a670 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a680 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a690 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1a6a0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1a6b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a6c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1a6d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a6e0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1a6f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1a700 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1a710 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1a720 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1a730 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1a740 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1a750 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1a760 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1a770 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1a780 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1a790 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1a7a0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1a7b0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1a7c0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1a7d0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1a7e0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1a7f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1a800 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1a810 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1a820 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1a830 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1a840 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1a850 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1a860 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1a870 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1a880 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1a890 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1a8a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1a8b0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1a8c0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1a8d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1a8e0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1a8f0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1a900 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1a910 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1a920 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1a930 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1a940 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1a950 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1a960 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a970 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1a980 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1a990 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1a9a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1a9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1a9c0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1a9d0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1a9e0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1a9f0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1aa00 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1aa10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1aa20 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1aa30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1aa40 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1aa50 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1aa60 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1aa70 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1aa80 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1aa90 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e  H13100} <H13000>
1aaa0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1aab0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1aac0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1aad0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1aae0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1aaf0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1ab00 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1ab10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1ab20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1ab30 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1ab40 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1ab50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ab60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1ab70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1ab80 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1ab90 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20  ts:.** [H13101] 
1aba0 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33  [H13102] [H13103
1abb0 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1abc0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
1abd0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1abe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1abf0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
1ac00 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
1ac10 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30  ct {H15000} <S20
1ac20 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
1ac30 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1ac40 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1ac50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ac60 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1ac70 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1ac80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ac90 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1aca0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1acb0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1acc0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1acd0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1ace0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1acf0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1ad00 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61  es it stores. Va
1ad10 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1ad20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ad30 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
1ad40 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
1ad50 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
1ad60 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
1ad70 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
1ad80 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1ad90 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
1ada0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
1adb0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
1adc0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
1add0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
1ade0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1adf0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
1ae00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
1ae10 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
1ae20 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
1ae30 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
1ae40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1ae50 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
1ae60 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
1ae70 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
1ae80 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
1ae90 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1aea0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1aeb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1aec0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1aed0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1aee0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1aef0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1af00 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1af10 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1af20 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1af30 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1af40 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1af50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1af60 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1af70 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1af80 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1af90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1afa0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1afb0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1afc0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1afd0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
1afe0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
1aff0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
1b000 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1b010 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
1b020 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
1b030 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
1b040 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
1b050 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
1b060 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
1b070 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
1b080 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1b090 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
1b0a0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
1b0b0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1b0c0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1b0d0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1b0e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
1b0f0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
1b100 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
1b110 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
1b120 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
1b130 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1b140 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1b150 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
1b160 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
1b170 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
1b180 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e   between between
1b190 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1b1a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1b1b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1b1c0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
1b1d0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
1b1e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1b1f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1b200 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1b210 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1b220 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1b230 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b240 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1b250 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1b260 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1b270 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1b280 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1b290 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1b2a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1b2b0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1b2c0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1b2d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1b2e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1b2f0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1b300 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1b310 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1b320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1b330 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
1b340 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1b350 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1b360 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1b370 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1b380 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1b390 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1b3a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1b3b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1b3c0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1b3d0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1b3e0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
1b3f0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1b400 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30   {H16001} <S2020
1b410 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  0>.**.** The con
1b420 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
1b430 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
1b440 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
1b450 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
1b460 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
1b470 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  .  A pointer to 
1b480 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1b490 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1b4a0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1b4b0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1b4c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1b4d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1b4e0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1b4f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1b500 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1b510 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1b520 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1b530 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1b540 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1b550 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1b560 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1b570 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1b580 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1b590 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1b5a0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1b5b0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1b5c0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1b5d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1b5e0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1b5f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1b600 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1b610 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1b620 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1b630 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1b640 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1b650 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1b660 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20  ared Statements 
1b670 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30  {H13500} <S70300
1b680 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1b690 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1b6a0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1b6b0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1b6c0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1b6d0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1b6e0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1b6f0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1b700 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1b710 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1b720 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1b730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b740 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
1b750 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
1b760 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
1b770 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
1b780 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] in one of thes
1b790 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1b7a0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1b7b0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1b7c0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1b7d0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1b7e0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1b7f0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1b800 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1b810 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1b820 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1b830 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69  al,.** and VVV i
1b840 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72  s an alpha-numer
1b850 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  ic parameter nam
1b860 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  e. The values of
1b870 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
1b880 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
1b890 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
1b8a0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
1b8b0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
1b8c0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
1b8d0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1b8e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1b8f0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
1b900 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1b910 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1b920 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1b930 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1b940 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1b950 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1b960 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1b970 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1b980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b990 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1b9a0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
1b9b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1b9c0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1b9d0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1b9e0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54   to be set..** T
1b9f0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1ba00 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1ba10 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
1ba20 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1ba30 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1ba40 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1ba50 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1ba60 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1ba70 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1ba80 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1ba90 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1baa0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1bab0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
1bac0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
1bad0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
1bae0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
1baf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1bb00 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
1bb10 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
1bb20 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
1bb30 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
1bb40 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
1bb50 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e  f NNN..** The NN
1bb60 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
1bb70 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
1bb80 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
1bb90 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
1bba0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
1bbb0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
1bbc0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
1bbd0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  999)..**.** The 
1bbe0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
1bbf0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
1bc00 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
1bc10 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  eter..**.** In t
1bc20 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
1bc30 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
1bc40 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
1bc50 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1bc60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1bc70 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
1bc80 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
1bc90 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
1bca0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
1bcb0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
1bcc0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
1bcd0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1bce0 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ters..** If the 
1bcf0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1bd00 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
1bd10 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
1bd20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
1bd30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1bd40 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
1bd50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1bd60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
1bd70 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1bd80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1bd90 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
1bda0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
1bdb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1bdc0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
1bdd0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
1bde0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
1bdf0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
1be00 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
1be10 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1be20 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
1be30 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
1be40 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
1be50 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
1be60 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
1be70 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
1be80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
1be90 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
1bea0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
1beb0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1bec0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74  e freed..** If t
1bed0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1bee0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
1bef0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
1bf00 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
1bf10 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
1bf20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
1bf30 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
1bf40 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
1bf50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1bf60 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
1bf70 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
1bf80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1bf90 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1bfa0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1bfb0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1bfc0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1bfd0 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f   zeroes.  A zero
1bfe0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
1bff0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
1c000 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
1c010 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
1c020 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
1c030 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1c040 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1c050 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1c060 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1c070 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1c080 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1c090 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1c0a0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
1c0b0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
1c0c0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
1c0d0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
1c0e0 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  s..** A negative
1c0f0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1c100 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1c110 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1c120 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   BLOB..**.** The
1c130 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1c140 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
1c150 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
1c160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c170 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
1c180 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
1c190 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1c1a0 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
1c1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c1c0 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
1c1d0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
1c1e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
1c1f0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
1c200 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
1c210 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
1c220 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
1c230 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1c240 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1c250 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
1c260 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
1c270 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
1c280 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
1c290 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
1c2a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1c2b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
1c2c0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
1c2d0 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
1c2e0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
1c2f0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
1c300 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  ls..** [SQLITE_M
1c310 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20  ISUSE] might be 
1c320 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73  returned if thes
1c330 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
1c340 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69  alled on a.** vi
1c350 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68  rtual machine th
1c360 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20  at is the wrong 
1c370 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68  state or which h
1c380 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  as already been 
1c390 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65  finalized..** De
1c3a0 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73  tection of misus
1c3b0 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e  e is unreliable.
1c3c0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73    Applications s
1c3d0 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64  hould not depend
1c3e0 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49  .** on SQLITE_MI
1c3f0 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53  SUSE returns.  S
1c400 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20  QLITE_MISUSE is 
1c410 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69  intended to indi
1c420 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69  cate a.** a logi
1c430 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61  c error in the a
1c440 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74  pplication.  Fut
1c450 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c460 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
1c470 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61  panic rather tha
1c480 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  n return SQLITE_
1c490 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65  MISUSE..**.** Se
1c4a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1c4b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1c4c0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
1c4d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1c4e0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
1c4f0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1c500 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1c510 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1c520 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35  ements:.** [H135
1c530 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31  06] [H13509] [H1
1c540 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b  3512] [H13515] [
1c550 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d  H13518] [H13521]
1c560 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32   [H13524] [H1352
1c570 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b  7].** [H13530] [
1c580 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d  H13533] [H13536]
1c590 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34   [H13539] [H1354
1c5a0 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33  2] [H13545] [H13
1c5b0 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a  548] [H13551].**
1c5c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c5d0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
1c5e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1c5f0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
1c600 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1c610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c620 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
1c630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
1c640 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
1c650 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
1c660 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c670 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1c680 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
1c690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c6a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1c6b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c6c0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
1c6d0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
1c6e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1c6f0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
1c700 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
1c710 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
1c720 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1c730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c740 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
1c750 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1c760 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
1c770 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c780 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1c790 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1c7a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
1c7b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1c7c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1c7d0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
1c7e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
1c7f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c800 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
1c810 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31  L Parameters {H1
1c820 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3600} <S70300>.*
1c830 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1c840 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1c850 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
1c860 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
1c870 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
1c880 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c890 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
1c8a0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
1c8b0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
1c8c0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
1c8d0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
1c8e0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
1c8f0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
1c900 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
1c910 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
1c920 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
1c930 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
1c940 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
1c950 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  r time..**.** Th
1c960 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
1c970 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1c980 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
1c990 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
1c9a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
1c9b0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1c9c0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1c9d0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1c9e0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
1c9f0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
1ca00 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1ca10 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1ca20 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
1ca30 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
1ca40 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1ca50 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1ca60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1ca70 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1ca80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ca90 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1caa0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1cab0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1cac0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1cad0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1cae0 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f  :.** [H13601].*/
1caf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1cb00 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1cb10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
1cb20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cb30 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
1cb40 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33  t Parameter {H13
1cb50 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  620} <S70300>.**
1cb60 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1cb70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1cb80 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
1cb90 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53  f the n-th.** [S
1cba0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
1cbb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1cbc0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20  tement]..** SQL 
1cbd0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
1cbe0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
1cbf0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
1cc00 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
1cc10 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
1cc20 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
1cc30 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
1cc40 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
1cc50 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
1cc60 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
1cc70 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
1cc80 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
1cc90 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
1cca0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
1ccb0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
1ccc0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
1ccd0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
1cce0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
1ccf0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
1cd00 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
1cd10 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64  re also referred
1cd20 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75   to as "anonymou
1cd30 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1cd40 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
1cd50 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
1cd60 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
1cd70 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
1cd80 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
1cd90 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
1cda0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
1cdb0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
1cdc0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
1cdd0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
1cde0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1cdf0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
1ce00 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
1ce10 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
1ce20 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
1ce30 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
1ce40 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
1ce50 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
1ce60 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
1ce70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ce80 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1ce90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1cea0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1ceb0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1cec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ced0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1cee0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1cef0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1cf00 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1cf10 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1cf20 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f  :.** [H13621].*/
1cf30 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1cf40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1cf50 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
1cf60 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
1cf70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1cf80 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
1cf90 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
1cfa0 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c   Name {H13640} <
1cfb0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S70300>.**.** Re
1cfc0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
1cfd0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
1cfe0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
1cff0 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78  e.  The.** index
1d000 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1d010 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
1d020 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
1d030 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1d040 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
1d050 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1d060 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a  d()].  A zero.**
1d070 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1d080 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
1d090 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
1d0a0 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   The parameter.*
1d0b0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
1d0c0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
1d0d0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
1d0e0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
1d0f0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
1d100 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
1d110 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1d120 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1d130 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1d140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1d150 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1d160 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1d170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1d180 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
1d190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d1a0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1d1b0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1d1c0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a  ts:.** [H13641].
1d1d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1d1e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1d1f0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
1d200 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
1d210 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
1d220 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
1d230 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
1d240 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1d250 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30  nt {H13660} <S70
1d260 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  300>.**.** Contr
1d270 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
1d280 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
1d290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1d2a0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
1d2b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
1d2c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
1d2d0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
1d2e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1d2f0 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
1d300 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
1d310 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
1d320 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
1d330 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1d340 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74   [H13661].*/.int
1d350 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
1d360 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
1d370 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1d380 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
1d390 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
1d3a0 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
1d3b0 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  10} <S10700>.**.
1d3c0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
1d3d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1d3e0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1d3f0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
1d400 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1d410 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20  tatement]. This 
1d420 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1d430 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
1d440 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1d450 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
1d460 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
1d470 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
1d480 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ATE])..**.** Req
1d490 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1d4a0 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13711].*/.int sq
1d4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
1d4c0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
1d4d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1d4e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
1d4f0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
1d500 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20  lt Set {H13720} 
1d510 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1d520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1d530 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
1d540 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
1d550 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
1d560 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
1d570 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
1d580 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
1d590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d5a0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
1d5b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
1d5c0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1d5d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1d5e0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
1d5f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1d600 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
1d610 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1d620 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1d630 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
1d640 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1d650 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
1d660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d670 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
1d680 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
1d690 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
1d6a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d6b0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
1d6c0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
1d6d0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
1d6e0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
1d6f0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1d700 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
1d710 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
1d720 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
1d730 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
1d740 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
1d750 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1d760 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
1d770 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
1d780 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
1d790 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
1d7a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1d7b0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
1d7c0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
1d7d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d7e0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
1d7f0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
1d800 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
1d810 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
1d820 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
1d830 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
1d840 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
1d850 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1d860 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1d870 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
1d880 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
1d890 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1d8a0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
1d8b0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
1d8c0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
1d8d0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
1d8e0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
1d8f0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
1d900 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
1d910 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
1d920 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
1d930 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
1d940 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
1d950 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
1d960 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1d970 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b  s:.** [H13721] [
1d980 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d  H13723] [H13724]
1d990 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32   [H13725] [H1372
1d9a0 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63  6] [H13727].*/.c
1d9b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1d9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
1d9d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d9e0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
1d9f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1da00 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1da10 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
1da20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da30 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
1da40 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
1da50 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
1da60 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
1da70 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
1da80 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
1da90 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
1daa0 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
1dab0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
1dac0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
1dad0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1dae0 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
1daf0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
1db00 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
1db10 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
1db20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
1db30 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
1db40 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
1db50 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
1db60 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
1db70 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
1db80 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
1db90 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
1dba0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
1dbb0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
1dbc0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
1dbd0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
1dbe0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
1dbf0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
1dc00 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
1dc10 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
1dc20 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
1dc30 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
1dc40 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1dc50 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
1dc60 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
1dc70 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
1dc80 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
1dc90 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
1dca0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
1dcb0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
1dcc0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
1dcd0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
1dce0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
1dcf0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
1dd00 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
1dd10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1dd20 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
1dd30 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
1dd40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1dd50 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1dd60 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
1dd70 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
1dd80 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
1dd90 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
1dda0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
1ddb0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1ddc0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
1ddd0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1dde0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
1ddf0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
1de00 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
1de10 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
1de20 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
1de30 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
1de40 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
1de50 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
1de60 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
1de70 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
1de80 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
1de90 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
1dea0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
1deb0 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
1dec0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
1ded0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
1dee0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
1def0 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
1df00 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
1df10 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
1df20 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
1df30 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
1df40 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
1df50 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
1df60 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
1df70 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
1df80 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
1df90 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
1dfa0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1dfb0 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
1dfc0 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
1dfd0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
1dfe0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1dff0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1e000 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
1e010 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1e020 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
1e030 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
1e040 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
1e050 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
1e060 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
1e070 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
1e080 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
1e090 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
1e0a0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
1e0b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
1e0c0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
1e0d0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1e0e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
1e0f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1e100 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1e110 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33  ** [H13741] [H13
1e120 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48  742] [H13743] [H
1e130 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20  13744] [H13745] 
1e140 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38  [H13746] [H13748
1e150 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ].**.** If two o
1e160 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1e170 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
1e180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1e190 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1e1a0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
1e1b0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1e1c0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
1e1d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e1e0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
1e1f0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
1e200 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
1e210 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
1e220 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
1e230 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1e240 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1e250 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1e260 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1e270 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1e280 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1e290 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1e2a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
1e2b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1e2c0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
1e2d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1e2e0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1e2f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
1e300 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
1e310 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1e320 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1e330 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1e340 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1e350 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1e360 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1e370 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1e380 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1e390 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
1e3a0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
1e3b0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
1e3c0 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
1e3d0 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  760} <S10700>.**
1e3e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
1e3f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
1e400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e410 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
1e420 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
1e430 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1e440 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
1e450 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
1e460 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
1e470 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
1e480 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
1e490 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
1e4a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1e4b0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
1e4c0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
1e4d0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
1e4e0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
1e4f0 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
1e500 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
1e510 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
1e520 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
1e530 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
1e540 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
1e550 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
1e560 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1e570 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
1e580 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a  encoded. {END}.*
1e590 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1e5a0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
1e5b0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
1e5c0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
1e5d0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
1e5e0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
1e5f0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
1e600 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1e610 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
1e620 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
1e630 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
1e640 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
1e650 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
1e660 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
1e670 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
1e680 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
1e690 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
1e6a0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
1e6b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
1e6c0 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
1e6d0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1e6e0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
1e6f0 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
1e700 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
1e710 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
1e720 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
1e730 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
1e740 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
1e750 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
1e760 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
1e770 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
1e780 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
1e790 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
1e7a0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
1e7b0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
1e7c0 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
1e7d0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
1e7e0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
1e7f0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
1e800 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
1e810 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
1e820 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
1e830 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1e840 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b  s:.** [H13761] [
1e850 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d  H13762] [H13763]
1e860 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1e870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1e880 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
1e890 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1e8a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1e8b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
1e8c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1e8d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1e8e0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
1e8f0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1e900 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30   {H13200} <S1000
1e910 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0>.**.** After a
1e920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e930 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
1e940 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
1e950 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
1e960 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1e970 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1e980 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
1e990 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
1e9a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
1e9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1e9c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1e9d0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
1e9e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
1e9f0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
1ea00 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
1ea10 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
1ea20 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
1ea30 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
1ea40 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
1ea50 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
1ea60 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
1ea70 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
1ea80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
1ea90 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
1eaa0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
1eab0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
1eac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ead0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1eae0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1eaf0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
1eb00 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
1eb10 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1eb20 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
1eb30 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
1eb40 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
1eb50 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
1eb60 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
1eb70 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
1eb80 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
1eb90 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
1eba0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
1ebb0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
1ebc0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
1ebd0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
1ebe0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
1ebf0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
1ec00 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
1ec10 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
1ec20 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
1ec30 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
1ec40 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
1ec50 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
1ec60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1ec70 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
1ec80 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
1ec90 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
1eca0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1ecb0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
1ecc0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
1ecd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1ece0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
1ecf0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
1ed00 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
1ed10 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
1ed20 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
1ed30 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
1ed40 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
1ed50 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
1ed60 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
1ed70 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
1ed80 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1ed90 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
1eda0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
1edb0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
1edc0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
1edd0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
1ede0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
1edf0 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
1ee00 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
1ee10 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
1ee20 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
1ee30 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
1ee40 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b  tinuing..**.** [
1ee50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
1ee60 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
1ee70 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
1ee80 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
1ee90 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
1eea0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
1eeb0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
1eec0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
1eed0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
1eee0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
1eef0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1ef00 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
1ef10 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
1ef20 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
1ef30 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
1ef40 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  state..**.** If 
1ef50 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ef60 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
1ef70 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
1ef80 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
1ef90 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
1efa0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
1efb0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
1efc0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
1efd0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
1efe0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
1eff0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
1f000 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
1f010 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
1f020 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
1f030 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
1f040 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
1f050 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
1f060 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
1f070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
1f080 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
1f090 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
1f0a0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
1f0b0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
1f0c0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
1f0d0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
1f0e0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
1f0f0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
1f100 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
1f110 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
1f120 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
1f130 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
1f140 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
1f150 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
1f160 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
1f170 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
1f180 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
1f190 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
1f1a0 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
1f1b0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
1f1c0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
1f1d0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
1f1e0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
1f1f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1f200 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
1f210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f220 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76  ent].  In the "v
1f230 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
1f240 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
1f250 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
1f260 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
1f270 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
1f280 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
1f290 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
1f2a0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
1f2b0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
1f2c0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
1f2d0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
1f2e0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
1f2f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1f300 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
1f310 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
1f320 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f330 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
1f340 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
1f350 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
1f360 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
1f370 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
1f380 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
1f390 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
1f3a0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
1f3b0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1f3c0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
1f3d0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
1f3e0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
1f3f0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
1f400 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
1f410 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
1f420 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
1f430 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
1f440 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
1f450 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
1f460 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
1f470 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
1f480 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
1f490 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
1f4a0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
1f4b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1f4c0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
1f4d0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
1f4e0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
1f4f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1f500 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
1f510 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
1f520 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
1f530 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1f540 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
1f550 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
1f560 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
1f570 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
1f580 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
1f590 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
1f5a0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
1f5b0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
1f5c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
1f5d0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
1f5e0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
1f5f0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
1f600 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1f610 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f620 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1f630 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
1f640 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
1f650 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
1f660 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1f670 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f680 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
1f690 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
1f6a0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
1f6b0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
1f6c0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
1f6d0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
1f6e0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
1f6f0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
1f700 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
1f710 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ded..**.** Requi
1f720 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1f730 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48  202] [H15304] [H
1f740 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20  15306] [H15308] 
1f750 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20  [H15310].*/.int 
1f760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
1f770 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1f780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f790 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1f7a0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20  in a result set 
1f7b0 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30  {H13770} <S10700
1f7c0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20  >.**.** Returns 
1f7d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
1f7e0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
1f7f0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
1f800 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
1f810 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1f820 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37  * [H13771] [H137
1f830 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  72].*/.int sqlit
1f840 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
1f850 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1f860 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f870 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
1f880 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32   Datatypes {H102
1f890 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30  65} <S10110><S10
1f8a0 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  120>.** KEYWORDS
1f8b0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
1f8c0 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65  .** {H10266} Eve
1f8d0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
1f8e0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
1f8f0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
1f900 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
1f910 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
1f920 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1f930 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
1f940 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
1f950 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
1f960 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
1f970 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
1f980 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b   NULL.** </ul> {
1f990 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
1f9a0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
1f9b0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
1f9c0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
1f9d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
1f9e0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
1f9f0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
1fa00 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
1fa10 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
1fa20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
1fa30 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
1fa40 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
1fa50 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
1fa60 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
1fa70 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
1fa80 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
1fa90 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
1faa0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
1fab0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
1fac0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
1fad0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
1fae0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
1faf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
1fb00 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
1fb10 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
1fb20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
1fb30 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
1fb40 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
1fb50 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1fb60 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
1fb70 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
1fb80 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
1fb90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1fba0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
1fbb0 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30   A Query {H13800
1fbc0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45  } <S10700>.** KE
1fbd0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
1fbe0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
1fbf0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
1fc00 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
1fc10 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72  "result set quer
1fc20 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  y" interface..**
1fc30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1fc40 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
1fc50 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
1fc60 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
1fc70 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
1fc80 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
1fc90 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63  ery.  In every c
1fca0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
1fcb0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1fcc0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
1fcd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fce0 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
1fcf0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
1fd00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
1fd10 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
1fd20 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
1fd30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1fd40 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
1fd50 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
1fd60 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
1fd70 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
1fd80 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
1fd90 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
1fda0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
1fdb0 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  e returned.  The
1fdc0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
1fdd0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
1fde0 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
1fdf0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
1fe00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
1fe10 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
1fe20 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
1fe30 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
1fe40 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
1fe50 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
1fe60 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
1fe70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
1fe80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
1fe90 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
1fea0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
1feb0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
1fec0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1fed0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
1fee0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
1fef0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
1ff00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
1ff10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1ff20 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
1ff30 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
1ff40 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
1ff50 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1ff60 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
1ff70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
1ff80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1ff90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1ffa0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
1ffb0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
1ffc0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
1ffd0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
1ffe0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
1fff0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
20000 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
20010 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
20020 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20030 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
20040 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
20050 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
20060 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
20070 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
20080 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
20090 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
200a0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
200b0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
200c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
200d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
200e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
200f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
20100 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
20110 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
20120 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
20130 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
20140 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
20150 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
20160 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
20170 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
20180 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
20190 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
201a0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
201b0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
201c0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
201d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
201e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
201f0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
20200 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
20210 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
20220 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
20230 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
20240 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
20250 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
20260 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
20270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
20280 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
20290 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
202a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
202b0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
202c0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
202d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
202e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
202f0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
20300 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
20310 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
20320 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
20330 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
20340 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
20350 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20370 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
20380 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
20390 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
203a0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
203b0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
203c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
203d0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
203e0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
203f0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
20400 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20410 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
20420 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
20430 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
20440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
20450 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
20460 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
20470 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
20480 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
20490 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
204a0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
204b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
204c0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54  hat string..** T
204d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
204e0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
204f0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
20500 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
20510 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
20520 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79  ng.  For clarity
20530 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  : the value retu
20540 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62  rned is the numb
20550 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
20560 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
20570 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
20580 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
20590 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e  * Strings return
205a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
205b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
205c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
205d0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
205e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
205f0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
20600 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
20610 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
20620 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
20630 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
20640 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
20650 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  OB is an arbitra
20660 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
20670 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
20680 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20690 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
206a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
206b0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
206c0 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
206d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
206e0 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
206f0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
20700 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
20710 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
20720 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65  UTF-8..** The ze
20730 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73  ro terminator is
20740 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e   not included in
20750 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a   this count..**.
20760 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65  ** The object re
20770 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20780 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
20790 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
207a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
207b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
207c0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
207d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
207e0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
207f0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
20800 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20810 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
20820 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
20830 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
20840 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20850 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
20860 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
20870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
20880 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
20890 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
208a0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
208b0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
208c0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
208d0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
208e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
208f0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
20900 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
20910 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
20920 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
20930 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
20940 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
20950 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
20960 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
20970 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
20980 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
20990 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
209a0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
209b0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
209c0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
209d0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
209e0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
209f0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
20a00 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
20a10 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
20a20 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
20a30 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
20a40 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
20a50 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
20a60 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
20a70 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
20a80 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
20a90 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
20aa0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
20ab0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
20ac0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
20ad0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
20ae0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
20af0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
20b00 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
20b10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20b20 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
20b30 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
20b40 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
20b50 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20b60 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20b70 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
20b80 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
20b90 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20ba0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
20bb0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
20bc0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
20bd0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
20be0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
20bf0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
20c00 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
20c10 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
20c20 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
20c30 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
20c40 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
20c50 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
20c60 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
20c70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20c80 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
20c90 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
20ca0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
20cb0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
20cc0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
20cd0 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
20ce0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
20cf0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
20d00 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
20d10 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
20d20 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
20d30 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
20d40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
20d50 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
20d60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
20d70 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
20d80 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
20d90 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
20da0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
20db0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
20dc0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
20dd0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
20de0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
20df0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
20e00 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
20e10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
20e20 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
20e30 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
20e40 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
20e50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
20e60 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
20e70 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
20e80 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
20e90 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
20ea0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
20eb0 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
20ec0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
20ed0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
20ee0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
20ef0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  e>.**.** The tab
20f00 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
20f10 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
20f20 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
20f30 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
20f40 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
20f50 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
20f60 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
20f70 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
20f80 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
20f90 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
20fa0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
20fb0 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
20fc0 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
20fd0 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
20fe0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
20ff0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
21000 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
21010 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
21020 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
21030 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
21040 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
21050 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
21060 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
21070 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
21080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21090 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
210a0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
210b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
210c0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
210d0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
210e0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
210f0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
21100 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
21110 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
21120 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
21130 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
21140 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
21150 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
21160 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
21170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
21180 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
21190 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
211a0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
211b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
211c0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
211d0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
211e0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
211f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
21200 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
21210 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
21220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21230 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
21240 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
21250 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
21260 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
21270 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
21280 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
21290 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
212a0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
212b0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
212c0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
212d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
212e0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
212f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21300 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
21310 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
21320 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
21330 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
21340 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
21350 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
21360 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
21370 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
21380 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
21390 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
213a0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
213b0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
213c0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
213d0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
213e0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
213f0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
21400 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
21410 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
21420 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
21430 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
21440 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
21450 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
21460 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
21470 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
21480 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
21490 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
214a0 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
214b0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
214c0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
214d0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
214e0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
214f0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
21500 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
21510 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
21520 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
21530 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
21540 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
21550 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
21560 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
21570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21580 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
21590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
215a0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
215b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
215c0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
215d0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
215e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
215f0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
21600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
21610 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
21620 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
21630 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
21640 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
21650 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
21660 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21670 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
21680 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
21690 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
216a0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
216b0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
216c0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
216d0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
216e0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
216f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
21700 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
21710 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
21720 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
21730 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
21740 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21750 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
21760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
21770 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
21780 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
21790 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
217a0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
217b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
217c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
217d0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
217e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
217f0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  es()..**.** The 
21800 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
21810 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
21820 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
21830 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
21840 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
21850 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
21860 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
21870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21880 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21890 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
218a0 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f  alled.  The memo
218b0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
218c0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
218d0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
218e0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
218f0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
21900 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
21910 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
21920 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21930 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
21940 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
21950 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
21960 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
21970 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f  .**.** If a memo
21980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
21990 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
219a0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
219b0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
219c0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
219d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
219e0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
219f0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
21a00 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
21a10 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
21a20 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
21a30 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
21a40 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
21a50 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
21a60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
21a70 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
21a80 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
21a90 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  OMEM]..**.** Req
21aa0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
21ab0 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20  13803] [H13806] 
21ac0 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32  [H13809] [H13812
21ad0 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38  ] [H13815] [H138
21ae0 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31  18] [H13821] [H1
21af0 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37  3824].** [H13827
21b00 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f  ] [H13830].*/.co
21b10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21b20 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
21b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21b40 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
21b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21b60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21b70 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
21b80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21b90 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
21ba0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
21bb0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
21bc0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
21bd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21be0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
21bf0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
21c00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21c10 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
21c20 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
21c30 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
21c40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21c50 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
21c60 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
21c70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
21c80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21c90 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
21ca0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21cb0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
21cc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21cd0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
21ce0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
21cf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21d00 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
21d10 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
21d20 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
21d30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21d40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
21d50 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
21d60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
21d70 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30  t Object {H13300
21d80 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30  } <S70300><S3010
21d90 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
21da0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
21db0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
21dc0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
21dd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21de0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  nt]..** If the s
21df0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65  tatement was exe
21e00 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
21e10 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  ly or not execut
21e20 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a  ed at all, then.
21e30 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  ** SQLITE_OK is 
21e40 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65  returned. If exe
21e50 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
21e60 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
21e70 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72  hen an.** [error
21e80 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
21e90 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
21ea0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
21eb0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
21ec0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
21ed0 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
21ee0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
21ef0 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  of the.** [prepa
21f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21f10 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   If the virtual 
21f20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
21f30 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
21f40 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
21f50 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
21f60 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
21f70 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
21f80 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
21f90 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
21fa0 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
21fb0 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
21fc0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
21fd0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
21fe0 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
21ff0 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  led,.** dependin
22000 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
22010 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a  tances, and the.
22020 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
22030 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
22040 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
22050 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
22060 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d  nts:.** [H11302]
22070 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74   [H11304].*/.int
22080 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
22090 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
220a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
220b0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
220c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
220d0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
220e0 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  30} <S70300>.**.
220f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
22100 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
22110 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
22120 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
22130 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
22140 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
22150 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
22160 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
22170 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
22180 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
22190 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
221a0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
221b0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
221c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
221d0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
221e0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
221f0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
22200 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
22210 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
22220 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
22230 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
22240 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {H11332} The [s
22250 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
22260 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
22270 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
22280 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
22290 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
222a0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
222b0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
222c0 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66  *.** {H11334} If
222d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
222e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
222f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
22300 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
22310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22320 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
22330 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
22340 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
22350 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
22360 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
22370 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
22380 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
22390 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  n S,.**         
223a0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
223b0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
223c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
223d0 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20  .** {H11336} If 
223e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
223f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22400 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
22410 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
22420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22430 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
22440 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
22450 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22460 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
22470 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
22480 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
22490 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d  ..**.** {H11338}
224a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
224b0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
224c0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
224d0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
224e0 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20           of any 
224f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22500 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
22510 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22520 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
22530 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
22540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
22550 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
22560 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
22570 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
22580 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30  unctions {H16100
22590 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
225a0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
225b0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
225c0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
225d0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
225e0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
225f0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
22600 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
22610 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
22620 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
22630 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
22640 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
22650 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
22660 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
22670 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
22680 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
22690 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
226a0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
226b0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
226c0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
226d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
226e0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
226f0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
22700 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
22710 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
22720 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22730 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
22740 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
22750 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
22760 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
22770 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
22780 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
22790 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
227a0 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
227b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
227c0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
227d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
227e0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
227f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
22800 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
22810 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
22820 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
22830 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75  single program u
22840 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
22850 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
22860 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61  nnection interna
22870 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75  lly, then SQL fu
22880 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
22890 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
228a0 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61  ly to.** each da
228b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
228c0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
228d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
228e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
228f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
22900 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
22910 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68  * redefined.  Th
22920 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
22930 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
22940 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
22950 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
22960 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
22970 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
22980 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
22990 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
229a0 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
229b0 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
229c0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
229d0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
229e0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
229f0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
22a00 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20  TE_ERROR] being 
22a10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
22a20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
22a30 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
22a40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
22a50 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
22a60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
22a70 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
22a80 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
22a90 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
22aa0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
22ab0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
22ac0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
22ad0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
22ae0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
22af0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
22b00 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
22b10 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
22b20 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
22b30 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
22b40 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
22b50 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
22b60 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
22b70 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
22b80 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
22b90 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
22ba0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22bb0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
22bc0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
22bd0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
22be0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
22bf0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
22c00 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
22c10 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
22c20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
22c30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22c40 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
22c50 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
22c60 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
22c70 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
22c80 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
22c90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
22ca0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
22cb0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
22cc0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
22cd0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
22ce0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
22cf0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
22d00 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
22d10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
22d20 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
22d30 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
22d40 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
22d50 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
22d60 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
22d70 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
22d80 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
22d90 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
22da0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
22db0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
22dc0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
22dd0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
22de0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
22df0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
22e00 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
22e10 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
22e20 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
22e30 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
22e40 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
22e50 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
22e60 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
22e70 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
22e80 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
22e90 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
22ea0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
22eb0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
22ec0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
22ed0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
22ee0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
22ef0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
22f00 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
22f10 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
22f20 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
22f30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
22f40 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
22f50 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
22f60 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
22f70 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
22f80 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
22f90 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
22fa0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
22fb0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
22fc0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
22fd0 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
22fe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
22ff0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
23000 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
23010 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
23020 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
23030 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
23040 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
23050 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
23060 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
23070 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
23080 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
23090 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
230a0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
230b0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
230c0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
230d0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
230e0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
230f0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
23100 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
23110 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
23120 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
23130 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
23140 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
23150 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
23160 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
23170 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
23180 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
23190 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
231a0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
231b0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
231c0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
231d0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
231e0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
231f0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
23200 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
23210 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
23220 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
23230 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
23240 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
23250 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
23260 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74  s used.  A funct
23270 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
23280 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
23290 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
232a0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
232b0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
232c0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
232d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
232e0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
232f0 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77  g.  A function w
23300 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
23310 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
23320 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
23330 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
23340 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
23350 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
23360 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
23370 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
23380 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66  ferent.  .** A f
23390 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
233a0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
233b0 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
233c0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
233d0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
233e0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
233f0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
23400 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
23410 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
23420 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
23430 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c  TF16..**.** Buil
23440 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
23450 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
23460 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
23470 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
23480 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69  tions..** The fi
23490 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
234a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
234b0 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
234c0 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
234d0 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
234e0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
234f0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
23500 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
23510 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
23520 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69  Subsequent appli
23530 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
23540 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  unctions of the 
23550 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f  same name only o
23560 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f  verride .** prio
23570 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  r application-de
23580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
23590 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63  that are an exac
235a0 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a  t match for the.
235b0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  ** number of par
235c0 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66  ameters and pref
235d0 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a  erred encoding..
235e0 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61  **.** An applica
235f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
23600 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
23610 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
23620 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
23630 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
23640 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
23650 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
23660 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23670 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
23680 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
23690 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
236a0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
236b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
236c0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65  unning..**.** Re
236d0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
236e0 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30 36 5d  H16103] [H16106]
236f0 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 31 31   [H16109] [H1611
23700 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 31 36  2] [H16118] [H16
23710 31 32 31 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a  121] [H16127].**
23720 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33   [H16130] [H1613
23730 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36  3] [H16136] [H16
23740 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f  139] [H16142].*/
23750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
23760 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
23770 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
23780 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
23790 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
237a0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
237b0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
237c0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
237d0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
237e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
237f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
23800 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
23810 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
23820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
23830 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
23840 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
23850 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
23860 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
23870 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
23880 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
23890 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
238a0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
238b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
238c0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
238d0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
238e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
238f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
23900 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
23910 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
23920 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
23930 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
23940 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
23950 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
23960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23970 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
23980 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30   {H10267} <S5020
23990 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a  0> <H16100>.**.*
239a0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
239b0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
239c0 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
239d0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
239e0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
239f0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
23a00 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
23a10 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
23a20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
23a30 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
23a40 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
23a50 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
23a60 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
23a70 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
23a80 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
23a90 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
23aa0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
23ab0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
23ac0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
23ad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23ae0 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
23af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
23b00 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
23b10 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
23b20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
23b30 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
23b40 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
23b50 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
23b60 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
23b70 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
23b80 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
23b90 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
23ba0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
23bb0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
23bc0 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
23bd0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
23be0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
23bf0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
23c00 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
23c10 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
23c20 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
23c30 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
23c40 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
23c50 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
23c60 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
23c70 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
23c80 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
23c90 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
23ca0 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
23cb0 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
23cc0 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
23cd0 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
23ce0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
23cf0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
23d00 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
23d10 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
23d20 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
23d30 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
23d40 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
23d50 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
23d60 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
23d70 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
23d80 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
23d90 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
23da0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
23db0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
23dc0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
23dd0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23de0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
23df0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
23e00 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23e10 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
23e20 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
23e30 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
23e40 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
23e50 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
23e60 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
23e70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
23e80 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
23e90 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
23ea0 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53  lues {H15100} <S
23eb0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
23ec0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
23ed0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
23ee0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
23ef0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
23f00 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
23f10 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
23f20 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
23f30 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
23f40 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
23f50 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
23f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
23f70 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
23f80 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
23f90 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
23fa0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
23fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
23fc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
23fd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
23fe0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
23ff0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
24000 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
24010 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
24020 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
24030 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
24040 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
24050 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
24060 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
24070 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
24080 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24090 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
240a0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
240b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
240c0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
240d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
240e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
240f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24100 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
24110 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
24120 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
24130 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
24140 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24150 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
24160 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
24170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
24180 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
24190 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
241a0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
241b0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
241c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
241d0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
241e0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
241f0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  avior..**.** The
24200 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
24210 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
24220 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
24230 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
24240 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
24250 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
24260 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
24270 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
24280 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
24290 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
242a0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
242b0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
242c0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
242d0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
242e0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
242f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24300 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
24310 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
24320 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
24330 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
24340 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
24350 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
24360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
24370 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
24380 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24390 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
243a0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
243b0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
243c0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
243d0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
243e0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ctively..**.** T
243f0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
24400 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
24410 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
24420 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
24430 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
24440 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
24450 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
24460 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
24470 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
24480 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
24490 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
244a0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
244b0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
244c0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
244d0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
244e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
244f0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
24500 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
24510 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
24520 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
24530 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
24540 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
24550 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
24560 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
24570 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
24580 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
24590 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
245a0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
245b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
245c0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
245d0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
245e0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
245f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
24600 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
24610 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
24620 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
24630 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
24640 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
24650 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
24660 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
24670 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
24680 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
24690 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
246a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
246b0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
246c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
246d0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
246e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
246f0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
24700 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
24710 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
24720 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
24730 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
24740 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
24750 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
24760 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
24770 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ters..**.** Requ
24780 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
24790 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b  5103] [H15106] [
247a0 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d  H15109] [H15112]
247b0 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31   [H15115] [H1511
247c0 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35  8] [H15121] [H15
247d0 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d  124].** [H15127]
247e0 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33   [H15130] [H1513
247f0 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63  3] [H15136].*/.c
24800 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
24810 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
24820 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
24830 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
24840 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
24850 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
24860 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
24870 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
24880 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
24890 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
248a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
248b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
248c0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
248d0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
248e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
248f0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
24900 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
24910 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
24920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
24930 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
24940 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24950 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
24960 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
24970 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
24980 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
24990 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
249a0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
249b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
249c0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
249d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
249e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
249f0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
24a00 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24a10 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
24a20 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
24a30 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
24a40 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
24a50 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
24a60 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d  Context {H16210}
24a70 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
24a80 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
24a90 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  on of aggregate 
24aa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
24ab0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
24ac0 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20  o allocate.** a 
24ad0 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
24ae0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
24af0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
24b00 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
24b10 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
24b20 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20  ntext() routine 
24b30 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a  is called for a.
24b40 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67  ** particular ag
24b50 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20  gregate, SQLite 
24b60 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73  allocates nBytes
24b70 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
24b80 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d  es out that.** m
24b90 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
24ba0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
24bb0 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  it. On second an
24bc0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
24bd0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
24be0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
24bf0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
24c00 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
24c10 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74  tion index,.** t
24c20 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
24c30 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20  s returned. The 
24c40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
24c50 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
24c60 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72  can use.** the r
24c70 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
24c80 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
24c90 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  a..**.** SQLite 
24ca0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
24cb0 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  ees the allocate
24cc0 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68  d buffer when th
24cd0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
24ce0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
24cf0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
24d00 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
24d10 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
24d20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
24d30 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
24d40 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
24d50 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
24d60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
24d70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  the callback rou
24d80 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
24d90 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
24da0 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  te function..**.
24db0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
24dc0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
24dd0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
24de0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
24df0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
24e00 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
24e10 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
24e20 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
24e30 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20  16211] [H16213] 
24e40 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37  [H16215] [H16217
24e50 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
24e60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
24e70 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
24e80 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
24e90 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
24ea0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
24eb0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  or Functions {H1
24ec0 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6240} <S20200>.*
24ed0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24ee0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
24ef0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
24f00 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
24f10 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
24f20 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
24f30 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
24f40 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
24f50 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
24f60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
24f70 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
24f80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24f90 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
24fa0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
24fb0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
24fc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
24fd0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
24fe0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
24ff0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
25000 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
25010 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
25020 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
25030 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25040 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
25050 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
25060 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
25070 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  16243].*/.void *
25080 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
25090 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
250a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
250b0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
250c0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
250d0 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d  nctions {H16250}
250e0 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30   <S60600><S20200
250f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
25100 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
25110 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
25120 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
25130 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
25140 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
25150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25160 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
25170 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
25180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
25190 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
251a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
251b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
251c0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
251d0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
251e0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
251f0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
25200 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65  nction..**.** Re
25210 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
25220 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74  H16253].*/.sqlit
25230 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
25240 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
25250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
25260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25270 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
25280 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37  iary Data {H1627
25290 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
252a0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
252b0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
252c0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
252d0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
252e0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
252f0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
25300 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
25310 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
25320 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
25330 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
25340 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
25350 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
25360 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
25370 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
25380 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
25390 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
253a0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
253b0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
253c0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
253d0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
253e0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
253f0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
25400 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
25410 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
25420 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
25430 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
25440 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
25450 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
25460 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
25470 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
25480 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
25490 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
254a0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
254b0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
254c0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
254d0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
254e0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
254f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
25500 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
25510 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
25520 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
25530 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
25540 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
25550 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
25560 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
25570 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
25580 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
25590 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
255a0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
255b0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
255c0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
255d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
255e0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
255f0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
25600 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
25610 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25620 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20  function. If no 
25630 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
25640 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
25650 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
25660 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
25670 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
25680 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
25690 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
256a0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
256b0 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
256c0 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
256d0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
256e0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
256f0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
25700 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
25710 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25720 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
25730 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
25740 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
25750 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
25760 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
25770 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
25780 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
25790 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
257a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
257b0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
257c0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
257d0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
257e0 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
257f0 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
25800 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
25810 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66  destroyed..** If
25820 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
25830 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
25840 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
25850 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
25860 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
25870 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25880 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
25890 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
258a0 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
258b0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
258c0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
258d0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
258e0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
258f0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
25900 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
25910 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
25920 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
25930 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
25940 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
25950 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
25960 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
25970 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
25980 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20  time.  The only 
25990 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
259a0 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
259b0 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
259c0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
259d0 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
259e0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
259f0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
25a00 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
25a10 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
25a20 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
25a30 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
25a40 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
25a50 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
25a60 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
25a70 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c  * values and SQL
25a80 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a   variables..**.*
25a90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25aa0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
25ab0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
25ac0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
25ad0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25ae0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
25af0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
25b00 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48  :.** [H16272] [H
25b10 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20  16274] [H16276] 
25b20 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38  [H16277] [H16278
25b30 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f  ] [H16279].*/.vo
25b40 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
25b50 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
25b60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
25b70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
25b80 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
25b90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
25ba0 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
25bb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
25bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
25bd0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
25be0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
25bf0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48  ctor Behavior {H
25c00 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a  10280} <S30100>.
25c10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
25c20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
25c30 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
25c40 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
25c50 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
25c60 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
25c70 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
25c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
25c90 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64  ob()].  If the d
25ca0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
25cb0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
25cc0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
25cd0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
25ce0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
25cf0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
25d00 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
25d10 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
25d20 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
25d30 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54  d.  The.** SQLIT
25d40 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
25d50 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
25d60 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
25d70 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
25d80 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
25d90 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
25da0 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
25db0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
25dc0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
25dd0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
25de0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
25df0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
25e00 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
25e10 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
25e20 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
25e30 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
25e40 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
25e50 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
25e60 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
25e70 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
25e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25e90 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
25ea0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
25eb0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
25ec0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
25ed0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
25ee0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
25ef0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
25f00 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
25f10 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
25f20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30  Function {H16400
25f30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
25f40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25f50 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
25f60 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
25f70 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
25f80 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
25f90 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
25fa0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
25fb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
25fc0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
25fd0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
25fe0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
25ff0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
26000 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
26010 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
26020 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
26030 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
26040 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
26050 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
26060 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
26070 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
26080 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
26090 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
260a0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
260b0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
260c0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
260d0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
260e0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
260f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26100 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
26110 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
26120 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
26130 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
26140 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26150 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
26160 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
26170 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
26180 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
26190 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
261a0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
261b0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
261c0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
261d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
261e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
261f0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
26200 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
26210 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
26220 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26230 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
26240 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
26250 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
26260 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
26270 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
26280 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
26290 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
262a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
262b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
262c0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
262d0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
262e0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
262f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26300 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
26310 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
26320 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
26330 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
26340 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
26350 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26360 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
26370 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26380 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
26390 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
263a0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
263b0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
263c0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
263d0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
263e0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
263f0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
26400 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
26410 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26420 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
26430 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
26440 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
26450 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
26460 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65  ge.  SQLite inte
26470 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
26480 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
26490 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
264a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
264b0 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a  s UTF-8. SQLite.
264c0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
264d0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
264e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
264f0 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
26500 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
26510 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68  te order.  If th
26520 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
26530 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
26540 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
26550 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
26560 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
26570 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
26580 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
26590 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
265a0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
265b0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
265c0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
265d0 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70  * If the third p
265e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
265f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26600 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
26610 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
26620 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
26630 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
26640 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
26650 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
26660 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
26670 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
26680 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
26690 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  age..** The sqli
266a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
266b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
266c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
266d0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
266e0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
266f0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
26700 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
26710 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
26720 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
26730 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
26740 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
26750 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
26760 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
26770 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
26780 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
26790 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
267a0 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
267b0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
267c0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
267d0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
267e0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
267f0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
26800 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
26810 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
26820 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
26830 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74  R.  A subsequent
26840 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
26850 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
26860 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
26870 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
26880 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
26890 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
268a0 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  RROR..**.** The 
268b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
268c0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
268d0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
268e0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
268f0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
26900 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
26910 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
26920 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
26930 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26940 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
26950 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
26960 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
26970 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
26980 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
26990 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
269a0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   failed..**.** T
269b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
269c0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
269d0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
269e0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
269f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
26a00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
26a10 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
26a20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
26a30 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
26a40 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
26a50 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  t..** The sqlite
26a60 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
26a70 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
26a80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
26a90 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
26aa0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26ab0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
26ac0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
26ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
26ae0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
26af0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
26b00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26b10 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
26b20 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
26b30 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
26b40 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
26b50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26b60 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
26b70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26b80 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
26b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26ba0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
26bb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
26bc0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
26bd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
26be0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
26bf0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
26c00 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
26c10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26c20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26c30 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
26c40 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
26c50 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
26c60 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
26c70 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
26c80 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
26c90 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
26ca0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
26cb0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69  ctively..** SQLi
26cc0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
26cd0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
26ce0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
26cf0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
26d00 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
26d10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26d20 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
26d30 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
26d40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
26d50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26d60 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
26d70 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
26d80 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
26d90 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
26da0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
26db0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
26dc0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
26dd0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74  aracter..** If t
26de0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
26df0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
26e00 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
26e10 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
26e20 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
26e30 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
26e40 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
26e50 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
26e60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
26e70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
26e80 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
26e90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26ea0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
26eb0 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
26ec0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
26ed0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
26ee0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
26ef0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
26f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
26f10 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
26f20 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
26f30 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
26f40 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
26f50 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
26f60 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
26f70 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
26f80 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
26f90 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
26fa0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
26fb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
26fc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26fd0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
26fe0 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s or.** sqlite3_
26ff0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
27000 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
27010 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
27020 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
27030 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
27040 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
27050 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
27060 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
27070 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
27080 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20   the it or call 
27090 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65  a destructor whe
270a0 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
270b0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
270c0 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
270d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
270e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
270f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
27100 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
27110 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
27120 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
27130 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
27140 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
27150 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
27160 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
27170 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
27180 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
27190 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
271a0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
271b0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
271c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
271d0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
271e0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
271f0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
27200 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27210 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
27220 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
27230 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
27240 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27250 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
27260 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
27270 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
27280 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
27290 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
272a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
272b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
272c0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
272d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
272e0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
272f0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
27300 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
27310 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
27320 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
27330 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
27340 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20  hout harm..** A 
27350 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
27360 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27370 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
27380 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
27390 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
273a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
273b0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
273c0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
273d0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
273e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
273f0 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
27400 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
27410 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
27420 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
27430 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
27440 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
27450 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
27460 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
27470 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27480 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
27490 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
274a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
274b0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
274c0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
274d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  efined..**.** Re
274e0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
274f0 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d  H16403] [H16406]
27500 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31   [H16409] [H1641
27510 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36  2] [H16415] [H16
27520 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48  418] [H16421] [H
27530 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32  16424].** [H1642
27540 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36  7] [H16430] [H16
27550 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48  433] [H16436] [H
27560 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20  16439] [H16442] 
27570 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38  [H16445] [H16448
27580 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48  ].** [H16451] [H
27590 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20  16454] [H16457] 
275a0 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33  [H16460] [H16463
275b0 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ].*/.void sqlite
275c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
275d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
275e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
275f0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
27600 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27610 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
27620 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27630 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
27640 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27650 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
27660 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
27670 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
27680 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27690 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
276a0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
276b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
276c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
276d0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
276e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
276f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27700 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
27710 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
27720 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27730 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
27740 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27750 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
27760 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
27770 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27780 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
27790 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
277a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
277b0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
277c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
277d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
277e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
277f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
27800 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
27810 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
27820 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
27830 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
27840 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27850 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
27860 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
27870 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
27880 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
27890 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
278a0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
278b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
278c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
278d0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
278e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
278f0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
27900 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
27910 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
27920 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
27930 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
27940 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
27950 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
27960 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
27970 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27980 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
27990 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
279a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
279b0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
279c0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
279d0 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30  es {H16600} <S20
279e0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  300>.**.** These
279f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
27a00 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
27a10 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
27a20 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61  es to the.** [da
27a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27a40 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
27a50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
27a60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  nt..**.** The na
27a70 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
27a80 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
27a90 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
27aa0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
27ab0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
27ac0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
27ad0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
27ae0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
27af0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
27b00 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
27b10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27b20 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20  llation16(). In 
27b30 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65  all cases.** the
27b40 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20   name is passed 
27b50 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  as the second fu
27b60 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
27b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
27b80 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
27b90 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
27ba0 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
27bb0 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
27bc0 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51  UTF16LE], or [SQ
27bd0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
27be0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
27bf0 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
27c00 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
27c10 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
27c20 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
27c30 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
27c40 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
27c50 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
27c60 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
27c70 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74  -endian, respect
27c80 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68  ively. The.** th
27c90 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
27ca0 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
27cb0 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64  TE_UTF16] to ind
27cc0 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72  icate that the r
27cd0 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74  outine.** expect
27ce0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65  s pointers to be
27cf0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
27d00 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
27d10 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65  te order, or the
27d20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e  .** argument can
27d30 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
27d40 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68  6_ALIGNED] if th
27d50 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  e.** the routine
27d60 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
27d70 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
27d80 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
27d90 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e  .** of UTF-16 in
27da0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
27db0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20   order..**.** A 
27dc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
27dd0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
27de0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
27df0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
27e00 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
27e10 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
27e20 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
27e30 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
27e40 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
27e50 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
27e60 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
27e70 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
27e80 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61   Each time the a
27e90 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
27ea0 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
27eb0 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
27ec0 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
27ed0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
27ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
27ef0 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
27f00 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
27f10 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
27f20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27f30 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
27f40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
27f50 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  ()..**.** The re
27f60 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
27f70 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
27f80 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
27f90 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
27fa0 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
27fb0 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
27fc0 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
27fd0 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
27fe0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
27ff0 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
28000 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
28010 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
28020 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
28030 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
28040 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54  stered. {END}  T
28050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28060 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
28070 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
28080 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
28090 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
280a0 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
280b0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
280c0 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
280d0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
280e0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
280f0 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
28100 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
28110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28120 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28130 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
28140 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
28150 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
28160 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
28170 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
28180 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
28190 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
281a0 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
281b0 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
281c0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
281d0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
281e0 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
281f0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
28200 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
28210 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
28220 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
28230 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
28240 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
28250 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69  v2()..** Collati
28260 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
28270 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
28280 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
28290 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
282a0 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
282b0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
282c0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
282d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
282e0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
282f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
28300 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  lose()]..**.** S
28310 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
28320 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28330 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
28340 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
28350 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  eded16()]..**.**
28360 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
28370 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36  * [H16603] [H166
28380 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31  04] [H16606] [H1
28390 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b  6609] [H16612] [
283a0 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d  H16615] [H16618]
283b0 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31   [H16621].** [H1
283c0 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b  6624] [H16627] [
283d0 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H16630].*/.int s
283e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
283f0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
28400 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
28410 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
28420 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
28430 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
28440 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
28450 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
28460 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
28470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
28480 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
28490 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
284a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
284b0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
284c0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
284d0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
284e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
284f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28500 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
28510 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
28520 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
28530 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
28540 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
28550 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
28560 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
28570 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
28580 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
28590 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
285a0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
285b0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
285c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
285d0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
285e0 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20  lbacks {H16700} 
285f0 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
28600 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
28610 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
28620 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
28630 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
28640 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
28650 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
28660 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
28670 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
28680 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
28690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
286a0 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  on] to be called
286b0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
286c0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
286d0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
286e0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
286f0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
28700 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
28710 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28720 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
28730 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
28740 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
28750 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
28760 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
28770 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
28780 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
28790 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d   UTF-8. {H16703}
287a0 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
287b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
287c0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
287d0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
287e0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
287f0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
28800 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63  te order..** A c
28810 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
28820 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
28830 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
28840 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
28850 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
28860 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
28870 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
28880 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
28890 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
288a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
288b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
288c0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
288d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
288e0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
288f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
28900 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
28910 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
28920 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
28930 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
28940 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
28950 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
28960 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
28970 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
28980 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
28990 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
289a0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
289b0 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
289c0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
289d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
289e0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
289f0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
28a00 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
28a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
28a20 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
28a30 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
28a40 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
28a50 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
28a60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28a70 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
28a80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28a90 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
28aa0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28ab0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
28ac0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
28ad0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32  ents:.** [H16702
28ae0 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37  ] [H16704] [H167
28af0 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  06].*/.int sqlit
28b00 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28b10 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
28b20 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
28b30 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
28b40 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
28b50 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
28b60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
28b70 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
28b80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
28b90 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
28ba0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
28bb0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
28bc0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
28bd0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
28be0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
28bf0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
28c00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
28c10 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
28c20 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
28c30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
28c40 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
28c50 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
28c60 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
28c70 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
28c80 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
28c90 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
28ca0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
28cb0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
28cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28cd0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
28ce0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
28cf0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
28d00 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
28d10 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
28d20 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
28d30 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
28d40 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
28d50 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
28d60 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
28d70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
28d80 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
28d90 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
28da0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
28db0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
28dc0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
28dd0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
28de0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
28df0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
28e00 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
28e10 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
28e20 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
28e30 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
28e40 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28e50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28e60 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
28e70 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
28e80 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
28e90 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
28ea0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
28eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
28ec0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
28ed0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
28ee0 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31   {H10530} <S4041
28ef0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
28f00 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
28f10 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
28f20 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
28f30 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
28f40 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
28f50 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
28f60 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
28f70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
28f80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
28f90 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
28fa0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
28fb0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
28fc0 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
28fd0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
28fe0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
28ff0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
29000 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
29010 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
29020 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
29030 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
29040 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
29050 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
29060 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
29070 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
29080 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
29090 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
290a0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
290b0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
290c0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
290d0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
290e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
290f0 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  bject..**.** Req
29100 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35  uirements: [H105
29110 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a  33] [H10536].*/.
29120 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
29130 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
29140 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
29150 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
29160 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
29170 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32  les {H10310} <S2
29180 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  0000>.**.** If t
29190 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
291a0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
291b0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
291c0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
291d0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
291e0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
291f0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
29200 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
29210 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
29220 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
29230 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
29240 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
29250 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
29260 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
29270 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
29280 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
29290 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
292a0 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
292b0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
292c0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
292d0 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
292e0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
292f0 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
29300 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
29310 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
29320 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
29330 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
29340 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
29350 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29360 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
29370 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
29380 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
29390 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
293a0 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
293b0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
293c0 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
293d0 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
293e0 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
293f0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
29400 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
29410 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
29420 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
29430 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
29440 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
29450 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
29460 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  after..**.** The
29470 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
29480 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
29490 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
294a0 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
294b0 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
294c0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
294d0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
294e0 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74  3_malloc].  Furt
294f0 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
29500 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
29510 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
29520 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
29530 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
29540 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
29550 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
29560 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
29570 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
29580 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
29590 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
295a0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
295b0 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
295c0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
295d0 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
295e0 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
295f0 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
29600 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
29610 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
29620 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
29630 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
29640 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
29650 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
29660 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
29670 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
29680 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
29690 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
296a0 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
296b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
296c0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
296d0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
296e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
296f0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
29700 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39  ommit Mode {H129
29710 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20  30} <S60200>.** 
29720 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
29730 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
29740 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
29750 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
29760 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29770 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
29780 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
29790 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
297a0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
297b0 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
297c0 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
297d0 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d  tively.  Autocom
297e0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
297f0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75  y default..** Au
29800 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
29810 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
29820 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
29830 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
29840 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
29850 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
29860 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
29870 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
29880 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
29890 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
298a0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
298b0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
298c0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
298d0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
298e0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
298f0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
29900 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
29910 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
29920 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
29930 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
29940 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
29950 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
29960 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
29970 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
29980 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
29990 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
299a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
299b0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
299c0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
299d0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
299e0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
299f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
29a00 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
29a10 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
29a20 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
29a30 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
29a40 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
29a50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
29a60 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
29a70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
29a80 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
29a90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
29aa0 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48 31  ts: [H12931] [H1
29ab0 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b  2932] [H12933] [
29ac0 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H12934].*/.int s
29ad0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
29ae0 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
29af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29b00 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
29b10 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
29b20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29b30 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30  nt {H13120} <S60
29b40 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  600>.**.** The s
29b50 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
29b60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29b70 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
29b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
29b90 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
29ba0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29bb0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
29bc0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
29bd0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
29be0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
29bf0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
29c00 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
29c10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
29c20 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
29c30 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
29c40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
29c50 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
29c60 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
29c70 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
29c80 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
29c90 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
29ca0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
29cb0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
29cc0 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73  s: [H13123].*/.s
29cd0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
29ce0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
29cf0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29d00 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
29d10 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
29d20 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d statement {H13
29d30 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  140} <S60600>.**
29d40 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
29d50 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
29d60 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
29d70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29d80 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
29d90 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
29da0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
29db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
29dc0 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73  Db.  If pStmt is
29dd0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
29de0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
29df0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
29e00 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
29e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
29e20 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
29e30 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
29e40 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
29e50 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
29e60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
29e70 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
29e80 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
29e90 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
29ea0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
29eb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29ec0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
29ed0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
29ee0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
29ef0 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
29f00 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
29f10 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
29f20 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
29f30 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
29f40 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
29f50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ter..**.** Requi
29f60 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33  rements: [H13143
29f70 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31  ] [H13146] [H131
29f80 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a  49] [H13152].*/.
29f90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
29fa0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
29fb0 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
29fc0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
29fd0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29fe0 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
29ff0 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
2a000 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
2a010 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30  {H12950} <S60400
2a020 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a030 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2a040 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2a050 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2a060 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2a070 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2a080 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2a090 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2a0a0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e  ommitted]..** An
2a0b0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2a0c0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2a0d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
2a0e0 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
2a0f0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2a100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2a110 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2a120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c   The sqlite3_rol
2a130 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2a140 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2a150 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2a160 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2a170 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2a180 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2a190 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2a1a0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79  ed back]..** Any
2a1b0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2a1c0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2a1d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2a1e0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2a1f0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2a200 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2a210 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2a220 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
2a230 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
2a240 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
2a250 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ack..** If the c
2a260 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
2a270 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
2a280 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
2a290 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
2a2a0 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
2a2b0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
2a2c0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
2a2d0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
2a2e0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
2a2f0 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a  gistered, its.**
2a300 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
2a310 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
2a320 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
2a330 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2a340 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
2a350 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
2a360 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
2a370 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
2a380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2a390 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
2a3a0 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
2a3b0 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
2a3c0 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
2a3d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a3e0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
2a3f0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
2a400 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
2a410 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
2a420 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2a430 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
2a440 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
2a450 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
2a460 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2a470 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
2a480 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a490 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2a4a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2a4b0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2a4c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2a4d0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2a4e0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2a4f0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2a500 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69  raph..**.** Regi
2a510 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
2a520 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2a530 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2a540 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f  *.** When the co
2a550 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
2a560 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
2a570 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
2a580 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
2a590 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
2a5a0 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
2a5b0 6c 79 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d  ly.  If the comm
2a5c0 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
2a5d0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
2a5e0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
2a5f0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2a600 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
2a610 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68  * The rollback h
2a620 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
2a630 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
2a640 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
2a650 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
2a660 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
2a670 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
2a680 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
2a690 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
2a6a0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
2a6b0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
2a6c0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
2a6d0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
2a6e0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
2a6f0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
2a700 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
2a710 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
2a720 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
2a730 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
2a740 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
2a750 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
2a760 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68   to occur..** Th
2a770 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2a780 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2a790 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2a7a0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2a7b0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2a7c0 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2a7d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a7e0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2a7f0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
2a800 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2a810 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2a820 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f  saction is.** ro
2a830 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2a840 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  e a commit callb
2a850 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e  ack returned non
2a860 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e  -zero..** <todo>
2a870 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c   Check on this <
2a880 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65  /todo>.**.** See
2a890 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2a8a0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2a8b0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
2a8c0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2a8d0 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31  .** [H12951] [H1
2a8e0 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b  2952] [H12953] [
2a8f0 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d  H12954] [H12955]
2a900 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31  .** [H12961] [H1
2a910 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b  2962] [H12963] [
2a920 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20  H12964].*/.void 
2a930 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
2a940 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
2a950 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
2a960 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
2a970 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2a980 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
2a990 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
2a9a0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
2a9b0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
2a9c0 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
2a9d0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30  allbacks {H12970
2a9e0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
2a9f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
2aa00 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
2aa10 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2aa20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2aa30 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
2aa40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2aa50 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
2aa60 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
2aa70 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
2aa80 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2aa90 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
2aaa0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2aab0 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
2aac0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2aad0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2aae0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2aaf0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2ab00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ab10 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2ab20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
2ab30 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
2ab40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2ab50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
2ab60 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
2ab70 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
2ab80 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
2ab90 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
2aba0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2abb0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
2abc0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2abd0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2abe0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2abf0 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  k()..** The seco
2ac00 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2ac10 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2ac20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2ac30 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2ac40 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2ac50 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2ac60 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2ac70 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2ac80 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2ac90 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2aca0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
2acb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
2acc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2acd0 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
2ace0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
2acf0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
2ad00 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
2ad10 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
2ad20 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
2ad30 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2ad40 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2ad50 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e  f the row..** In
2ad60 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
2ad70 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
2ad80 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
2ad90 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
2ada0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
2adb0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2adc0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2add0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
2ade0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
2adf0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
2ae00 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
2ae10 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
2ae20 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ce)..**.** In th
2ae30 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2ae40 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
2ae50 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
2ae60 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2ae70 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
2ae80 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
2ae90 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
2aea0 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
2aeb0 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
2aec0 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f 72 20  E] clause.  Nor 
2aed0 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
2aee0 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
2aef0 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
2af00 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
2af10 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
2af20 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
2af30 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
2af40 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2af50 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
2af60 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
2af70 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2af80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
2af90 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
2afa0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2afb0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2afc0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2afd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2afe0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2aff0 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
2b000 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
2b010 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
2b020 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2b030 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
2b040 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
2b050 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
2b060 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
2b070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2b080 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
2b090 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
2b0a0 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
2b0b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b0c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2b0d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2b0e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2b0f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2b100 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2b110 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2b120 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2b130 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  raph..**.** If a
2b140 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
2b150 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
2b160 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70  egistered, its p
2b170 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  Arg value.** is 
2b180 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
2b190 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
2b1a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
2b1b0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2b1c0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2b1d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2b1e0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
2b1f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
2b200 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2b210 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b  s:.** [H12971] [
2b220 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d  H12973] [H12975]
2b230 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37   [H12977] [H1297
2b240 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32  9] [H12981] [H12
2b250 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f  983] [H12986].*/
2b260 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2b270 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2b280 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2b290 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2b2a0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2b2b0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2b2c0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2b2d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2b2e0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2b2f0 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2b300 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33  ger Cache {H1033
2b310 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b  0} <S30900>.** K
2b320 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
2b330 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20   cache} {shared 
2b340 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  cache mode}.**.*
2b350 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
2b360 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2b370 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2b380 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2b390 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2b3a0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2b3b0 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
2b3c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b3d0 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
2b3e0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
2b3f0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
2b400 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
2b410 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
2b420 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
2b430 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2b440 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  nt is false..**.
2b450 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
2b460 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2b470 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2b480 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2b490 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2b4a0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2b4b0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2b4c0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2b4d0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2b4e0 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2b4f0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2b500 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2b510 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2b520 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
2b530 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
2b540 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
2b550 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
2b560 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2b570 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2b580 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2b590 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
2b5a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2b5b0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
2b5c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b5d0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
2b5e0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
2b5f0 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
2b600 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
2b610 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
2b620 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
2b630 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
2b640 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
2b650 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
2b660 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
2b670 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
2b680 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2b690 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
2b6a0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
2b6b0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
2b6c0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
2b6d0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
2b6e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b6f0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2b700 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2b710 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2b720 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2b730 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2b740 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2b750 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2b760 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53  herwise..**.** S
2b770 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2b780 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2b790 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2b7a0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2b7b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2b7c0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2b7d0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2b7e0 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2b7f0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2b800 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2b810 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2b820 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2b830 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2b840 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71   Mode].**.** Req
2b850 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33  uirements: [H103
2b860 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31  31] [H10336] [H1
2b870 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a  0337] [H10339].*
2b880 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2b890 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2b8a0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2b8b0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2b8c0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2b8d0 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53  mory {H17340} <S
2b8e0 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2b8f0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2b900 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2b910 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2b920 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
2b930 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2b940 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2b950 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2b960 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
2b970 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
2b980 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
2b990 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
2b9a0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2b9b0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2b9c0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2b9d0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2b9e0 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2b9f0 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2ba00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2ba10 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2ba20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ba30 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2ba40 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2ba50 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2ba60 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2ba70 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2ba80 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2ba90 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37  s: [H17341] [H17
2baa0 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  342].*/.int sqli
2bab0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2bac0 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2bad0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2bae0 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2baf0 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c   Size {H17350} <
2bb00 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2bb10 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2bb20 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2bb30 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
2bb40 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
2bb50 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2bb60 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2bb70 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2bb80 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
2bb90 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2bba0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2bbb0 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2bbc0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2bbd0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2bbe0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2bbf0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2bc00 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2bc10 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2bc20 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2bc30 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2bc40 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2bc50 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rmed..**.** The 
2bc60 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
2bc70 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
2bc80 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2bc90 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2bca0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2bcb0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2bcc0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2bcd0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2bce0 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2bcf0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2bd00 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2bd10 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2bd20 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2bd30 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
2bd40 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
2bd50 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
2bd60 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
2bd70 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
2bd80 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
2bd90 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
2bda0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
2bdb0 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
2bdc0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
2bdd0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2bde0 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2bdf0 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2be00 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
2be10 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2be20 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2be30 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2be40 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2be50 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2be60 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2be70 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2be80 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2be90 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2bea0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
2beb0 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
2bec0 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
2bed0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
2bee0 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
2bef0 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
2bf00 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
2bf10 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
2bf20 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
2bf30 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
2bf40 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
2bf50 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
2bf60 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
2bf70 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
2bf80 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
2bf90 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
2bfa0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
2bfb0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
2bfc0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2bfd0 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
2bfe0 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
2bff0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
2c000 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2c010 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
2c020 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
2c030 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
2c040 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
2c050 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
2c060 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
2c070 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
2c080 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
2c090 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
2c0a0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
2c0b0 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
2c0c0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2c0d0 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48  :.** [H16351] [H
2c0e0 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20  16352] [H16353] 
2c0f0 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35  [H16354] [H16355
2c100 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f  ] [H16358].*/.vo
2c110 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
2c120 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
2c130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c140 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
2c150 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
2c160 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31  n Of A Table {H1
2c170 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a  2850} <S60300>.*
2c180 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2c190 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2c1a0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2c1b0 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2c1c0 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2c1d0 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2c1e0 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2c1f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c200 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2c210 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2c220 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2c230 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
2c240 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
2c250 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
2c260 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
2c270 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2c280 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
2c290 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
2c2a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
2c2b0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
2c2c0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2c2d0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
2c2e0 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
2c2f0 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
2c300 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
2c310 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
2c320 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
2c330 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
2c340 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
2c350 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
2c360 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
2c370 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
2c380 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
2c390 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2c3a0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
2c3b0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
2c3c0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
2c3d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
2c3e0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2c3f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2c400 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2c410 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2c420 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2c430 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2c440 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2c450 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2c460 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2c470 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2c480 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72  ** Metadata is r
2c490 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
2c4a0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
2c4b0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
2c4c0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
2c4d0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
2c4e0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2c4f0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
2c500 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
2c510 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
2c520 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2c530 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2c540 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2c550 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
2c560 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d..**.** <blockq
2c570 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2c580 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2c590 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
2c5a0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
2c5b0 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
2c5c0 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
2c5d0 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
2c5e0 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2c5f0 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
2c600 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
2c610 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2c620 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
2c630 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2c640 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
2c650 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
2c660 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2c670 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
2c680 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2c690 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
2c6a0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2c6b0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2c6c0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
2c6d0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
2c6e0 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
2c6f0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2c700 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2c710 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
2c720 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
2c730 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2c740 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
2c750 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
2c760 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
2c770 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
2c780 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
2c790 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
2c7a0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
2c7b0 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
2c7c0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
2c7d0 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
2c7e0 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
2c7f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2c800 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2c810 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2c820 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2c830 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2c840 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
2c850 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2c860 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
2c870 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
2c880 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
2c890 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2c8a0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
2c8b0 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
2c8c0 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
2c8d0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2c8e0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2c8f0 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
2c900 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
2c910 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
2c920 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2c930 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2c940 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2c950 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2c960 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2c970 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2c980 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2c990 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2c9a0 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2c9b0 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2c9c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2c9d0 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2c9e0 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2c9f0 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2ca00 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2ca10 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2ca20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  e>.**.** This fu
2ca30 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
2ca40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
2ca50 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
2ca60 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
2ca70 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
2ca80 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
2ca90 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
2caa0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
2cab0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
2cac0 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
2cad0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2cae0 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
2caf0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
2cb00 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
2cb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cb20 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
2cb30 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
2cb40 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
2cb50 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
2cb60 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2cb70 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2cb80 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2cb90 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2cba0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2cbb0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2cbc0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
2cbd0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2cbe0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
2cbf0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
2cc00 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2cc10 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
2cc20 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
2cc30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
2cc40 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
2cc50 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
2cc60 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
2cc70 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
2cc80 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
2cc90 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
2cca0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
2ccb0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
2ccc0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
2ccd0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
2cce0 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
2ccf0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
2cd00 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
2cd10 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
2cd20 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
2cd30 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
2cd40 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
2cd50 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
2cd60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2cd70 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
2cd80 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2cd90 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
2cda0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
2cdb0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2cdc0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2cdd0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
2cde0 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
2cdf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2ce00 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2ce10 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
2ce20 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
2ce30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ce40 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
2ce50 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32  ion {H12600} <S2
2ce60 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2ce70 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
2ce80 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
2ce90 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
2cea0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
2ceb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d  ..**.** {H12601}
2cec0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2ced0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2cee0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2cef0 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20   to load an.**  
2cf00 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65          SQLite e
2cf10 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2cf20 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2cf30 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
2cf40 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65  .** {H12602} The
2cf50 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2cf60 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zProc..**.** {H1
2cf70 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
2cf80 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
2cf90 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
2cfa0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
2cfb0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
2cfc0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
2cfd0 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
2cfe0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d  ..**.** {H12604}
2cff0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2d000 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2d010 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2d020 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2d030 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2d040 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2d050 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2d060 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2d070 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  ng..**.** {H1260
2d080 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  5} If an error o
2d090 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
2d0a0 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
2d0b0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2d0c0 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f    [sqlite3_load_
2d0d0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
2d0e0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
2d0f0 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  empt to.**      
2d100 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d      fill *pzErrM
2d110 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
2d120 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
2d130 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  d in memory.**  
2d140 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64          obtained
2d150 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2d160 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20  alloc()]. {END} 
2d170 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
2d180 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2d190 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68    should free th
2d1a0 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2d1b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2d1c0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ee()]..**.** {H1
2d1d0 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20  2606} Extension 
2d1e0 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
2d1f0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
2d200 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d210 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2d220 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
2d230 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
2d240 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20  s API,.**       
2d250 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20     otherwise an 
2d260 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2d270 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
2d280 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2d290 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
2d2a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
2d2b0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
2d2c0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
2d2d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d2e0 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2d2f0 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
2d300 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
2d310 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
2d320 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
2d330 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2d340 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
2d350 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
2d360 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
2d370 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
2d380 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
2d390 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
2d3a0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
2d3b0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
2d3c0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2d3d0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
2d3e0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48  nsion Loading {H
2d3f0 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12620} <S20500>.
2d400 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20  **.** So as not 
2d410 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
2d420 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
2d430 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2d440 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
2d450 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
2d460 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
2d470 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
2d480 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
2d490 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
2d4a0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
2d4b0 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
2d4c0 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
2d4d0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
2d4e0 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
2d4f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
2d500 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2d510 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
2d520 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65   off..**.** Exte
2d530 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2d540 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2d550 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
2d560 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31  3..**.** {H12621
2d570 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
2d580 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2d590 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
2d5a0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
2d5b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2d5c0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2d5d0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
2d5e0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
2d5f0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20  ==0 to turn.**  
2d600 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20          it back 
2d610 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a  off again..**.**
2d620 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73   {H12622} Extens
2d630 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
2d640 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ff by default..*
2d650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2d660 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
2d670 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
2d680 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
2d690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
2d6a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
2d6b0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b   An Extensions {
2d6c0 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e  H12640} <S20500>
2d6d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2d6e0 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
2d6f0 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
2d700 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
2d710 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
2d720 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
2d730 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
2d740 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
2d750 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
2d760 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73  all new [databas
2d770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20  e connections]. 
2d780 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
2d790 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
2d7a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d7b0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e   extension in an
2d7c0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a   array that is.*
2d7d0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2d7e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2d7f0 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20  )].  If you run 
2d800 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68  a memory leak ch
2d810 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72  ecker.** on your
2d820 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
2d830 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
2d840 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61  ecause of this a
2d850 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  rray, invoke.** 
2d860 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
2d870 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
2d880 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f   prior to shutdo
2d890 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
2d8a0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
2d8b0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
2d8c0 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
2d8d0 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
2d8e0 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
2d8f0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2d900 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
2d910 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
2d920 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d930 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
2d940 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e    is opened usin
2d950 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
2d960 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2d970 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2d980 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2d990 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2d9a0 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69  * {H12642} Dupli
2d9b0 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
2d9c0 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
2d9d0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
2d9e0 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tine.**         
2d9f0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
2da00 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
2da10 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
2da20 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ess..**.** {H126
2da30 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
2da40 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65   stores a pointe
2da50 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69  r to the extensi
2da60 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a  on in an array.*
2da70 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
2da80 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2da90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2daa0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2dab0 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
2dac0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2dad0 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2dae0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2daf0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2db00 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2db10 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2db20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2db30 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2db40 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2db50 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30  {H12660} <S20500
2db60 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2db70 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2db80 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2db90 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2dba0 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2dbb0 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f  . {END}  It undo
2dbc0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
2dbd0 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73   all prior.** [s
2dbe0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2dbf0 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a  nsion()] calls..
2dc00 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54  **.** {H12661} T
2dc10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
2dc20 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f  ables all previo
2dc30 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a  usly registered.
2dc40 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2dc50 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2dc60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d  ..**.** {H12662}
2dc70 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2dc80 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
2dc90 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
2dca0 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2dcb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2dcc0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2dcd0 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a  n(void);../*.***
2dce0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
2dcf0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
2dd00 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
2dd10 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
2dd20 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
2dd30 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
2dd40 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2dd50 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
2dd60 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
2dd70 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
2dd80 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
2dd90 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
2dda0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
2ddb0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
2ddc0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
2ddd0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
2dde0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
2ddf0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
2de00 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
2de10 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2de20 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
2de30 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
2de40 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
2de50 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
2de60 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
2de70 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
2de80 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
2de90 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
2dea0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
2deb0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
2dec0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
2ded0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2dee0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
2def0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2df00 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2df10 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
2df20 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
2df30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2df40 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
2df50 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
2df60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2df70 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
2df80 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
2df90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2dfa0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
2dfb0 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32  ect {H18000} <S2
2dfc0 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
2dfd0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
2dfe0 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
2dff0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45   module}.** EXPE
2e000 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2e010 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
2e020 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
2e030 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  a a "virtual tab
2e040 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
2e050 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
2e060 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
2e070 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2e080 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
2e090 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
2e0a0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
2e0b0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
2e0c0 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c  .**.** A virtual
2e0d0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
2e0e0 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
2e0f0 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
2e100 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
2e110 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
2e120 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
2e130 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2e140 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
2e150 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2e160 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
2e170 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
2e180 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  le_v2()]..** The
2e190 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65   registration re
2e1a0 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69  mains valid unti
2e1b0 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64  l it is replaced
2e1c0 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a   by a different.
2e1d0 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74  ** module or unt
2e1e0 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  il the [database
2e1f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f   connection] clo
2e200 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  ses.  The conten
2e210 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72  t.** of this str
2e220 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
2e230 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20  change while it 
2e240 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
2e250 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61  th.** any databa
2e260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2e270 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2e280 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
2e290 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
2e2a0 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
2e2b0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2e2c0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e2d0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2e2e0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2e2f0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2e300 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2e310 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2e320 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
2e330 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
2e340 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2e350 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2e360 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2e370 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2e380 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2e390 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2e3a0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2e3b0 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
2e3c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2e3d0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
2e3e0 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
2e3f0 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
2e400 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2e410 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
2e420 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
2e430 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2e440 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
2e450 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
2e460 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2e470 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
2e480 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
2e490 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2e4a0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2e4b0 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
2e4c0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
2e4d0 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
2e4e0 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
2e4f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2e500 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
2e510 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
2e520 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
2e530 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2e540 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
2e550 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
2e560 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2e570 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
2e580 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2e590 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2e5a0 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
2e5b0 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
2e5c0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2e5d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
2e5e0 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
2e5f0 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
2e600 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
2e610 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
2e620 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
2e630 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
2e640 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2e650 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2e660 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
2e670 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2e680 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
2e690 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2e6a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
2e6b0 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
2e6c0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2e6d0 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
2e6e0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2e6f0 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
2e700 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2e710 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
2e720 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2e730 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
2e740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2e750 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2e760 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
2e770 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
2e780 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
2e790 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
2e7a0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
2e7b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
2e7c0 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
2e7d0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
2e7e0 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
2e7f0 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30  ormation {H18100
2e800 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
2e810 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2e820 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58  index_info.** EX
2e830 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2e840 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
2e850 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
2e860 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
2e870 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
2e880 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
2e890 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
2e8a0 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
2e8b0 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
2e8c0 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
2e8d0 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
2e8e0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
2e8f0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
2e900 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
2e910 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
2e920 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
2e930 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
2e940 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
2e950 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
2e960 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
2e970 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
2e980 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  *.** The aConstr
2e990 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
2e9a0 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
2e9b0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
2e9c0 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a   the form:.**.**
2e9d0 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20   <pre>column OP 
2e9e0 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  expr</pre>.**.**
2e9f0 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
2ea00 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
2ea10 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68  ;, or &gt;=.  Th
2ea20 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
2ea30 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72  rator is.** stor
2ea40 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ed in aConstrain
2ea50 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
2ea60 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2ea70 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
2ea80 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
2ea90 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
2eaa0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
2eab0 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
2eac0 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
2ead0 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
2eae0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
2eaf0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
2eb00 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
2eb10 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
2eb20 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
2eb30 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
2eb40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2eb50 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
2eb60 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
2eb70 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
2eb80 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
2eb90 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
2eba0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
2ebb0 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
2ebc0 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
2ebd0 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
2ebe0 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
2ebf0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
2ec00 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
2ec10 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
2ec20 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
2ec30 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
2ec40 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
2ec50 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
2ec60 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
2ec70 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
2ec80 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
2ec90 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
2eca0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2ecb0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2ecc0 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
2ecd0 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
2ece0 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
2ecf0 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
2ed00 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
2ed10 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
2ed20 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
2ed30 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
2ed40 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
2ed50 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
2ed60 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
2ed70 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
2ed80 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
2ed90 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e  lter.  If argvIn
2eda0 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
2edb0 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
2edc0 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
2edd0 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
2ede0 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
2edf0 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
2ee00 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
2ee10 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
2ee20 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74    If aConstraint
2ee30 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
2ee40 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
2ee50 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
2ee60 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
2ee70 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
2ee80 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
2ee90 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
2eea0 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
2eeb0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
2eec0 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
2eed0 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
2eee0 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
2eef0 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
2ef00 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
2ef10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2ef20 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
2ef30 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
2ef40 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e  nd only iff.** n
2ef50 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
2ef60 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  is true..**.** T
2ef70 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
2ef80 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
2ef90 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
2efa0 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
2efb0 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
2efc0 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
2efd0 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
2efe0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
2eff0 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
2f000 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
2f010 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
2f020 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74  *.** The estimat
2f030 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
2f040 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
2f050 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
2f060 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
2f070 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
2f080 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
2f090 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
2f0a0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
2f0b0 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
2f0c0 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
2f0d0 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
2f0e0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
2f0f0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
2f100 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
2f110 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
2f120 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2f130 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
2f140 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
2f150 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
2f160 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
2f170 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
2f180 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
2f190 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
2f1a0 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
2f1b0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
2f1c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
2f1d0 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
2f1e0 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
2f1f0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
2f200 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
2f210 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
2f220 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
2f230 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
2f240 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
2f250 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
2f260 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
2f270 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
2f280 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
2f290 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
2f2a0 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
2f2b0 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
2f2c0 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
2f2d0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
2f2e0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
2f2f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
2f300 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
2f310 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
2f320 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
2f330 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
2f340 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
2f350 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
2f360 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
2f370 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
2f380 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
2f390 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
2f3a0 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
2f3b0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
2f3c0 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
2f3d0 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
2f3e0 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
2f3f0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
2f400 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
2f410 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
2f420 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
2f430 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
2f440 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
2f450 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
2f460 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
2f470 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
2f480 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
2f490 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
2f4a0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
2f4b0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
2f4c0 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
2f4d0 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
2f4e0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
2f4f0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
2f500 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
2f510 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
2f520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f530 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
2f540 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
2f550 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
2f560 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
2f570 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
2f580 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
2f590 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
2f5a0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
2f5b0 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
2f5c0 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
2f5d0 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
2f5e0 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
2f5f0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
2f600 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
2f610 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
2f620 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
2f630 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
2f640 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
2f650 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
2f660 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
2f670 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
2f680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f690 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
2f6a0 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
2f6b0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
2f6c0 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
2f6d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f6e0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
2f6f0 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
2f700 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
2f710 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
2f720 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
2f730 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2f740 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
2f750 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2f760 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
2f770 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
2f780 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
2f790 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
2f7a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31  plementation {H1
2f7b0 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8200} <S20400>.*
2f7c0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
2f7d0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2f7e0 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
2f7f0 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72  ister a new [vir
2f800 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2f810 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75  e] name..** Modu
2f820 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
2f830 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
2f840 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61  re.** creating a
2f850 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
2f860 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d  ble] using the m
2f870 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
2f880 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65   using a.** pree
2f890 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c  xisting [virtual
2f8a0 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20   table] for the 
2f8b0 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  module..**.** Th
2f8c0 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
2f8d0 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
2f8e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f8f0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
2f900 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
2f910 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  st parameter.  T
2f920 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
2f930 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62  odule is given b
2f940 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64  y the .** second
2f950 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
2f960 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f970 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2f980 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
2f990 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76  tation of the [v
2f9a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2f9b0 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72  ule].   The four
2f9c0 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
2f9d0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2f9e0 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
2f9f0 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
2fa00 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e  ed through.** in
2fa10 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d  to the [xCreate]
2fa20 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
2fa30 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76  methods of the v
2fa40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2fa50 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65  ule.** when a ne
2fa60 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
2fa70 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61  is be being crea
2fa80 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c  ted or reinitial
2fa90 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ized..**.** This
2faa0 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65   interface has e
2fab0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
2fac0 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e  effect as callin
2fad0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
2fae0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
2faf0 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c  ] with a NULL cl
2fb00 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75  ient data destru
2fb10 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ctor..*/.SQLITE_
2fb20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
2fb30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fb40 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
2fb50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2fb60 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
2fb70 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
2fb80 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
2fb90 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
2fba0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
2fbb0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
2fbc0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
2fbd0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
2fbe0 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f  e *p,   /* Metho
2fbf0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
2fc00 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c  e */.  void *pCl
2fc10 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20  ientData        
2fc20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
2fc30 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
2fc40 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
2fc50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
2fc60 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
2fc70 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
2fc80 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53  tion {H18210} <S
2fc90 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20400>.** EXPERI
2fca0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69  MENTAL.**.** Thi
2fcb0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
2fcc0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73  ntical to the [s
2fcd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2fce0 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a  dule()] method,.
2fcf0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
2fd00 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70  t has an extra p
2fd10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63  arameter to spec
2fd20 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75  ify .** a destru
2fd30 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ctor function fo
2fd40 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74  r the client dat
2fd50 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69  a pointer.  SQLi
2fd60 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
2fd70 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2fd80 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
2fd90 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
2fda0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
2fdb0 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
2fdc0 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
2fdd0 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54  nter.  .*/.SQLIT
2fde0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
2fdf0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2fe00 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
2fe10 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2fe20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
2fe30 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
2fe40 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
2fe50 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
2fe60 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
2fe70 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
2fe80 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
2fe90 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
2fea0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
2feb0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
2fec0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
2fed0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
2fee0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
2fef0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
2ff00 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
2ff10 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2ff20 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
2ff30 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
2ff40 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
2ff50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ff60 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
2ff70 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48  stance Object {H
2ff80 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18010} <S20400>.
2ff90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
2ffa0 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50  ite3_vtab.** EXP
2ffb0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2ffc0 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
2ffd0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
2ffe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
2fff0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
30000 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
30010 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
30020 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
30030 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f  ar instance.** o
30040 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
30050 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62  able].  Each sub
30060 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65  class will.** be
30070 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65   tailored to the
30080 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
30090 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d  of the module im
300a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
300b0 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20   The purpose of 
300c0 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  this superclass 
300d0 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72  is to define cer
300e0 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74  tain fields that
300f0 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74   are.** common t
30100 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70  o all module imp
30110 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
30120 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
30130 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
30140 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
30150 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
30160 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
30170 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
30180 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
30190 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
301a0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
301b0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
301c0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
301d0 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
301e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
301f0 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
30200 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
30210 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
30220 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68  rrMsg.  After th
30230 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
30240 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
30250 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
30260 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
30270 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
30280 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
30290 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
302a0 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
302b0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
302c0 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
302d0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
302e0 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
302f0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
30300 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
30310 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
30320 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
30330 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
30340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30350 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74       /* Used int
30360 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61  ernally */.  cha
30370 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
30380 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30390 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
303a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
303b0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
303c0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
303d0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
303e0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
303f0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
30400 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
30410 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
30420 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
30430 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32  ct  {H18020} <S2
30440 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
30450 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
30460 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
30470 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
30480 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
30490 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
304a0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
304b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
304c0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
304d0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
304e0 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
304f0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
30500 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
30510 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
30520 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
30530 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
30540 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
30550 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
30560 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
30570 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
30580 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
30590 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
305a0 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
305b0 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
305c0 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
305d0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
305e0 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
305f0 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20  ethod.  Cussors 
30600 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
30610 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
30620 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
30630 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
30640 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
30650 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
30660 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
30670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
30680 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
30690 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
306a0 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
306b0 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
306c0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
306d0 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
306e0 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
306f0 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
30700 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
30710 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
30720 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
30730 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
30740 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30750 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
30760 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
30770 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
30780 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
30790 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
307a0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
307b0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
307c0 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
307d0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
307e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
307f0 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
30800 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
30810 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30  al Table {H18280
30820 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
30830 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
30840 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61   The [xCreate] a
30850 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
30860 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76  thods of a.** [v
30870 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30880 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69  ule] call this i
30890 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64  nterface.** to d
308a0 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
308b0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
308c0 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
308d0 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
308e0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
308f0 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
30900 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
30910 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
30920 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
30930 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
30940 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
30950 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30960 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
30970 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
30980 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30  ual Table {H1830
30990 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45  0} <S20400>.** E
309a0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
309b0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
309c0 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
309d0 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
309e0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
309f0 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
30a00 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
30a10 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
30a20 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
30a30 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
30a40 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
30a50 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
30a60 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
30a70 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
30a80 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  e overloaded..**
30a90 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b  .** This API mak
30aa0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
30ab0 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
30ac0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
30ad0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
30ae0 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
30af0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
30b00 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
30b10 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
30b20 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
30b30 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
30b40 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
30b50 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  eated.  The impl
30b60 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
30b70 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
30b80 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
30b90 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
30ba0 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
30bb0 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
30bc0 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
30bd0 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
30be0 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
30bf0 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
30c00 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64  o be a placehold
30c10 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  er function that
30c20 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64   can be overload
30c30 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74  ed.** by a [virt
30c40 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53  ual table]..*/.S
30c50 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
30c60 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  AL int sqlite3_o
30c70 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
30c80 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
30c90 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
30ca0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
30cb0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
30cc0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
30cd0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
30ce0 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
30cf0 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
30d00 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
30d10 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
30d20 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
30d30 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
30d40 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
30d50 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
30d60 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
30d70 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
30d80 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
30d90 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
30da0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
30db0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
30dc0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
30dd0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
30de0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
30df0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
30e00 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
30e10 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
30e20 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
30e30 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
30e40 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
30e50 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a  this comment..**
30e60 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
30e70 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
30e80 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
30e90 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
30ea0 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ******.*/../*.**
30eb0 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
30ec0 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
30ed0 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33  LOB {H17800} <S3
30ee0 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0230>.** KEYWORD
30ef0 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d  S: {BLOB handle}
30f00 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a   {BLOB handles}.
30f10 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
30f20 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
30f30 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
30f40 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63  pen BLOB on whic
30f50 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  h.** [sqlite3_bl
30f60 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
30f70 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
30f80 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
30f90 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20  ..** Objects of 
30fa0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
30fb0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
30fc0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
30fd0 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
30fe0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
30ff0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68  _close()]..** Th
31000 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
31010 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
31020 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
31030 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
31040 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
31050 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d  read or write sm
31060 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20  all subsections 
31070 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20  of the BLOB..** 
31080 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
31090 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
310a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
310b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
310c0 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  B in bytes..*/.t
310d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
310e0 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
310f0 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
31100 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
31110 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
31120 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31  ental I/O {H1781
31130 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
31140 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
31150 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20  s opens a [BLOB 
31160 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d  handle | handle]
31170 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63   to the BLOB loc
31180 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
31190 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
311a0 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
311b0 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
311c0 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
311d0 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42  ords, the same B
311e0 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62  LOB that would b
311f0 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
31200 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
31210 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
31220 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
31230 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d   WHERE [rowid] =
31240 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
31250 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
31260 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
31270 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
31280 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   then the BLOB i
31290 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
312a0 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61  d.** and write a
312b0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20  ccess. If it is 
312c0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
312d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
312e0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  d access..**.** 
312f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
31300 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
31310 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
31320 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
31330 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
31340 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
31350 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
31360 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
31370 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77  ** is assigned w
31380 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
31390 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73   is connected us
313a0 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a  ing [ATTACH]..**
313b0 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   For the main da
313c0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
313d0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
313e0 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72  s "main"..** For
313f0 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
31400 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
31410 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
31420 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
31430 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
31440 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
31450 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
31460 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
31470 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
31480 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
31490 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
314a0 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65  nd *ppBlob is se
314b0 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c  t.** to be a nul
314c0 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  l pointer..** Th
314d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
314e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
314f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
31500 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
31510 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
31520 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
31530 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
31540 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
31550 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
31560 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74  nctions.  Note t
31570 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
31580 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
31590 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
315a0 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
315b0 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
315c0 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
315d0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
315e0 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
315f0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
31600 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
31610 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
31620 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
31630 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
31640 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
31650 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
31660 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
31670 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
31680 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
31690 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
316a0 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
316b0 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
316c0 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
316d0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
316e0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
316f0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
31700 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
31710 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
31720 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
31730 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a  dle is open on..
31740 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** Calls to [sql
31750 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
31760 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
31770 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
31780 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
31790 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
317a0 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
317b0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
317c0 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73  ORT]..** Changes
317d0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20   written into a 
317e0 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68  BLOB prior to th
317f0 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20  e BLOB expiring 
31800 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62  are not.** rollb
31810 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72  ack by the expir
31820 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f  ation of the BLO
31830 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73  B.  Such changes
31840 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
31850 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68  .** commit if th
31860 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  e transaction co
31870 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
31880 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65  etion..**.** Use
31890 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
318a0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
318b0 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69  rface to determi
318c0 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ne the size of.*
318d0 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f  * the opened blo
318e0 62 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  b.  The size of 
318f0 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62  a blob may not b
31900 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69  e changed by thi
31910 73 0a 2a 2a 20 75 6e 64 65 72 66 61 63 65 2e 20  s.** underface. 
31920 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45   Use the [UPDATE
31930 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f  ] SQL command to
31940 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
31950 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a   of a.** blob..*
31960 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
31970 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
31980 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31990 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
319a0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
319b0 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
319c0 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
319d0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
319e0 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
319f0 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
31a00 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
31a10 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
31a20 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
31a30 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
31a40 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
31a50 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
31a60 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
31a70 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
31a80 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
31a90 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
31aa0 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
31ab0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
31ac0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  ob_close()]..**.
31ad0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
31ae0 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31  .** [H17813] [H1
31af0 37 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b  7814] [H17816] [
31b00 48 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d  H17819] [H17821]
31b10 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74   [H17824].*/.int
31b20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
31b30 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
31b40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
31b50 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
31b60 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
31b70 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
31b80 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
31b90 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
31ba0 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
31bb0 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
31bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
31bd0 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
31be0 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30  le {H17830} <S30
31bf0 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  230>.**.** Close
31c00 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  s an open [BLOB 
31c10 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43  handle]..**.** C
31c20 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
31c30 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
31c40 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
31c50 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
31c60 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
31c70 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
31c80 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
31c90 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
31ca0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
31cb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
31cc0 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
31cd0 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72  e]..** If any wr
31ce0 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74  ites were made t
31cf0 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79  o the BLOB, they
31d00 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69   might be held i
31d10 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c  n cache.** until
31d20 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61   the close opera
31d30 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c  tion if they wil
31d40 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f  l fit..**.** Clo
31d50 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66  sing the BLOB of
31d60 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63  ten forces the c
31d70 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f  hanges.** out to
31d80 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20   disk and so if 
31d90 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f  any I/O errors o
31da0 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20  ccur, they will 
31db0 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20  likely occur.** 
31dc0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
31dd0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   the BLOB is clo
31de0 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73  sed.  Any errors
31df0 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
31e00 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
31e10 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
31e20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
31e30 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
31e40 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
31e50 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
31e60 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
31e70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
31e80 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
31e90 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
31ea0 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  ll closed..**.**
31eb0 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
31ec0 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c  utine with a nul
31ed0 6c 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68  l pointer (which
31ee0 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74   as would be ret
31ef0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c  urned.** by fail
31f00 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ed call to [sqli
31f10 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
31f20 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
31f30 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  no-op..**.** Req
31f40 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
31f50 31 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20  17833] [H17836] 
31f60 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20  [H17839].*/.int 
31f70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
31f80 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  se(sqlite3_blob 
31f90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31fa0 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20  REF: Return The 
31fb0 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20  Size Of An Open 
31fc0 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53  BLOB {H17840} <S
31fd0 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  30230>.**.** Ret
31fe0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e  urns the size in
31ff0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
32000 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  OB accessible vi
32010 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73  a the .** succes
32020 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42  sfully opened [B
32030 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69  LOB handle] in i
32040 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
32050 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d  .  The.** increm
32060 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72  ental blob I/O r
32070 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79  outines can only
32080 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69   read or overwri
32090 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a  ting existing.**
320a0 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74   blob content; t
320b0 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67  hey cannot chang
320c0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
320d0 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  blob..**.** This
320e0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
320f0 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
32100 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
32110 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
32120 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
32130 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
32140 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
32150 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
32160 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
32170 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
32180 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
32190 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
321a0 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
321b0 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
321c0 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
321d0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
321e0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
321f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
32200 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
32210 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74   [H17843].*/.int
32220 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79   sqlite3_blob_by
32230 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  tes(sqlite3_blob
32240 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
32250 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20  3REF: Read Data 
32260 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72  From A BLOB Incr
32270 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35  ementally {H1785
32280 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
32290 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
322a0 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  is used to read 
322b0 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65  data from an ope
322c0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
322d0 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  into a.** caller
322e0 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
322f0 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74  . N bytes of dat
32300 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  a are copied int
32310 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72  o buffer Z.** fr
32320 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  om the open BLOB
32330 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
32340 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
32350 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f  .** If offset iO
32360 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
32370 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
32380 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
32390 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
323a0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
323b0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
323c0 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72  s read.  If N or
323d0 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
323e0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
323f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
32400 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
32410 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
32420 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68  * The size of th
32430 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
32440 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
32450 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
32460 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
32470 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
32480 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
32490 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
324a0 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65  e..**.** An atte
324b0 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d  mpt to read from
324c0 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
324d0 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
324e0 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
324f0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
32500 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f  _ABORT]..**.** O
32510 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
32520 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
32530 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
32540 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
32550 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
32560 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
32570 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
32580 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
32590 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
325a0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
325b0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
325c0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
325d0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
325e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
325f0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
32600 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
32610 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
32620 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
32630 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
32640 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
32650 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
32660 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
32670 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
32680 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
32690 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
326a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
326b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
326c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
326d0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
326e0 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48  853] [H17856] [H
326f0 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20  17859] [H17862] 
32700 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35  [H17863] [H17865
32710 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e  ] [H17868].*/.in
32720 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
32730 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
32740 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
32750 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
32760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32770 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
32780 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
32790 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d  entally {H17870}
327a0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
327b0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
327c0 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64   used to write d
327d0 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e  ata into an open
327e0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
327f0 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  rom a.** caller-
32800 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
32810 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
32820 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
32830 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
32840 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
32850 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
32860 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
32870 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42  .**.** If the [B
32880 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
32890 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
328a0 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
328b0 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
328c0 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
328d0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
328e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
328f0 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
32900 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
32910 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
32920 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
32930 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
32940 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20  may only modify 
32950 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
32960 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a  the BLOB; it is.
32970 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
32980 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  to increase the 
32990 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75  size of a BLOB u
329a0 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a  sing this API..*
329b0 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
329c0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
329d0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
329e0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
329f0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
32a00 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
32a10 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
32a20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69  written.  If N i
32a30 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
32a40 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ero [SQLITE_ERRO
32a50 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
32a60 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
32a70 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69  itten..** The si
32a80 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28  ze of the BLOB (
32a90 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
32aa0 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
32ab0 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
32ac0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
32ad0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
32ae0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
32af0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
32b00 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77   An attempt to w
32b10 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72  rite to an expir
32b20 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
32b30 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
32b40 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
32b50 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20  [SQLITE_ABORT]. 
32b60 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42   Writes to the B
32b70 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65  LOB that occurre
32b80 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  d.** before the 
32b90 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78  [BLOB handle] ex
32ba0 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f  pired are not ro
32bb0 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
32bc0 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  .** expiration o
32bd0 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68  f the handle, th
32be0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
32bf0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67  hose changes mig
32c00 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  ht.** have been 
32c10 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
32c20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
32c30 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c  t expired the BL
32c40 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20  OB handle.** or 
32c50 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e  by other indepen
32c60 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e  dent statements.
32c70 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
32c80 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
32c90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
32ca0 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72  erwise, an  [err
32cb0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
32cc0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
32cd0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
32ce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
32cf0 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
32d00 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
32d10 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
32d20 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
32d30 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
32d40 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
32d50 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
32d60 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
32d70 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
32d80 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
32d90 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
32da0 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
32db0 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
32dc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
32dd0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
32de0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
32df0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
32e00 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
32e10 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
32e20 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a  lob_read()]..**.
32e30 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
32e40 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31  .** [H17873] [H1
32e50 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b  7874] [H17875] [
32e60 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d  H17876] [H17877]
32e70 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38   [H17879] [H1788
32e80 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b  2] [H17885].** [
32e90 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73  H17888].*/.int s
32ea0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
32eb0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
32ec0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c  , const void *z,
32ed0 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
32ee0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
32ef0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46  I3REF: Virtual F
32f00 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
32f10 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30  ts {H11200} <S20
32f20 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  100>.**.** A vir
32f30 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
32f40 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
32f50 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
32f60 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
32f70 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
32f80 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
32f90 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
32fa0 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
32fb0 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f  SQLite builds co
32fc0 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
32fd0 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
32fe0 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
32ff0 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
33000 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
33010 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
33020 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
33030 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
33040 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
33050 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
33060 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
33070 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
33080 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66  * The sqlite3_vf
33090 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61  s_find() interfa
330a0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
330b0 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69  nter to a VFS gi
330c0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a  ven its name..**
330d0 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20   Names are case 
330e0 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61  sensitive..** Na
330f0 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
33100 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
33110 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65  rings..** If the
33120 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20  re is no match, 
33130 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
33140 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
33150 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
33160 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
33170 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
33180 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56  ned..**.** New V
33190 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65  FSes are registe
331a0 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33  red with sqlite3
331b0 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e  _vfs_register().
331c0 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53  .** Each new VFS
331d0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66   becomes the def
331e0 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20  ault VFS if the 
331f0 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73  makeDflt flag is
33200 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d   set..** The sam
33210 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67  e VFS can be reg
33220 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
33230 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69   times without i
33240 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b  njury..** To mak
33250 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46  e an existing VF
33260 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75  S into the defau
33270 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72  lt VFS, register
33280 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74   it again.** wit
33290 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  h the makeDflt f
332a0 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f  lag set.  If two
332b0 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73   different VFSes
332c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d   with the.** sam
332d0 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73  e name are regis
332e0 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76  tered, the behav
332f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
33300 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69  .  If a.** VFS i
33310 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
33320 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73  h a name that is
33330 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
33340 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65  y string,.** the
33350 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
33360 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
33370 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20  ** Unregister a 
33380 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c  VFS with the sql
33390 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
333a0 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  ter() interface.
333b0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75  .** If the defau
333c0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
333d0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
333e0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
333f0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
33400 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
33410 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
33420 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
33430 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
33440 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32  * [H11203] [H112
33450 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31  06] [H11209] [H1
33460 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b  1212] [H11215] [
33470 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74  H11218].*/.sqlit
33480 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f  e3_vfs *sqlite3_
33490 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63  vfs_find(const c
334a0 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a  har *zVfsName);.
334b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
334c0 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
334d0 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44  _vfs*, int makeD
334e0 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  flt);.int sqlite
334f0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
33500 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a  (sqlite3_vfs*);.
33510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33520 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30   Mutexes {H17000
33530 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
33540 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
33550 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
33560 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a  ines for thread.
33570 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69  ** synchronizati
33580 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20  on. Though they 
33590 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
335a0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
335b0 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
335c0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
335d0 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
335e0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
335f0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
33600 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
33610 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
33620 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
33630 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
33640 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68  tations.** of th
33650 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ese mutex routin
33660 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69  es.  An appropri
33670 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ate implementati
33680 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65  on.** is selecte
33690 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
336a0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
336b0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a    The following.
336c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
336d0 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  ns are available
336e0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63   in the SQLite c
336f0 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ore:.**.** <ul>.
33700 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
33710 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c  _MUTEX_OS2.** <l
33720 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
33730 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69  X_PTHREAD.** <li
33740 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
33750 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _W32.** <li>   S
33760 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
33770 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
33780 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
33790 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61  _NOOP implementa
337a0 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66  tion is a set of
337b0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61   routines.** tha
337c0 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c  t does no real l
337d0 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70  ocking and is ap
337e0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
337f0 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  e in.** a single
33800 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
33810 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49  ation.  The SQLI
33820 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
33830 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
33840 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
33850 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
33860 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
33870 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
33880 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
33890 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
338a0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69  s..**.** If SQLi
338b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
338c0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
338d0 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
338e0 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
338f0 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
33900 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
33910 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
33920 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
33930 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
33940 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
33950 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69   library. In thi
33960 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70  s case the.** ap
33970 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
33980 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d  upply a custom m
33990 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
339a0 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ion using the.**
339b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
339c0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66  MUTEX] option of
339d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
339e0 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  fig() function.*
339f0 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67  * before calling
33a00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
33a10 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68  ize() or any oth
33a20 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  er public sqlite
33a30 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  3_.** function t
33a40 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  hat calls sqlite
33a50 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
33a60 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54  **.** {H17011} T
33a70 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
33a80 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
33a90 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
33aa0 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
33ab0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
33ac0 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20  to it. {H17012} 
33ad0 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  If it returns NU
33ae0 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73  LL.** that means
33af0 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f   that a mutex co
33b00 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63  uld not be alloc
33b10 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53  ated. {H17013} S
33b20 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
33b30 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
33b40 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
33b50 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65  or. {H17014} The
33b60 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
33b70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
33b80 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20  loc() is one of 
33b90 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
33ba0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  nstants:.**.** <
33bb0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
33bc0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
33bd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
33be0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
33bf0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
33c00 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
33c10 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ER.** <li>  SQLI
33c20 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
33c30 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  MEM.** <li>  SQL
33c40 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
33c50 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _MEM2.** <li>  S
33c60 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
33c70 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20  IC_PRNG.** <li> 
33c80 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
33c90 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e  ATIC_LRU.** <li>
33ca0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
33cb0 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f  TATIC_LRU2.** </
33cc0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ul>.**.** {H1701
33cd0 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f  5} The first two
33ce0 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65   constants cause
33cf0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
33d00 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65  lloc() to create
33d10 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e  .** a new mutex.
33d20 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20    The new mutex 
33d30 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65  is recursive whe
33d40 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
33d50 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75  ECURSIVE.** is u
33d60 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65  sed but not nece
33d70 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20  ssarily so when 
33d80 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
33d90 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d  T is used. {END}
33da0 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
33db0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
33dc0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
33dd0 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
33de0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
33df0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
33e00 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
33e10 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
33e20 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
33e30 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75  to.  {H17016} Bu
33e40 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e  t SQLite will on
33e50 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
33e60 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
33e70 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
33e80 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
33e90 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20  ne.  {END} If a 
33ea0 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
33eb0 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
33ec0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
33ed0 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
33ee0 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
33ef0 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
33f00 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
33f10 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
33f20 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
33f30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
33f40 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37  T..**.** {H17017
33f50 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f  } The other allo
33f60 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74  wed parameters t
33f70 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
33f80 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74  alloc() each ret
33f90 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
33fa0 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
33fb0 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
33fc0 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74  {END}  Four stat
33fd0 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a  ic mutexes are.*
33fe0 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75  * used by the cu
33ff0 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66  rrent version of
34000 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65   SQLite.  Future
34010 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
34020 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61  ite.** may add a
34030 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63  dditional static
34040 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69   mutexes.  Stati
34050 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f  c mutexes are fo
34060 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73  r internal.** us
34070 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79  e by SQLite only
34080 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
34090 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20  that use SQLite 
340a0 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a  mutexes should.*
340b0 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64  * use only the d
340c0 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72  ynamic mutexes r
340d0 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54  eturned by SQLIT
340e0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a  E_MUTEX_FAST or.
340f0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
34100 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a  RECURSIVE..**.**
34110 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74   {H17018} Note t
34120 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
34130 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
34140 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
34150 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
34160 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
34170 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
34180 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
34190 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
341a0 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
341b0 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
341c0 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37  very call.  {H17
341d0 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65  034} But for the
341e0 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
341f0 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65   types, the same
34200 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e   mutex is return
34210 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ed on every call
34220 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65   that has.** the
34230 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65   same type numbe
34240 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39  r..**.** {H17019
34250 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
34260 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
34270 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
34280 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
34290 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
342a0 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d   mutex. {H17020}
342b0 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66   SQLite is caref
342c0 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ul to deallocate
342d0 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69   every.** dynami
342e0 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20  c mutex that it 
342f0 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30  allocates. {A170
34300 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20  21} The dynamic 
34310 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
34320 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
34330 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
34340 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32  located. {A17022
34350 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  } Attempting to 
34360 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61  deallocate a sta
34370 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73  tic.** mutex res
34380 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
34390 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37  d behavior. {H17
343a0 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65  023} SQLite neve
343b0 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a  r deallocates.**
343c0 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e   a static mutex.
343d0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
343e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
343f0 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74  nter() and sqlit
34400 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72  e3_mutex_try() r
34410 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a  outines attempt.
34420 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75  ** to enter a mu
34430 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66  tex. {H17024} If
34440 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
34450 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69  is already withi
34460 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20  n the mutex,.** 
34470 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
34480 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b  ter() will block
34490 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
344a0 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65  ex_try() will re
344b0 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42  turn.** SQLITE_B
344c0 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54  USY. {H17025}  T
344d0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
344e0 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  _try() interface
344f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
34500 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63  _OK].** upon suc
34510 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20  cessful entry.  
34520 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73  {H17026} Mutexes
34530 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
34540 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
34550 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20  ECURSIVE can be 
34560 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  entered multiple
34570 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61   times by the sa
34580 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48  me thread..** {H
34590 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63  17027} In such c
345a0 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74  ases the,.** mut
345b0 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65  ex must be exite
345c0 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65  d an equal numbe
345d0 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72  r of times befor
345e0 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  e another thread
345f0 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20  .** can enter.  
34600 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20  {A17028} If the 
34610 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65  same thread trie
34620 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f  s to enter any o
34630 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
34640 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20  mutex more than 
34650 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69  once, the behavi
34660 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
34670 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c  .** {H17029} SQL
34680 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
34690 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
346a0 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
346b0 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
346c0 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79  s..**.** Some sy
346d0 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70  stems (for examp
346e0 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20  le, Windows 95) 
346f0 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74  do not support t
34700 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
34710 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73  implemented by s
34720 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
34730 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79  ().  On those sy
34740 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d  stems, sqlite3_m
34750 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69  utex_try().** wi
34760 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
34770 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b   SQLITE_BUSY.  {
34780 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69  H17030} The SQLi
34790 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65  te core only eve
347a0 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65  r uses.** sqlite
347b0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73  3_mutex_try() as
347c0 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e   an optimization
347d0 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65   so this is acce
347e0 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ptable behavior.
347f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20  .**.** {H17031} 
34800 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
34810 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e  x_leave() routin
34820 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20  e exits a mutex 
34830 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76  that was.** prev
34840 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62  iously entered b
34850 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
34860 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65  d.  {A17032} The
34870 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
34880 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65  undefined if the
34890 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75   mutex is not cu
348a0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
348b0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e  by the.** callin
348c0 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e  g thread or is n
348d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c  ot currently all
348e0 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33  ocated.  {H17033
348f0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a  } SQLite will.**
34900 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72   never do either
34910 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66  . {END}.**.** If
34920 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
34930 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
34940 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f  nter(), sqlite3_
34950 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a  mutex_try(), or.
34960 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
34970 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55  _leave() is a NU
34980 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
34990 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69   all three routi
349a0 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73  nes.** behave as
349b0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53   no-ops..**.** S
349c0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
349d0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
349e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
349f0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
34a00 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
34a10 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
34a20 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
34a30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
34a40 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
34a50 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34a60 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
34a70 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
34a80 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
34a90 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
34aa0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
34ab0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
34ac0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
34ad0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34ae0 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62  Mutex Methods Ob
34af0 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53  ject {H17120} <S
34b00 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20130>.** EXPERI
34b10 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
34b20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
34b30 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
34b40 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
34b50 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
34b60 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
34b70 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
34b80 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
34b90 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
34ba0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34bb0 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
34bc0 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
34bd0 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
34be0 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
34bf0 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
34c00 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
34c10 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34c20 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
34c30 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
34c40 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
34c50 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
34c60 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
34c70 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
34c80 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
34c90 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
34ca0 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
34cb0 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
34cc0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
34cd0 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
34ce0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
34cf0 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
34d00 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
34d10 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
34d20 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
34d30 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
34d40 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
34d50 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
34d60 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
34d70 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
34d80 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
34d90 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
34da0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
34db0 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
34dc0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
34dd0 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
34de0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75  n..**.** The xMu
34df0 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64  texInit method d
34e00 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
34e10 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f  tructure is invo
34e20 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ked as.** part o
34e30 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c  f system initial
34e40 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73  ization by the s
34e50 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
34e60 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  e() function..**
34e70 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d   {H17001} The xM
34e80 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65  utexInit routine
34e90 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64   shall be called
34ea0 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20   by SQLite once 
34eb0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65  for each.** effe
34ec0 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73  ctive call to [s
34ed0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
34ee0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e()]..**.** The 
34ef0 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64  xMutexEnd method
34f00 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
34f10 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e   structure is in
34f20 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  voked as.** part
34f30 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64   of system shutd
34f40 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74  own by the sqlit
34f50 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75  e3_shutdown() fu
34f60 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69  nction. The.** i
34f70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34f80 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20   this method is 
34f90 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65  expected to rele
34fa0 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64  ase all outstand
34fb0 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ing.** resources
34fc0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65   obtained by the
34fd0 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69   mutex methods i
34fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65  mplementation, e
34ff0 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f  specially.** tho
35000 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74  se obtained by t
35010 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65  he xMutexInit me
35020 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54  thod. {H17003} T
35030 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a  he xMutexEnd().*
35040 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  * interface shal
35050 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  l be invoked onc
35060 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20  e for each call 
35070 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  to [sqlite3_shut
35080 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  down()]..**.** T
35090 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76  he remaining sev
350a0 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  en methods defin
350b0 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
350c0 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f  ture (xMutexAllo
350d0 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65  c,.** xMutexFree
350e0 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78  , xMutexEnter, x
350f0 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78  MutexTry, xMutex
35100 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c  Leave, xMutexHel
35110 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e  d and.** xMutexN
35120 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e  otheld) implemen
35130 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  t the following 
35140 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70  interfaces (resp
35150 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a  ectively):.**.**
35160 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
35170 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
35180 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  alloc()] </li>.*
35190 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
351a0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d  e3_mutex_free()]
351b0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
351c0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
351d0 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a  _enter()] </li>.
351e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
351f0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d  te3_mutex_try()]
35200 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
35210 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
35220 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a  _leave()] </li>.
35230 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
35240 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
35250 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
35260 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
35270 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c  x_notheld()] </l
35280 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
35290 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65  * The only diffe
352a0 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68  rence is that th
352b0 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  e public sqlite3
352c0 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65  _XXX functions e
352d0 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f  numerated.** abo
352e0 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ve silently igno
352f0 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f  re any invocatio
35300 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e  ns that pass a N
35310 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
35320 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69  ead.** of a vali
35330 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20  d mutex handle. 
35340 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
35350 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f  ons of the metho
35360 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  ds defined.** by
35370 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
35380 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64  are not required
35390 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20   to handle this 
353a0 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74  case, the result
353b0 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20  s.** of passing 
353c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
353d0 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69  nstead of a vali
353e0 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61  d mutex handle a
353f0 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20  re undefined.** 
35400 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65  (i.e. it is acce
35410 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64  ptable to provid
35420 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e an implementat
35430 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c  ion that segfaul
35440 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70  ts if.** it is p
35450 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69  assed a NULL poi
35460 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  nter)..*/.typede
35470 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
35480 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73  _mutex_methods s
35490 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
354a0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
354b0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
354c0 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  ds {.  int (*xMu
354d0 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a  texInit)(void);.
354e0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e    int (*xMutexEn
354f0 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69  d)(void);.  sqli
35500 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75  te3_mutex *(*xMu
35510 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a  texAlloc)(int);.
35520 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46    void (*xMutexF
35530 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ree)(sqlite3_mut
35540 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
35550 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c  xMutexEnter)(sql
35560 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
35570 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79   int (*xMutexTry
35580 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
35590 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  *);.  void (*xMu
355a0 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65  texLeave)(sqlite
355b0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e  3_mutex *);.  in
355c0 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28  t (*xMutexHeld)(
355d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
355e0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
355f0 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33  Notheld)(sqlite3
35600 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f  _mutex *);.};../
35610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
35620 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f  utex Verificatio
35630 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30  n Routines {H170
35640 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33  80} <S20130> <S3
35650 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0800>.**.** The 
35660 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
35670 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ld() and sqlite3
35680 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
35690 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
356a0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
356b0 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28  e inside assert(
356c0 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48  ) statements. {H
356d0 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74  17081} The SQLit
356e0 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20  e core.** never 
356f0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
35700 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64  nes except insid
35710 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e  e an assert() an
35720 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  d applications.*
35730 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f  * are advised to
35740 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64   follow the lead
35750 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b   of the core.  {
35760 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65  H17082} The core
35770 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65   only.** provide
35780 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
35790 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  s for these rout
357a0 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20  ines when it is 
357b0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
357c0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55   the SQLITE_DEBU
357d0 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37  G flag.  {A17087
357e0 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78  } External mutex
357f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35800 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71  .** are only req
35810 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
35820 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35830 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  if SQLITE_DEBUG 
35840 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e  is.** defined an
35850 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e  d if NDEBUG is n
35860 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ot defined..**.*
35870 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65  * {H17083} These
35880 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
35890 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20   return true if 
358a0 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65  the mutex in the
358b0 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  ir argument.** i
358c0 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65  s held or not he
358d0 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  ld, respectively
358e0 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67  , by the calling
358f0 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b   thread..**.** {
35900 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c  X17084} The impl
35910 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f  ementation is no
35920 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  t required to pr
35930 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20  ovided versions 
35940 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74  of these.** rout
35950 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c  ines that actual
35960 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20  ly work. If the 
35970 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64  implementation d
35980 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
35990 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69  working.** versi
359a0 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ons of these rou
359b0 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64  tines, it should
359c0 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64   at least provid
359d0 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77  e stubs that alw
359e0 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72  ays.** return tr
359f0 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64  ue so that one d
35a00 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72  oes not get spur
35a10 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66  ious assertion f
35a20 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ailures..**.** {
35a30 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61  H17085} If the a
35a40 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
35a50 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
35a60 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35a70 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f  r then.** the ro
35a80 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
35a90 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68  urn 1.  {END} Th
35aa0 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72  is seems counter
35ab0 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65  -intuitive since
35ac0 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20  .** clearly the 
35ad0 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20  mutex cannot be 
35ae0 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20  held if it does 
35af0 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20  not exist.  But 
35b00 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f  the.** the reaso
35b10 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73  n the mutex does
35b20 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65   not exist is be
35b30 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20  cause the build 
35b40 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20  is not.** using 
35b50 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65  mutexes.  And we
35b60 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65   do not want the
35b70 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69   assert() contai
35b80 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  ning the.** call
35b90 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
35ba0 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c  x_held() to fail
35bb0 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  , so a non-zero 
35bc0 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65  return is.** the
35bd0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69   appropriate thi
35be0 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30  ng to do.  {H170
35bf0 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  86} The sqlite3_
35c00 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a  mutex_notheld().
35c10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ** interface sho
35c20 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  uld also return 
35c30 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e  1 when given a N
35c40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
35c50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
35c60 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d  x_held(sqlite3_m
35c70 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
35c80 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
35c90 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  d(sqlite3_mutex*
35ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35cb0 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20  EF: Mutex Types 
35cc0 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30  {H17001} <H17000
35cd0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  >.**.** The [sql
35ce0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
35cf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61  ()] interface ta
35d00 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
35d10 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69  ument.** which i
35d20 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
35d30 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
35d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20  ..**.** The set 
35d50 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  of static mutexe
35d60 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  s may change fro
35d70 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c  m one SQLite rel
35d80 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  ease to the.** n
35d90 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
35da0 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65  ns that override
35db0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75   the built-in mu
35dc0 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62  tex logic must b
35dd0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f  e.** prepared to
35de0 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64   accommodate add
35df0 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d  itional static m
35e00 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  utexes..*/.#defi
35e10 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
35e20 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20  FAST            
35e30 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
35e40 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
35e50 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
35e60 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
35e70 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20  STATIC_MASTER   
35e80 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
35e90 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
35ea0 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73  EM       3  /* s
35eb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
35ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35ed0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
35ee0 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e  EM2      4  /* N
35ef0 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69  OT USED */.#defi
35f00 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
35f10 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20  STATIC_OPEN     
35f20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74   4  /* sqlite3Bt
35f30 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65  reeOpen() */.#de
35f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
35f50 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20  X_STATIC_PRNG   
35f60 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
35f70 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65  _random() */.#de
35f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
35f90 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20  X_STATIC_LRU    
35fa0 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67     6  /* lru pag
35fb0 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e  e list */.#defin
35fc0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
35fd0 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20  TATIC_LRU2      
35fe0 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c  7  /* lru page l
35ff0 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ist */../*.** CA
36000 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65  PI3REF: Retrieve
36010 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61   the mutex for a
36020 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36030 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48  tion {H17002} <H
36040 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  17000>.**.** Thi
36050 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
36060 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68  rns a pointer th
36070 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
36080 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a  ] object that .*
36090 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63  * serializes acc
360a0 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ess to the [data
360b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
360c0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72   given in the ar
360d0 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74  gument.** when t
360e0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
360f0 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65  de] is Serialize
36100 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68  d..** If the [th
36110 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
36120 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f   Single-thread o
36130 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74  r Multi-thread t
36140 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  hen this.** rout
36150 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
36160 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
36170 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
36180 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73  lite3_db_mutex(s
36190 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
361a0 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c   CAPI3REF: Low-L
361b0 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20  evel Control Of 
361c0 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b  Database Files {
361d0 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e  H11300} <S30800>
361e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20  .**.** {H11301} 
361f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  The [sqlite3_fil
36200 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
36210 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64  erface makes a d
36220 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68  irect call to th
36230 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  e.** xFileContro
36240 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65  l method for the
36250 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
36260 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73  hods] object ass
36270 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
36280 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
36290 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64  abase identified
362a0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
362b0 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32  rgument. {H11302
362c0 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  } The.** name of
362d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
362e0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
362f0 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ed to the databa
36300 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20  se by the.** <a 
36310 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63  href="lang_attac
36320 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f  h.html">ATTACH</
36330 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  a> SQL command t
36340 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a  hat opened the.*
36350 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31  * database. {H11
36360 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20  303} To control 
36370 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
36380 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20  e file, use the 
36390 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f  name "main".** o
363a0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
363b0 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74  . {H11304} The t
363c0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
363d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
363e0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72  is routine.** ar
363f0 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c  e passed directl
36400 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  y through to the
36410 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
36420 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a  d parameters of.
36430 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** the xFileCont
36440 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31  rol method.  {H1
36450 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e  1305} The return
36460 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46   value of the xF
36470 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65  ileControl.** me
36480 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65  thod becomes the
36490 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
364a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a   this routine..*
364b0 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66  *.** {H11306} If
364c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
364d0 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20  meter (zDbName) 
364e0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74  does not match t
364f0 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a  he name of any.*
36500 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  * open database 
36510 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54  file, then SQLIT
36520 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72  E_ERROR is retur
36530 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68  ned. {H11307} Th
36540 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  is error.** code
36550 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72   is not remember
36560 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20  ed and will not 
36570 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b  be recalled by [
36580 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
36590 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
365a0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31  3_errmsg()]. {A1
365b0 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c  1308} The underl
365c0 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f  ying xFileContro
365d0 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a  l method might.*
365e0 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51  * also return SQ
365f0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31  LITE_ERROR.  {A1
36600 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e  1309} There is n
36610 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67  o way to disting
36620 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20  uish between.** 
36630 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62  an incorrect zDb
36640 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49  Name and an SQLI
36650 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20  TE_ERROR return 
36660 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79  from the underly
36670 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74  ing.** xFileCont
36680 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44  rol method. {END
36690 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  }.**.** See also
366a0 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  : [SQLITE_FCNTL_
366b0 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e  LOCKSTATE].*/.in
366c0 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  t sqlite3_file_c
366d0 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c  ontrol(sqlite3*,
366e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
366f0 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  Name, int op, vo
36700 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
36710 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49  I3REF: Testing I
36720 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 30  nterface {H11400
36730 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
36740 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73   The sqlite3_tes
36750 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65  t_control() inte
36760 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
36770 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e   read out intern
36780 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53  al.** state of S
36790 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a  QLite and to inj
367a0 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20  ect faults into 
367b0 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69  SQLite for testi
367c0 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20  ng.** purposes. 
367d0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
367e0 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61  eter is an opera
367f0 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64  tion code that d
36800 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65  etermines.** the
36810 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67   number, meaning
36820 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20  , and operation 
36830 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  of all subsequen
36840 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  t parameters..**
36850 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
36860 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73  ce is not for us
36870 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  e by application
36880 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f  s.  It exists so
36890 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69  lely.** for veri
368a0 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63  fying the correc
368b0 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  t operation of t
368c0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
368d0 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a  y.  Depending.**
368e0 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69   on how the SQLi
368f0 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f  te library is co
36900 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74  mpiled, this int
36910 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74  erface might not
36920 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68   exist..**.** Th
36930 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
36940 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73   operation codes
36950 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73  , their meanings
36960 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  , the parameters
36970 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61  .** they take, a
36980 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20  nd what they do 
36990 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20  are all subject 
369a0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
369b0 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c  t notice..** Unl
369c0 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  ike most of the 
369d0 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73  SQLite API, this
369e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
369f0 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a   guaranteed to.*
36a00 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73  * operate consis
36a10 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20  tently from one 
36a20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
36a30 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ext..*/.int sqli
36a40 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c  te3_test_control
36a50 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a  (int op, ...);..
36a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36a70 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63  Testing Interfac
36a80 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65  e Operation Code
36a90 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34  s {H11410} <H114
36aa0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
36ab0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
36ac0 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f  e valid operatio
36ad0 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72  n code parameter
36ae0 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65  s used.** as the
36af0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
36b00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74  to [sqlite3_test
36b10 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a  _control()]..**.
36b20 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74  ** These paramet
36b30 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65  ers and their me
36b40 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65  anings are subje
36b50 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  ct to change.** 
36b60 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20  without notice. 
36b70 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72   These values ar
36b80 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75  e for testing pu
36b90 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20  rposes only..** 
36ba0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
36bb0 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20  uld not use any 
36bc0 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
36bd0 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73  ers or the.** [s
36be0 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74  qlite3_test_cont
36bf0 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
36c00 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
36c10 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e  ITE_TESTCTRL_PRN
36c20 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 20  G_SAVE          
36c30 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
36c40 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
36c50 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20  PRNG_RESTORE    
36c60 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
36c70 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
36c80 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20  RL_PRNG_RESET   
36c90 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
36ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
36cb0 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53  TCTRL_BITVEC_TES
36cc0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 38  T              8
36cd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36ce0 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49  TESTCTRL_FAULT_I
36cf0 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20  NSTALL          
36d00 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
36d10 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49  TE_TESTCTRL_BENI
36d20 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20  GN_MALLOC_HOOKS 
36d30 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
36d40 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
36d50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20  ENDING_BYTE     
36d60 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
36d70 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
36d80 4c 5f 41 53 53 45 52 54 20 20 20 20 20 20 20 20  L_ASSERT        
36d90 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
36da0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
36db0 43 54 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20  CTRL_ALWAYS     
36dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 33 0a               13.
36dd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36de0 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20   SQLite Runtime 
36df0 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20  Status {H17200} 
36e00 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S60200>.** EXPE
36e10 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
36e20 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
36e30 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
36e40 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73  e runtime status
36e50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
36e60 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72  about the prefor
36e70 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c  mance of SQLite,
36e80 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   and optionally 
36e90 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73  to reset various
36ea0 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61  .** highwater ma
36eb0 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  rks.  The first 
36ec0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
36ed0 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a  nteger code for.
36ee0 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20  ** the specific 
36ef0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61  parameter to mea
36f00 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65  sure.  Recognize
36f10 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a  d integer codes.
36f20 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f  ** are of the fo
36f30 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55  rm [SQLITE_STATU
36f40 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20  S_MEMORY_USED | 
36f50 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e  SQLITE_STATUS_..
36f60 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65  .]..** The curre
36f70 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  nt value of the 
36f80 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74  parameter is ret
36f90 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72  urned into *pCur
36fa0 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67  rent..** The hig
36fb0 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61  hest recorded va
36fc0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  lue is returned 
36fd0 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20  in *pHighwater. 
36fe0 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74   If the.** reset
36ff0 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68  Flag is true, th
37000 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72  en the highest r
37010 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72  ecord value is r
37020 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70  eset after.** *p
37030 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69  Highwater is wri
37040 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d  tten. Some param
37050 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63  eters do not rec
37060 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a  ord the highest.
37070 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74  ** value.  For t
37080 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a  hose parameters.
37090 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72  ** nothing is wr
370a0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67  itten into *pHig
370b0 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72  hwater and the r
370c0 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f  esetFlag is igno
370d0 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61  red..** Other pa
370e0 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20  rameters record 
370f0 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74  only the highwat
37100 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20  er mark and not 
37110 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76  the current.** v
37120 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65  alue.  For these
37130 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65   latter paramete
37140 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72  rs nothing is wr
37150 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72  itten into *pCur
37160 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rent..**.** This
37170 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37180 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75   SQLITE_OK on su
37190 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d  ccess and a non-
371a0 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  zero.** [error c
371b0 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
371c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
371d0 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ine is threadsaf
371e0 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f  e but is not ato
371f0 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69  mic.  This routi
37200 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64  ne can.** called
37210 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72   while other thr
37220 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67  eads are running
37230 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66   the same or dif
37240 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a  ferent SQLite.**
37250 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
37260 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73  wever the values
37270 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43   returned in *pC
37280 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70  urrent and.** *p
37290 48 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63  Highwater reflec
372a0 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
372b0 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72  SQLite at differ
372c0 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69  ent points in ti
372d0 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20  me.** and it is 
372e0 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e  possible that an
372f0 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67  other thread mig
37300 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61  ht change the pa
37310 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65  rameter.** in be
37320 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20  tween the times 
37330 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61  when *pCurrent a
37340 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61  nd *pHighwater a
37350 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a  re written..**.*
37360 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
37370 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29  ite3_db_status()
37380 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ].*/.SQLITE_EXPE
37390 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
373a0 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20  ite3_status(int 
373b0 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e  op, int *pCurren
373c0 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74  t, int *pHighwat
373d0 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61  er, int resetFla
373e0 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  g);.../*.** CAPI
373f0 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72  3REF: Status Par
37400 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d  ameters {H17250}
37410 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50   <H17200>.** EXP
37420 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
37430 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
37440 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74  nstants designat
37450 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69  e various run-ti
37460 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65  me status parame
37470 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  ters.** that can
37480 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20   be returned by 
37490 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
374a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  )]..**.** <dl>.*
374b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41  * <dt>SQLITE_STA
374c0 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c  TUS_MEMORY_USED<
374d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
374e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
374f0 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74  e current amount
37500 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b   of memory check
37510 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20  ed out.** using 
37520 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37530 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63  )], either direc
37540 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c  tly or indirectl
37550 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72  y.  The.** figur
37560 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73  e includes calls
37570 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65   made to [sqlite
37580 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74  3_malloc()] by t
37590 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
375a0 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d  * and internal m
375b0 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74  emory usage by t
375c0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
375d0 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f  y.  Scratch memo
375e0 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64  ry.** controlled
375f0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
37600 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
37610 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63  auxiliary page-c
37620 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63  ache.** memory c
37630 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51  ontrolled by [SQ
37640 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
37650 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e  CACHE] is not in
37660 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69  cluded in.** thi
37670 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  s parameter.  Th
37680 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65  e amount returne
37690 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20  d is the sum of 
376a0 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  the allocation.*
376b0 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72  * sizes as repor
376c0 74 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65  ted by the xSize
376d0 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69   method in [sqli
376e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
376f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
37700 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d  >SQLITE_STATUS_M
37710 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a  ALLOC_SIZE</dt>.
37720 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
37730 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68  meter records th
37740 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79  e largest memory
37750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
37760 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f  est.** handed to
37770 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37780 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
37790 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74  realloc()] (or t
377a0 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  heir.** internal
377b0 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20   equivalents).  
377c0 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72  Only the value r
377d0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a  eturned in the.*
377e0 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61  * *pHighwater pa
377f0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
37800 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73  te3_status()] is
37810 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a   of interest.  .
37820 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69  ** The value wri
37830 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70  tten into the *p
37840 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65  Current paramete
37850 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c  r is undefined.<
37860 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
37870 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47  QLITE_STATUS_PAG
37880 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e  ECACHE_USED</dt>
37890 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
378a0 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
378b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
378c0 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74  es used out of t
378d0 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65  he.** [pagecache
378e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
378f0 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66  r] that was conf
37900 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a  igured using .**
37910 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
37920 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65  PAGECACHE].  The
37930 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e  .** value return
37940 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20  ed is in pages, 
37950 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  not in bytes.</d
37960 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
37970 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43  ITE_STATUS_PAGEC
37980 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64  ACHE_OVERFLOW</d
37990 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
379a0 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73  arameter returns
379b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
379c0 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63  ytes of page cac
379d0 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  he.** allocation
379e0 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74   which could not
379f0 20 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62   be statisfied b
37a00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  y the [SQLITE_CO
37a10 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a  NFIG_PAGECACHE].
37a20 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68  ** buffer and wh
37a30 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76  ere forced to ov
37a40 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74  erflow to [sqlit
37a50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
37a60 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76  he.** returned v
37a70 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c  alue includes al
37a80 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f  locations that o
37a90 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73  verflowed becaus
37aa0 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20  e they.** where 
37ab0 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20  too large (they 
37ac0 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e  were larger than
37ad0 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65   the "sz" parame
37ae0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
37af0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
37b00 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74  HE]) and allocat
37b10 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c  ions that overfl
37b20 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20  owed because.** 
37b30 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66  no space was lef
37b40 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61  t in the page ca
37b50 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  che.</dd>.**.** 
37b60 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
37b70 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45  S_PAGECACHE_SIZE
37b80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
37b90 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f  s parameter reco
37ba0 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  rds the largest 
37bb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37bc0 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e  n request.** han
37bd0 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68  ded to [pagecach
37be0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
37bf0 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76  or].  Only the v
37c00 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e  alue returned in
37c10 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61   the.** *pHighwa
37c20 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ter parameter to
37c30 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
37c40 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65  ()] is of intere
37c50 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c  st.  .** The val
37c60 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ue written into 
37c70 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61  the *pCurrent pa
37c80 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66  rameter is undef
37c90 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
37ca0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54   <dt>SQLITE_STAT
37cb0 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c  US_SCRATCH_USED<
37cc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
37cd0 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72   parameter retur
37ce0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
37cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65   allocations use
37d00 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20  d out of the.** 
37d10 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20  [scratch memory 
37d20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
37d30 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  gured using.** [
37d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
37d50 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c  RATCH].  The val
37d60 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69  ue returned is i
37d70 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e  n allocations, n
37d80 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20  ot.** in bytes. 
37d90 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20   Since a single 
37da0 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20  thread may only 
37db0 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68  have one scratch
37dc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
37dd0 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69  utstanding at ti
37de0 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74  me, this paramet
37df0 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20  er also reports 
37e00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  the number of th
37e10 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73  reads.** using s
37e20 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74  cratch memory at
37e30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c   the same time.<
37e40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
37e50 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52  QLITE_STATUS_SCR
37e60 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64  ATCH_OVERFLOW</d
37e70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
37e80 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73  arameter returns
37e90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
37ea0 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20  ytes of scratch 
37eb0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
37ec0 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64  tion which could
37ed0 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69   not be statisfi
37ee0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
37ef0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
37f00 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20  ].** buffer and 
37f10 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20  where forced to 
37f20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c  overflow to [sql
37f30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
37f40 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72   The values.** r
37f50 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20  eturned include 
37f60 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73  overflows becaus
37f70 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  e the requested 
37f80 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74  allocation was t
37f90 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68  oo.** larger (th
37fa0 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74  at is, because t
37fb0 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c  he requested all
37fc0 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67  ocation was larg
37fd0 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22  er than the.** "
37fe0 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f  sz" parameter to
37ff0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
38000 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65  SCRATCH]) and be
38010 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68  cause no scratch
38020 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73   buffer.** slots
38030 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e   were available.
38040 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
38050 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
38060 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f  S_SCRATCH_SIZE</
38070 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
38080 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64  parameter record
38090 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65  s the largest me
380a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
380b0 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65  request.** hande
380c0 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65  d to [scratch me
380d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e  mory allocator].
380e0 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65    Only the value
380f0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65   returned in the
38100 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20  .** *pHighwater 
38110 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
38120 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20  lite3_status()] 
38130 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20  is of interest. 
38140 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77   .** The value w
38150 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
38160 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65  *pCurrent parame
38170 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ter is undefined
38180 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
38190 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50  >SQLITE_STATUS_P
381a0 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e  ARSER_STACK</dt>
381b0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
381c0 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74  ameter records t
381d0 68 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65  he deepest parse
381e0 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20  r stack.  It is 
381f0 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66  only.** meaningf
38200 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ul if SQLite is 
38210 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59  compiled with [Y
38220 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45  YTRACKMAXSTACKDE
38230 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  PTH].</dd>.** </
38240 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74  dl>.**.** New st
38250 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20  atus parameters 
38260 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f  may be added fro
38270 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a  m time to time..
38280 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38290 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f  E_STATUS_MEMORY_
382a0 55 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a  USED          0.
382b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
382c0 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f  TATUS_PAGECACHE_
382d0 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65  USED       1.#de
382e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
382f0 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45  US_PAGECACHE_OVE
38300 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e  RFLOW   2.#defin
38310 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
38320 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20  SCRATCH_USED    
38330 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
38340 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52  QLITE_STATUS_SCR
38350 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20  ATCH_OVERFLOW   
38360 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
38370 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43  TE_STATUS_MALLOC
38380 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35  _SIZE          5
38390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
383a0 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54  STATUS_PARSER_ST
383b0 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64  ACK         6.#d
383c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
383d0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49  TUS_PAGECACHE_SI
383e0 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69  ZE       7.#defi
383f0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ne SQLITE_STATUS
38400 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20  _SCRATCH_SIZE   
38410 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43        8../*.** C
38420 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
38430 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61  e Connection Sta
38440 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36  tus {H17500} <S6
38450 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
38460 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ENTAL.**.** This
38470 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
38480 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72  ed to retrieve r
38490 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e  untime status in
384a0 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62  formation .** ab
384b0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61  out a single [da
384c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
384d0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
384e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
384f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
38500 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20  ction object to 
38510 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  be interrogated.
38520 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
38530 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20  ument.** is the 
38540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74  parameter to int
38550 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65  errogate.  Curre
38560 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61  ntly, the only a
38570 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20  llowed value.** 
38580 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70  for the second p
38590 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c  arameter is [SQL
385a0 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f  ITE_DBSTATUS_LOO
385b0 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a  KASIDE_USED]..**
385c0 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   Additional opti
385d0 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ons will likely 
385e0 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65  appear in future
385f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
38600 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ite..**.** The c
38610 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
38620 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61  the requested pa
38630 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74  rameter is writt
38640 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a  en into *pCur.**
38650 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74   and the highest
38660 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76   instantaneous v
38670 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20  alue is written 
38680 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49  into *pHiwtr.  I
38690 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c  f.** the resetFl
386a0 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  g is true, then 
386b0 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74  the highest inst
386c0 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20  antaneous value 
386d0 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b  is.** reset back
386e0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72   down to the cur
386f0 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rent value..**.*
38700 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
38710 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61  ite3_status()] a
38720 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  nd [sqlite3_stmt
38730 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53  _status()]..*/.S
38740 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
38750 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
38760 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33  b_status(sqlite3
38770 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a  *, int op, int *
38780 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74  pCur, int *pHiwt
38790 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29  r, int resetFlg)
387a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
387b0 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65  F: Status Parame
387c0 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73  ters for databas
387d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48  e connections {H
387e0 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a  17520} <H17500>.
387f0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
38800 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72  **.** Status ver
38810 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  bs for [sqlite3_
38820 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a  db_status()]..**
38830 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74